Getting Started

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

The Trips & Itinerary API lets you read a trip's events, fast-forward a local cache with revision diffs, apply atomic timeline operations, manage collaborators, and drive the AI proposal workflow. Everything lives under /v1/trips/.

Base URL

The /v1/ prefix is part of the path.

Authentication in one line

These are user endpoints, not developer-key endpoints. Authenticate with either:

• the first-party session cookie (session_token) set when a user logs in to the web app, or
• a bearer token (a mobile access token or browser-extension session token) sent as Authorization: Bearer <token>.

Access to each trip is then gated by trip membership and role. See authentication.md for the full model.

Your first request

Read a trip's itinerary (replace 42 with a trip you can access):

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",
      "location": "John F. Kennedy International Airport",
      "booking_status": "planned_unbooked",
      "importance": "anchor"
    }
  ]
}

Note the revision field — it is the concurrency token you pass back as base_revision when you apply an operation. See operations.md.

Response and error shapes

These endpoints return resource objects directly — there is no { data, meta } envelope (that is the developer-key APIs' convention). Errors are returned as { "error": <string | array> } with an appropriate HTTP status. See errors.md.

Where next

• itinerary.md — full itinerary, diffs, and summary.
• operations.md — revision-tracked mutations.
• permissions.md — collaborator roles.
• proposals.md — the AI proposal workflow.
• openapi.yaml — the full machine-readable contract.