Contract snapshot 0.101.0 · Deployment and client release availability follow the integration note for your environment.
Availability first
Show Coming soon when no snapshots are published. Only on_sale snapshots may be purchased. Scope, record count, coverage, rate and licence come from the API.
Review before approval
Show the quote ceiling and full licence before approval. Approval accepts that licence version and holds credits; startExport with quoteId prepares the file. Later editions are not included.
Downloads
Use export state and availableUntil to decide whether to offer a download. Request a short-lived link only when ready. A failed or timed-out write must be reconciled before retrying; do not invent a successful order or file.
GET
/v1/snapshots
List dataset snapshots for sale
Ready dataset snapshots (D-1547): each with its scope, newest edition (as-of date, record count, fields, coverage), price in credits from the rate card (D-1553), licence summary, the 12-month download window and whether it is on sale. A snapshot below its coverage floor is listed and cannot be bought. Filter by family, kind or category. Public and free.
Parameters
[
{
"name": "family",
"in": "query",
"required": false,
"schema": {
"type": "string",
"title": "Family",
"examples": [
"commerce"
],
"pattern": "^(commerce|investors|startups|companies|public_records)$"
},
"description": "Only this family: commerce, investors, startups, companies, public_records."
},
{
"name": "kind",
"in": "query",
"required": false,
"schema": {
"type": "string",
"title": "Kind",
"examples": [
"listings_app"
],
"pattern": "^(listings_app|listings_app_city|dark_store_map|category_history|investors|startups|companies)$"
},
"description": "Only this kind: listings_app, listings_app_city, dark_store_map, category_history, investors, startups, companies."
},
{
"name": "category",
"in": "query",
"required": false,
"schema": {
"type": "string",
"title": "Category",
"examples": [
"quick_commerce"
],
"pattern": "^[a-z][a-z0-9_]{1,63}$"
},
"description": "Only this catalogue category."
}
]| Status | Meaning |
|---|---|
| 200 | Success |
| 400 | Error. The `error.code` is one of: - `invalid_request`: retry advice `fix_request` |
| 429 | Error. The `error.code` is one of: - `rate_limited`: retry advice `after_reset` |
| 500 | Error. The `error.code` is one of: - `internal`: retry advice `bounded` |
| 503 | Error. The `error.code` is one of: - `unavailable`: retry advice `bounded` |
Full response fields and reusable schemas are in the downloadable OpenAPI contract.
GET
/v1/snapshots/{id}
Get a dataset snapshot
One snapshot in full: everything in the list, plus up to 100 free sample records of the newest edition and the licence text, shown before buying (D-1556). Public and free.
Parameters
[
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Id",
"description": "The snapshot id.",
"examples": [
"listings_blinkit_in"
],
"pattern": "^[a-z][a-z0-9_]{1,63}$"
}
}
]| Status | Meaning |
|---|---|
| 200 | Success |
| 400 | Error. The `error.code` is one of: - `invalid_request`: retry advice `fix_request` |
| 404 | Error. The `error.code` is one of: - `not_found`: retry advice `fix_request` |
| 429 | Error. The `error.code` is one of: - `rate_limited`: retry advice `after_reset` |
| 500 | Error. The `error.code` is one of: - `internal`: retry advice `bounded` |
| 503 | Error. The `error.code` is one of: - `unavailable`: retry advice `bounded` |
Full response fields and reusable schemas are in the downloadable OpenAPI contract.
POST
/v1/snapshots/{id}/quote
Quote a dataset snapshot
Prices the newest edition of a snapshot in full, in credits from the rate card (D-1553), and returns the quote with the licence it is sold under, in full (D-1556). Approve it with POST /v1/quotes/{id}/approve: that holds the credits and accepts that licence version. Any member of the organisation may buy (D-1557). A snapshot below its coverage floor, not counted or not priced is refused with `not_for_sale`.
Parameters
[
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Id",
"description": "The snapshot id.",
"examples": [
"listings_blinkit_in"
],
"pattern": "^[a-z][a-z0-9_]{1,63}$"
}
}
]| Status | Meaning |
|---|---|
| 201 | Success |
| 400 | Error. The `error.code` is one of: - `invalid_request`: retry advice `fix_request` |
| 401 | Error. The `error.code` is one of: - `key_expired`: retry advice `refresh_credentials` - `key_revoked`: retry advice `refresh_credentials` - `session_expired`: retry advice `refresh_credentials` - `unauthenticated`: retry advice `refresh_credentials` |
| 403 | Error. The `error.code` is one of: - `org_missing`: retry advice `never` - `scope_missing`: retry advice `never` |
| 404 | Error. The `error.code` is one of: - `not_found`: retry advice `fix_request` |
| 409 | Error. The `error.code` is one of: - `not_for_sale`: retry advice `never` |
| 429 | Error. The `error.code` is one of: - `rate_limited`: retry advice `after_reset` |
| 500 | Error. The `error.code` is one of: - `internal`: retry advice `bounded` |
| 503 | Error. The `error.code` is one of: - `unavailable`: retry advice `bounded` |
Full response fields and reusable schemas are in the downloadable OpenAPI contract.
POST
/v1/exports
Buy a snapshot: start its export
Starts the purchase of an approved snapshot quote (POST /v1/snapshots/{id}/quote, then POST /v1/quotes/{id}/approve). The worker builds the JSON Lines file of exactly that edition; the hold is settled on the rows delivered, never above the quote, and a failed export charges nothing. Idempotent: starting the same quote again returns the same purchase and starts nothing new. Any member may buy (D-1557).
Request body schema
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"title": "Start a purchase",
"description": "Start the export of an approved snapshot quote. Idempotent: the same quote returns the same purchase.",
"additionalProperties": false,
"required": [
"quoteId"
],
"properties": {
"quoteId": {
"type": "string",
"title": "Quote",
"description": "An approved snapshot quote of your organisation.",
"examples": [
"6a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
],
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
}
}
}
}
}
}| Status | Meaning |
|---|---|
| 201 | Success |
| 400 | Error. The `error.code` is one of: - `invalid_json`: retry advice `fix_request` - `invalid_request`: retry advice `fix_request` |
| 401 | Error. The `error.code` is one of: - `key_expired`: retry advice `refresh_credentials` - `key_revoked`: retry advice `refresh_credentials` - `session_expired`: retry advice `refresh_credentials` - `unauthenticated`: retry advice `refresh_credentials` |
| 403 | Error. The `error.code` is one of: - `org_missing`: retry advice `never` - `scope_missing`: retry advice `never` |
| 404 | Error. The `error.code` is one of: - `not_found`: retry advice `fix_request` |
| 413 | Error. The `error.code` is one of: - `payload_too_large`: retry advice `fix_request` |
| 415 | Error. The `error.code` is one of: - `unsupported_media_type`: retry advice `fix_request` |
| 429 | Error. The `error.code` is one of: - `rate_limited`: retry advice `after_reset` |
| 500 | Error. The `error.code` is one of: - `internal`: retry advice `bounded` |
| 503 | Error. The `error.code` is one of: - `unavailable`: retry advice `bounded` |
Full response fields and reusable schemas are in the downloadable OpenAPI contract.
GET
/v1/exports
List your dataset purchases
Your organisation's snapshot purchases, newest first: state, file size and SHA-256 once built, the receipt, and until when each can be downloaded (D-1555).
Parameters
[
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "string",
"title": "Limit",
"examples": [
"20"
],
"pattern": "^[1-9][0-9]{0,2}$"
},
"description": "How many, 1 to 100 (default 20)."
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string",
"title": "Cursor",
"examples": [
"eyJ0IjoiMjAyNi0xMC0xN1QwNjozMDowMFoiLCJpIjoiLi4uIn0"
],
"pattern": "^[A-Za-z0-9_-]{1,200}$"
},
"description": "page.nextCursor from the previous page."
}
]| Status | Meaning |
|---|---|
| 200 | Success |
| 400 | Error. The `error.code` is one of: - `invalid_request`: retry advice `fix_request` |
| 401 | Error. The `error.code` is one of: - `key_expired`: retry advice `refresh_credentials` - `key_revoked`: retry advice `refresh_credentials` - `session_expired`: retry advice `refresh_credentials` - `unauthenticated`: retry advice `refresh_credentials` |
| 403 | Error. The `error.code` is one of: - `org_missing`: retry advice `never` - `scope_missing`: retry advice `never` |
| 429 | Error. The `error.code` is one of: - `rate_limited`: retry advice `after_reset` |
| 500 | Error. The `error.code` is one of: - `internal`: retry advice `bounded` |
| 503 | Error. The `error.code` is one of: - `unavailable`: retry advice `bounded` |
Full response fields and reusable schemas are in the downloadable OpenAPI contract.
GET
/v1/exports/{id}
Read a dataset purchase
One purchase of your organisation. Another organisation's purchase is not found.
Parameters
[
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Id",
"description": "The purchase id.",
"examples": [
"3f2a0c5e-9b1d-4c1e-8f00-1a2b3c4d5e6f"
],
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
}
}
]| Status | Meaning |
|---|---|
| 200 | Success |
| 400 | Error. The `error.code` is one of: - `invalid_request`: retry advice `fix_request` |
| 401 | Error. The `error.code` is one of: - `key_expired`: retry advice `refresh_credentials` - `key_revoked`: retry advice `refresh_credentials` - `session_expired`: retry advice `refresh_credentials` - `unauthenticated`: retry advice `refresh_credentials` |
| 403 | Error. The `error.code` is one of: - `org_missing`: retry advice `never` - `scope_missing`: retry advice `never` |
| 404 | Error. The `error.code` is one of: - `not_found`: retry advice `fix_request` |
| 429 | Error. The `error.code` is one of: - `rate_limited`: retry advice `after_reset` |
| 500 | Error. The `error.code` is one of: - `internal`: retry advice `bounded` |
| 503 | Error. The `error.code` is one of: - `unavailable`: retry advice `bounded` |
Full response fields and reusable schemas are in the downloadable OpenAPI contract.
POST
/v1/exports/{id}/link
Get a download link for a purchase
A short-lived signed link (15 minutes, never past the window) to the purchase file. Ask again, free, whenever it runs out, for 12 months after the file was ready (D-1555). `export_not_ready` while it is being built; `download_expired` after the 12 months (the file is kept, but no longer offered) or for a purchase that failed (it has no file and charged nothing).
Parameters
[
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Id",
"description": "The purchase id.",
"examples": [
"3f2a0c5e-9b1d-4c1e-8f00-1a2b3c4d5e6f"
],
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
}
}
]| Status | Meaning |
|---|---|
| 200 | Success |
| 400 | Error. The `error.code` is one of: - `invalid_request`: retry advice `fix_request` |
| 401 | Error. The `error.code` is one of: - `key_expired`: retry advice `refresh_credentials` - `key_revoked`: retry advice `refresh_credentials` - `session_expired`: retry advice `refresh_credentials` - `unauthenticated`: retry advice `refresh_credentials` |
| 403 | Error. The `error.code` is one of: - `org_missing`: retry advice `never` - `scope_missing`: retry advice `never` |
| 404 | Error. The `error.code` is one of: - `not_found`: retry advice `fix_request` |
| 409 | Error. The `error.code` is one of: - `export_not_ready`: retry advice `never` |
| 410 | Error. The `error.code` is one of: - `download_expired`: retry advice `fix_request` |
| 429 | Error. The `error.code` is one of: - `rate_limited`: retry advice `after_reset` |
| 500 | Error. The `error.code` is one of: - `internal`: retry advice `bounded` |
| 503 | Error. The `error.code` is one of: - `unavailable`: retry advice `bounded` |
Full response fields and reusable schemas are in the downloadable OpenAPI contract.