Skip to content

API Reference

Climate-Lama exposes a versioned REST API. All endpoints are prefixed with /v1/.

Async jobs return 202 Accepted with a job_id. Poll /v1/jobs/{job_id} for status and retrieve results from the returned storage URL once the job completes.

Interactive API explorer

When the API is running locally, the full OpenAPI specification and an interactive UI are available at:

  • Swagger UI: http://localhost:8000/docs
  • ReDoc: http://localhost:8000/redoc
  • OpenAPI JSON: http://localhost:8000/openapi.json

Key resource groups

Prefix Description
/v1/hazards Hazard event sets — upload, list, fetch
/v1/exposures Exposure layers — upload, list, fetch
/v1/jobs Async compute jobs — submit, poll, retrieve
/v1/catalog Data catalog — search available datasets
/v1/auth Authentication — token issuance

Authentication

All endpoints (except /v1/auth/token) require a Bearer token in the Authorization header:

Authorization: Bearer <token>

Conventions

  • Content-Type: application/json for bodies; multipart/form-data for file uploads
  • Date format: ISO 8601 (2026-04-22T00:00:00Z)
  • Error format: { "detail": "human-readable message" } with appropriate HTTP status
  • Pagination: cursor-based via ?cursor=<token>&limit=<n> where supported

OpenAPI embed

An embedded Swagger UI will be added here once the deployed API endpoint is confirmed. See the deployment guide for environment URLs.