Travelmode Events API
Last verified: 2026-06-20 (Task #390 — User APIs documentation).
This directory holds the public contract for the Events feature of the Travelmode developer platform. The OpenAPI spec is the source of truth; the markdown guides add narrative guidance and worked examples.
An event (a flight, stay, activity, meal, transit leg, and so on) can be attached to one or more trips through the many-to-many trip-events join, so the same booking can appear on every traveller's trip.
Auth model: these endpoints use the end-user auth model (session cookie or mobile / extension bearer token), not a
tm_developer key. Reads and creates require trip membership; updates and deletes are planner-only. Seeauthentication.md.
Hosted developer portal
| URL | What it serves |
|---|---|
/developers/events | Events feature overview (this README). |
/developers/events/<slug> | Each markdown guide (getting-started, authentication, events, errors). |
/developers/events/reference | Interactive OpenAPI 3.1 reference with Authorize and Try It. |
/developers/events/openapi.yaml | Canonical YAML spec, served raw. |
/developers/events/openapi.json | Same spec, JSON-encoded for tooling. |
Files
| File | What it contains |
|---|---|
openapi.yaml | OpenAPI 3.1 spec — every Events path, schema, and example. Validated by npm run check:openapi. |
getting-started.md | Base URL, auth quickstart, create your first event. |
authentication.md | Session cookie, bearer token, and planner gating. |
events.md | Create, read, update, and delete events across trips. |
errors.md | Status codes, the soft-delete 410, and the error shape. |
Quick links
- Response shape: resource objects (no
{ data, meta }envelope). - Error shape:
{ "error": <string | array> }— seeerrors.md. - A soft-deleted event returns
410 Gone.
Validating the spec
npm run check:openapi