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-HZ

Every 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