API conventions

Read the public OpenAPI specification and GET /v1/products for current schemas, supported sources and prices. Planned products are not callable.

Authentication

Send Authorization: Bearer <key>. Store keys in your server’s secret manager. Full-access keys can submit and cancel tasks; keys with read_results scope can inspect authorized tasks and results. Create and revoke keys in Developer → API Keys. A secret is shown once and cannot be recovered from a receipt.

Quote and submit

Send POST /v1/quotes with productId and input. Inspect its normalized input, pricingVersion, integer reservation and expiry. A quote creates no task or reservation and does not promise capacity or a result count.

Send POST /v1/tasks with productId, input and the required expectedPricingVersion from that quote. Unknown JSON fields are rejected. Review a fresh quote if the price changed.

Every controlled write requires a canonical Idempotency-Key: v1.<Unix milliseconds>.<random base64url nonce>, with a 22–64 character nonce. Preserve the entire original key for recovery. New acceptance is allowed for 24 hours, with at most five minutes of future clock skew. Changing the timestamp creates another key. Changing input under an existing key returns COMMAND_INPUT_CONFLICT.

Submission and cancellation return a command receipt plus the authorized current task when available. The receipt states whether that particular command was accepted; the task’s current status is a separate fact. Read command recovery before retrying uncertain work.

Waiting and failures

Use the task’s retryAfterSeconds between explicit checks. An HTTP 200 task read can describe a failed task. For HTTP 429, respect Retry-After; an elapsed delay permits a user-initiated retry, not an automatic repeat of a paid command.

Authentication, account restrictions, source availability, capacity and spending limits are checked at acceptance. A technical failure or lost response does not prove rejection. Recover the original command before authorizing new work.

Pagination and downloads

Tasks default to 100 items and allow pageSize 1–1,000. Task cursors preserve an immutable creation-time and ID order with a fixed upper bound. Results also default to 100 and allow 1–1,000; the response byte limit can produce a shorter page. prevCursor, nextCursor and hasMore describe saved pages. Keep filters and projection unchanged while paging and treat cursors as opaque.

Results are sorted by recordId. Reads do not start another collection. Request fresh JSONL links with POST /v1/tasks/{taskId}/download and {"format":"jsonl"}. Links last at most five minutes and are temporary bearer access. Download CSV with authenticated GET /v1/tasks/{taskId}/download.csv. An interrupted file is incomplete.

Frozen contracts and retention

Accepted tasks retain their input, contract.schemaVersion, contract.pricingVersion and billing facts. Use integer arithmetic: 1 credit = 1,000,000 units. Historical unknown values remain null.

Results remain available until resultExpiresAt, normally seven days after terminal result commitment. Expired reads return RESULT_EXPIRED; they do not collect again. Obtain and keep the files you need before that time.