Itinerary

Last verified: 2026-06-20 (Task #390 — User APIs documentation).

Three read-only endpoints expose a trip's itinerary at increasing levels of compactness. All three require trip membership (any role).

Full itinerary

GET /v1/trips/{tripId}/itinerary

Returns the trip's current revision, status, event_count, and the full events array ordered by start time.

curl -s "https://api.travelmode.ai/v1/trips/42/itinerary" \
  -H "Authorization: Bearer <token>"

{
  "trip_id": 42,
  "revision": 7,
  "status": "planning",
  "event_count": 2,
  "events": [
    { "id": 901, "type": "flight", "title": "JFK → FCO", "date": "2026-07-01", "time": "18:30" },
    { "id": 902, "type": "accommodation", "title": "Hotel Quirinale", "date": "2026-07-02", "time": "15:00" }
  ]
}

Keep the revision — you pass it as base_revision when applying operations (see operations.md).

Revision diff

GET /v1/trips/{tripId}/itinerary/diff?since_revision={n}

Returns the timeline operations applied since since_revision, plus the net per-event diffs, so a client that already holds revision n can fast-forward without re-reading the whole itinerary.

curl -s "https://api.travelmode.ai/v1/trips/42/itinerary/diff?since_revision=5" \
  -H "Authorization: Bearer <token>"

{
  "trip_id": 42,
  "since_revision": 5,
  "current_revision": 7,
  "operations": [
    { "op_id": "…", "operation_type": "move_event", "result_revision": 6, "affected_event_ids": [901] }
  ],
  "event_diffs": [ { "event_id": 901, "change": "updated" } ]
}

If since_revision already equals current_revision, operations and event_diffs come back empty.

Compact summary

GET /v1/trips/{tripId}/itinerary/summary

Returns an agent-friendly digest: counts by event type, geographic bounds, detected scheduling conflicts, and a compact event list.

{
  "trip_id": 42,
  "revision": 7,
  "status": "planning",
  "event_count": 2,
  "events_by_type": { "flight": 1, "accommodation": 1 },
  "trip_bounds": { "min_lat": 40.6, "max_lat": 41.9, "min_lng": 2.0, "max_lng": 12.5 },
  "conflicts": [],
  "conflict_count": 0,
  "compact_events": [ { "id": 901, "type": "flight", "date": "2026-07-01" } ]
}

Use the summary to drive UI badges and agent prompts cheaply; fall back to the full itinerary when you need every field.