Travelmode Agent Runs API
Last verified: 2026-06-20 (Task #390 — User APIs documentation).
This directory holds the public contract for the Agent Runs feature of the Travelmode developer platform. The OpenAPI spec is the source of truth; the markdown guides add narrative guidance and worked examples.
A run is an asynchronous execution of the planning agent over one trip. It moves through phases, emits a sequenced stream of events, and produces typed artifacts (candidates, entities, conflicts, draft operations, proposals).
Auth model: these endpoints use the end-user auth model (session cookie or mobile / extension bearer token), not a
tm_developer key. Runs are owner-scoped — only the user who created a run may read, stream, or control it. Seeauthentication.md.
Hosted developer portal
| URL | What it serves |
|---|---|
/developers/agent-runs | Agent Runs feature overview (this README). |
/developers/agent-runs/<slug> | Each markdown guide (getting-started, authentication, lifecycle, streaming, artifacts, errors). |
/developers/agent-runs/reference | Interactive OpenAPI 3.1 reference with Authorize and Try It. |
/developers/agent-runs/openapi.yaml | Canonical YAML spec, served raw. |
/developers/agent-runs/openapi.json | Same spec, JSON-encoded for tooling. |
Files
| File | What it contains |
|---|---|
openapi.yaml | OpenAPI 3.1 spec — every Agent Runs path, schema, and example. Validated by npm run check:openapi. |
getting-started.md | Base URL, auth quickstart, create your first run. |
authentication.md | Session cookie, bearer token, and owner scoping. |
lifecycle.md | Statuses, phases, and control actions. |
streaming.md | The SSE stream, event polling, and the since cursor. |
artifacts.md | Typed run outputs and pinning. |
errors.md | Status codes and the error response shape. |
Quick links
- Response shape: resource objects (no
{ data, meta }envelope). - Error shape:
{ "error": <string | array> }— seeerrors.md. - The SSE stream is cookie-only — see
streaming.md.
Validating the spec
npm run check:openapi