Canonical contract
The OpenAPI 3.1 document is the source of truth for paths, methods, required fields, enums, limits, content types, and error responses. The handwritten guides explain safe usage without replacing that contract.
Operation groups
| Group | Operations |
|---|---|
| Datasets | List datasets, get dataset, health |
| Releases | List releases, get release, download release |
| Queries | Query released rows |
| Builds | List, create, get, and cancel builds |
| Synthesis | Create definitions, run recipes, inspect reports, and list gated releases |
Shared request contract
| Header | Requirement |
|---|---|
| Authorization | Bearer API key; required |
| X-API-Version | Optional; defaults to 1 |
| Content-Type | application/json for POST bodies |
| Accept | application/json for structured responses |
Compatibility policy
Optional response fields may be added within v1. Breaking path, method, required-field, or semantic changes require a new API major version and migration guidance. The dataset builder release schema is validated separately behind the public adapter.