Travelmode Weather Intelligence API
This directory holds the public contract for the Weather Intelligence feature of the Travelmode developer platform. The OpenAPI spec is the source of truth; the markdown guides below add narrative guidance, billing tables, and worked examples.
Status: v1, MVP. Endpoints are stable. The Weather feature is published in the developer portal at
/developers/weatheron the deployed app (e.g. https://travelmode.ai/developers/weather). Typed client SDKs are auto-generated from this spec — seesdks/typescript/andsdks/python/.
Cross-cutting developer endpoints (webhooks and usage/quota) are not
part of the Weather surface — they live in the
Platform feature and are published at
/developers/platform.
Hosted developer portal
Every file in this directory is published under the Weather feature of the portal, e.g. https://travelmode.ai/developers/weather:
| URL | What it serves |
|---|---|
/developers/weather | Weather feature overview (this README). |
/developers/weather/<slug> | Each markdown guide (getting-started, authentication, rate-limits, endpoints, errors, watch-webhooks, billing, cache-freshness, attribution). |
/developers/weather/reference | Interactive OpenAPI 3.1 reference (Stoplight Elements) with built-in Authorize and Try It panels. |
/developers/weather/openapi.yaml | Canonical YAML spec, served raw. |
/developers/weather/openapi.json | Same spec, JSON-encoded for tooling. |
The portal is a Next.js route under app/developers/ that reads this
directory at runtime via the feature registry
(app/developers/lib/features/). 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 any feature spec is invalid — so a broken spec never
reaches production.
Files
| File | What it contains |
|---|---|
openapi.yaml | OpenAPI 3.1 spec — every Weather 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. |
watch-webhooks.md | Per-watch webhook headers, signature, payload envelope, and retry/backoff behaviour. |
billing.md | Billing-unit table per endpoint and per outcome. |
cache-freshness.md | Cache behavior, freshness bands, X-Cache-Status. |
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. - Account-level webhooks & usage: documented in the Platform feature.
- Per-watch webhooks (a watch's own
webhook_url): signature, headers, payload, and retries inwatch-webhooks.md.
Validating the spec
npm run check:openapi
check:openapi parses every feature's OpenAPI YAML 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.