# API conventions

Read the [public OpenAPI specification](https://api.truefetch.io/v1/openapi.json) and [`GET /v1/products`](https://api.truefetch.io/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](/docs/commands/) 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.
