Travelmode Platform API
This directory holds the public contract for the Platform feature of the Travelmode developer platform. The Platform API exposes the cross-cutting, product-agnostic developer-account endpoints — managing webhook endpoints and reading your usage and quota — that are not specific to any single product surface such as Weather.
The OpenAPI spec is the source of truth; the markdown guides below add narrative guidance, signing details, and worked examples. Platform endpoints share the same response envelope, error format, API key authentication scheme, and rate-limit headers as the rest of the platform.
Status: v1, MVP. The Platform feature is published in the developer portal at
/developers/platformon the deployed app (e.g. https://travelmode.ai/developers/platform).
Hosted developer portal
Every file in this directory is published under the Platform feature of the portal, e.g. https://travelmode.ai/developers/platform:
| URL | What it serves |
|---|---|
/developers/platform | Platform feature overview (this README). |
/developers/platform/<slug> | Each markdown guide (getting-started, authentication, webhooks, usage). |
/developers/platform/reference | Interactive OpenAPI 3.1 reference (Stoplight Elements) with built-in Authorize and Try It panels. |
/developers/platform/openapi.yaml | Canonical YAML spec, served raw. |
/developers/platform/openapi.json | Same spec, JSON-encoded for tooling. |
Files
| File | What it contains |
|---|---|
openapi.yaml | OpenAPI 3.1 spec — webhook and usage paths, schemas, error codes, headers, and examples. Validated by npm run check:openapi. |
getting-started.md | Base URL, keys, and the two endpoint families at a glance. |
authentication.md | API keys and the scopes Platform endpoints require. |
webhooks.md | Webhook events, signing, retries, and auto-disable safeguards. |
usage.md | Reading your plan, quota, and remaining capacity. |
Endpoints at a glance
| Endpoint | Purpose |
|---|---|
POST /v1/webhooks | Register a webhook endpoint and receive its signing secret (once). |
GET /v1/webhooks | List the endpoints the calling developer owns. |
GET /v1/webhooks/{webhook_id} | Read a single owned endpoint. |
DELETE /v1/webhooks/{webhook_id} | Soft-disable an endpoint. |
GET /v1/webhooks/{webhook_id}/attempts | Inspect recent delivery attempts. |
GET /v1/usage | Read plan, period bounds, limits, and current usage/remaining. |
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.