Travelmode Weather Intelligence API
Last verified: 2026-05-03 (Task #334 — docs accuracy pass).
This directory holds the public contract for the Weather Intelligence API. The spec is the source of truth; the markdown sections below add narrative guidance, billing tables, and worked examples.
Status: v1, MVP. Endpoints are stable. Public developer portal is hosted at
/developerson the deployed app (e.g. https://api.travelmode.app/developers). Typed client SDKs are auto-generated from this spec — seesdks/typescript/andsdks/python/.
Hosted developer portal
Every file in this directory is published as a hosted developer
portal at /developers on the deployed app, e.g.
https://api.travelmode.app/developers:
| URL | What it serves |
|---|---|
/developers | Landing page with the section index. |
/developers/<slug> | Each markdown file (getting-started, authentication, rate-limits, endpoints, errors, billing, cache-freshness, webhooks, attribution). |
/developers/reference | Interactive OpenAPI 3.1 reference (Stoplight Elements) with built-in Authorize and Try It panels. |
/developers/openapi.yaml | Canonical YAML spec, served raw. |
/developers/openapi.json | Same spec, JSON-encoded for tooling. |
The portal is a Next.js route under app/developers/ that reads
this directory at runtime. There is no separate publish step:
the moment a change to openapi.yaml or any *.md file lands on
main and the deploy build runs (npm run build), the live portal
serves the new content. The deploy build also runs
npm run check:openapi, which fails the deploy if the spec is
invalid — so a broken spec never reaches production.
Files
| File | What it contains |
|---|---|
openapi.yaml | OpenAPI 3.1 spec — every path, schema, error code, header, and example. Validated by npm run check:openapi. |
getting-started.md | First request, base URL, auth quickstart. |
authentication.md | API keys, scopes, environments, internal keys. |
rate-limits.md | Plan tiers, quota dimensions, throttling, headers. |
endpoints.md | Per-endpoint reference + curl/JS examples. |
errors.md | Every error code, status, and example envelope. |
billing.md | Billing-unit table per endpoint and per outcome. |
cache-freshness.md | Cache behavior, freshness bands, X-Cache-Status. |
webhooks.md | Webhook events, signing, retries. |
attribution.md | Provider attribution rules (placeholder). |
Quick links
- Standard envelope:
{ data: T, meta: ApiMeta }— seeendpoints.md#response-envelope. - Error envelope:
{ error: { code, message, details?, request_id }, meta }— seeerrors.md. - Auth:
Authorization: Bearer tm_weather_...— seeauthentication.md.
Validating the spec
npm run check:openapi
check:openapi parses every YAML file in this directory through
@apidevtools/swagger-parser, which dereferences $refs and runs the
standard OpenAPI 3.x structural validator. The validator runs as part
of npm run check.