Getting Started

Last verified: 2026-05-03 (Task #334 — docs accuracy pass).

Every public Weather Intelligence endpoint lives under /v1/ and shares the same response envelope, error format, auth scheme, and rate-limit headers. Once you can call GET /v1/weather/health, everything else is a matter of swapping the path and reading the response.

Base URL

The /v1/ prefix is part of the path — there are no per-environment hostnames beyond the deployment domain.

Get an API key

API keys are minted via internal admin tooling for the MVP. Once you have one, the plaintext is shown exactly once — store it somewhere safe.

A key looks like:

tm_weather_abc123def456ghi789...

See authentication.md for everything else (scopes, environments, key rotation, internal keys).

Your first request

curl -s "https://api.travelmode.app/v1/weather/health" \
  -H "Authorization: Bearer tm_weather_..."

{
  "data": { "status": "ok", "environment": "production" },
  "meta": {
    "request_id": "7c0f3c2c-9e4a-4d29-b4a2-9c2b4e9f5c11",
    "generated_at": "2026-04-25T18:01:13.500Z",
    "environment": "production",
    "billing_units": 0
  }
}

Health calls are free — they don't burn quota and they don't depend on the upstream weather provider being warm.

Your first weather call

curl -s "https://api.travelmode.app/v1/weather/current?lat=48.8566&lng=2.3522" \
  -H "Authorization: Bearer tm_weather_..."

{
  "data": {
    "location": { "lat": 48.8566, "lng": 2.3522, "geohash": "u09tu" },
    "current": { "temperature": 14.2, "condition": { "label": "light rain" } },
    "risk": { "level": "low", "reasons": [], "recommendation": null }
  },
  "meta": {
    "request_id": "7c0f3c2c-9e4a-4d29-b4a2-9c2b4e9f5c11",
    "cache_status": "HIT",
    "billing_units": 1
  }
}

The full response shape lives in openapi.yaml and is documented in endpoints.md.

Where next

• The full endpoint list with examples is in endpoints.md.
• Plan tiers and rate limits are in rate-limits.md.
• The full machine-readable contract is in openapi.yaml.