Getting Started

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

The Agent Runs API lets you start AI planning runs over a trip, observe their progress (by polling or via a live SSE stream), control their lifecycle, and read the typed artifacts they produce. Everything lives under /v1/agent-runs/.

Base URL

Authentication in one line

Authenticate with the first-party session cookie (session_token) or a bearer token (mobile access token / extension session token) sent as Authorization: Bearer <token>. Runs are owner-scoped: only the user who created a run may access it, and creating a run requires that you own the target trip. See authentication.md.

Create your first run

curl -s -X POST "https://api.travelmode.ai/v1/agent-runs" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "tripId": 42, "triggerMessage": "Plan 3 days in Rome" }'

{
  "run": {
    "id": "9f2a1c7e-…",
    "tripId": 42,
    "userId": "usr_8c1f",
    "status": "pending",
    "phase": null,
    "lastEventSequence": 0,
    "createdAt": "2026-06-20T12:00:00.000Z"
  }
}

The run starts in pending. Drive it with the control endpoint:

curl -s -X POST "https://api.travelmode.ai/v1/agent-runs/9f2a1c7e-…/control" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "action": "start" }'

Watch it progress

Poll incrementally with the events endpoint, or open the live SSE stream — both are covered in streaming.md.

curl -s "https://api.travelmode.ai/v1/agent-runs/9f2a1c7e-…/events?since=0" \
  -H "Authorization: Bearer <token>"

Response and error shapes

Endpoints return resource objects directly (no { data, meta } envelope). Errors are { "error": <string | array> }. See errors.md.

Where next

• lifecycle.md — statuses, phases, control actions.
• streaming.md — SSE stream and polling.
• artifacts.md — typed run outputs.
• openapi.yaml — the full machine-readable contract.