Early access · endpoints may change before general availability
Documentation
Everything you need to make your first call and take AirDB to production. If something is unclear, tell us: info@airdb.com.
01 · GUIDEQuickstart
Three steps from zero to data: get a key, make a request, page through the results.
1. Get an API key
Request access at airdb.io/get-access. Keys are scoped per environment; keep them out of source control and pass them via theAIRDB_KEY environment variable.
2. Make your first request
export AIRDB_KEY="sk_live_…"
curl https://api.airdb.io/v1/prices \
-H "Authorization: Bearer $AIRDB_KEY" \
-d commodity=apple -d region=CN-HZEvery response is JSON with a stable schema. Errors follow RFC 9457 problem details, so your client can branch on type instead of parsing messages.
3. Paginate
List responses include a next_cursor. Pass it back as cursorto fetch the next page; a null cursor means you have everything.
curl https://api.airdb.io/v1/prices \
-H "Authorization: Bearer $AIRDB_KEY" \
-d commodity=apple -d region=CN-HZ \
-d cursor="eyJvZmZzZXQi…"02 · REFERENCEAPI Reference
Base URL https://api.airdb.io. All endpoints require a Bearer key. Rate limits and remaining quota are reported in x-ratelimit-* headers.
| Endpoint | Description |
|---|---|
| GET /v1/datasets | List datasets in the catalog. Filter by domain, region, or cadence. |
| GET /v1/datasets/{id} | Dataset metadata: schema, coverage, update cadence, lineage, licensing. |
| GET /v1/datasets/{id}/rows | Query rows with typed filters. Cursor-paginated, max 10,000 rows per page. |
| GET /v1/datasets/{id}/export | Start a bulk export job (parquet or CSV). Poll or receive a webhook when ready. |
| GET /v1/prices | Convenience endpoint over commodity price series. Same parameters as rows. |
| POST /v1/webhooks | Subscribe to dataset updates. Signed payloads, automatic retries. |
The full reference with every parameter, error code, and response schema ships with general availability. Early-access partners receive the OpenAPI spec directly.
03 · CATALOGDataset Catalog
A sample of what is live today. Each dataset page documents coverage, cadence, lineage, and licensing terms.
| Dataset | Description | Cadence | Status |
|---|---|---|---|
| agri/apple-prices | Daily wholesale apple prices by production region | daily | live |
| agri/grain-yields | Seasonal grain yield estimates, county resolution | seasonal | live |
| agri/weather-obs | Station-level weather observations, agriculture regions | hourly | live |
| supply/cold-chain | Cold-chain logistics capacity and lane pricing | weekly | beta |
| trade/customs-agri | Agricultural import/export flows by HS code | monthly | beta |
Need a dataset that is not listed? Managed Collection builds compliant pipelines to order: tell us what you need.
04 · LIBRARIESSDKs
Official clients wrap auth, pagination, retries, and typed schemas. The REST API is always the source of truth.
| Language | Install | Status |
|---|---|---|
| Python | pip install airdb | beta |
| TypeScript | npm install @airdb/sdk | beta |
| Go | go get airdb.io/sdk-go | planned |