Travelmode Trips & Itinerary API
Last verified: 2026-06-20 (Task #390 — User APIs documentation).
This directory holds the public contract for the Trips & Itinerary feature of the Travelmode developer platform. The OpenAPI spec is the source of truth; the markdown guides below add narrative guidance and worked examples.
Auth model: unlike the developer-key features (Weather, Visa, Platform), these endpoints use the end-user auth model — a logged-in session cookie or a mobile / extension bearer token identifies the caller, and access is gated by trip membership and role, not a
tm_API key. Seeauthentication.md.
Hosted developer portal
Every file in this directory is published under the Trips feature of the
portal, e.g. /developers/trips on the deployed app:
| URL | What it serves |
|---|---|
/developers/trips | Trips feature overview (this README). |
/developers/trips/<slug> | Each markdown guide (getting-started, authentication, itinerary, operations, permissions, proposals, errors). |
/developers/trips/reference | Interactive OpenAPI 3.1 reference (Stoplight Elements) with built-in Authorize and Try It panels. |
/developers/trips/openapi.yaml | Canonical YAML spec, served raw. |
/developers/trips/openapi.json | Same spec, JSON-encoded for tooling. |
Files
| File | What it contains |
|---|---|
openapi.yaml | OpenAPI 3.1 spec — every Trips path, schema, and example. Validated by npm run check:openapi. |
getting-started.md | Base URL, auth quickstart, your first itinerary read. |
authentication.md | Session cookie, bearer token, and trip role gating. |
itinerary.md | Reading the full itinerary, revision diffs, and the compact summary. |
operations.md | Atomic, revision-tracked timeline mutations and conflict handling. |
permissions.md | Listing, granting, and revoking collaborator roles. |
proposals.md | Listing, creating, accepting, and rejecting AI proposals. |
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. - Auth: session cookie or
Authorization: Bearer <token>— seeauthentication.md.
Validating the spec
npm run check:openapi
check:openapi parses every feature's OpenAPI YAML through
@apidevtools/swagger-parser and runs the standard OpenAPI 3.x
structural validator. It runs as part of npm run check.