Getting Started

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

The Events API is CRUD for itinerary events. An event can be attached to one or more trips, and the user who creates it becomes its planner — the single user empowered to update or delete it globally. Everything lives under /v1/events/.

Base URL

Authentication in one line

Authenticate with the first-party session cookie (session_token) or a bearer token sent as Authorization: Bearer <token>. Reads and creates require trip membership; updates and deletes are planner-only. See authentication.md.

Create your first event

curl -s -X POST "https://api.travelmode.ai/v1/events" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "activity",
    "title": "Colosseum guided tour",
    "date": "2026-07-03",
    "time": "10:00",
    "description": "Skip-the-line small group tour",
    "location": "Piazza del Colosseo, Rome",
    "importance": "important",
    "attach": { "trip_ids": [42] }
  }'

{
  "event_id": 905,
  "type": "activity",
  "title": "Colosseum guided tour",
  "date": "2026-07-03",
  "time": "10:00",
  "planner_user_id": "usr_8c1f",
  "attached_trips": [42],
  "revision": 0
}

You must have access to every trip listed in attach.trip_ids, or the whole request is rejected with 403.

Read it back

curl -s "https://api.travelmode.ai/v1/events/905" \
  -H "Authorization: Bearer <token>"

Response and error shapes

Endpoints return resource objects directly (no { data, meta } envelope). Errors are { "error": <string | array> }. A soft-deleted event returns 410 Gone. See errors.md.

Where next

• events.md — the full create / read / update / delete reference.
• openapi.yaml — the full machine-readable contract.