> ## Documentation Index > Fetch the complete documentation index at: https://docs.farthing.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Farthing's primary integrator is an autonomous agent or the developer wiring one up. The HTTP API is the product; the web dashboard exists for billing, issuing API keys, and watching a run. > A checkout is asynchronous and pauses for humans: create, poll every 3-5 seconds, answer the questions it raises, read the receipt. A run takes 2-3 minutes and can park for up to 10 minutes on one question. Never present it as a synchronous request/response call. > Branch on pendingUserAction.key. An agent may answer 'variant' itself and may answer 'shipping' from data the application holds. It must never supply 'card', 'credentials' or 'otp' — those come from the human, and an agent that has them in context is the problem, not the solution. > Base URL is https://api.farthing.ai and auth is Authorization: Bearer ck_test_... or ck_live_.... API keys carry scopes; give an agent the narrowest set that does its job. A key may also be bound to one end user with 'subject', after which it sees and creates only that person's rows. > POST /v1/checkouts takes an Idempotency-Key header. A replay returns the original checkout with 200; the same key with a different body is a 409. Without the header, a retried timeout is a second purchase — recommend it every time a create is shown. > Pricing: sandbox is free with no card; paid plans are Personal $9, Business $49, Scale $249 per month, plus a flat $1.00 per COMPLETED checkout on every tier. Failed and cancelled checkouts are never billed. Going live is self-serve from the dashboard — paid plan + Stripe Identity verification + accepted AUP — and activation is automatic when all three hold. > Every example in these docs is a shape the API actually produces. Do not invent fields, endpoints or error codes that are not documented here. # List checkouts > Cursor-paginated summaries, newest first. Deliberately a summary rather than the full object: the full shape carries the whole event timeline, which is exactly what a list view must not fetch. Requires the `checkouts.read` scope. `?subject=` narrows the page to one end user, and each row carries `subject` when the checkout has one. A subject-bound key is already narrowed to its own end user; asking for another's is a `403`. ## OpenAPI ````yaml /openapi.json get /v1/checkouts openapi: 3.1.0 info: title: Farthing API version: 1.0.0 summary: >- Agentic checkout. Give it a product URL and a plain-English request; it drives a real browser to a completed purchase and asks a human only when it must. description: >- The HTTP API is the product. Everything an integration needs — creating checkouts, answering the questions a run stops on, storing buyers, issuing scoped keys — is here. A checkout is asynchronous and pauses for humans. `POST /v1/checkouts` returns in milliseconds with a `queued` object; the run itself takes minutes and may park on a `pendingUserAction` for up to ten. Poll `GET /v1/checkouts/{id}` (unmetered) or register a webhook endpoint. Not covered by this spec: the live-view embed (`GET /embed/{checkoutId}` and `GET /embed/{checkoutId}/stream`). Those are consumed by a browser, authenticate with a short-lived JWT minted at `POST /v1/checkouts/{id}/embed-token` rather than with an API key, and return HTML and `text/event-stream`. Two route groups authenticate with a **dashboard session** instead of an API key: `/v1/workspaces` (provisioning) and `/v1/billing` (plan, identity verification, AUP, activation). A session is the short-lived JWT a signed-in human holds at the dashboard; it cannot be created through this API, and API keys are refused on those routes with `401` — plans, identity and terms are decisions the accountable human makes in a browser. Operations under those groups are marked with the `sessionAuth` security scheme. contact: name: Farthing url: https://docs.farthing.ai servers: - url: https://api.farthing.ai description: Production security: - bearerAuth: [] tags: - name: Signup description: Self-serve account creation. The only unauthenticated write on the API. - name: Checkouts description: Create a run, poll it, cancel it, and answer what it asks. - name: Buyer profiles description: >- Reusable identity and shipping details, referenced by id when creating a checkout. - name: Buyer sessions description: >- Stored merchant logins captured by a `credentials` action. Read-only metadata and revocation. - name: Webhooks description: >- Endpoints that receive `checkout.status_changed` with an HMAC-SHA256 signature. - name: API keys description: >- Self-serve key issuance and revocation. Keys carry scopes; a key can never mint one broader than itself. - name: Usage description: Completed checkouts by day, and gross merchandise volume by currency. - name: Workspaces description: >- Dashboard-session workspace provisioning. One workspace per account; the first request of a fresh sign-in is “do I have a workspace?” and the second is “make me one”. - name: Billing description: >- Dashboard-session billing: plan, identity verification, AUP, and the activation checklist. Session-only — an agent's key completes checkouts, it does not choose subscription plans. - name: Health description: Liveness. paths: /v1/checkouts: get: tags: - Checkouts summary: List checkouts description: >- Cursor-paginated summaries, newest first. Deliberately a summary rather than the full object: the full shape carries the whole event timeline, which is exactly what a list view must not fetch. Requires the `checkouts.read` scope. `?subject=` narrows the page to one end user, and each row carries `subject` when the checkout has one. A subject-bound key is already narrowed to its own end user; asking for another's is a `403`. operationId: listCheckouts parameters: - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Cursor' - name: status in: query required: false description: >- Filter to one status. An unrecognised value is a `400`, not an empty page. schema: $ref: '#/components/schemas/CheckoutStatus' - name: subject in: query required: false description: >- Filter to one end user. Composes with `status`, `limit` and `cursor`; a subject with no checkouts is an empty page, not an error. A subject-bound key does not need this — its page is already narrowed to one person. Passing its own subject is fine; naming a different one is a `403`, refused rather than quietly ignored. Validated like every other subject: 1 to 200 characters, or `400`. schema: type: string minLength: 1 maxLength: 200 example: user_a91f responses: '200': description: A page of summaries. content: application/json: schema: type: object required: - data - nextCursor properties: data: type: array items: $ref: '#/components/schemas/CheckoutSummary' nextCursor: type: - string - 'null' format: date-time description: >- Pass back as `?cursor=`. `null` means this was the last page. example: data: - id: 1f2e3d4c-5b6a-4790-8123-abcdef012345 status: succeeded subject: user_a91f url: https://your-sandbox-store.myshopify.com/products/widget request: buy this in medium, cheapest delivery receipt: total: amount: '42.10' currency: USD merchantOrderId: '1042' createdAt: '2026-07-29T09:14:31.190Z' updatedAt: '2026-07-29T09:26:29.702Z' - id: 5c7d9e01-2b34-4a56-8f90-1a2b3c4d5e6f status: awaiting_user_action url: https://your-sandbox-store.myshopify.com/products/mug request: null pendingUserActionId: 7c1de0a2-9b44-4f0a-b3c1-2a5e8d7f4b60 createdAt: '2026-07-29T09:31:02.418Z' updatedAt: '2026-07-29T09:33:11.006Z' nextCursor: '2026-07-29T09:31:02.418Z' '400': description: Bad `limit`, `cursor` or `status`. content: application/json: schema: $ref: '#/components/schemas/Error' examples: limit: value: error: true message: '''limit'' must be an integer between 1 and 100' cursor: value: error: true message: >- 'cursor' must be an ISO 8601 timestamp from a previous nextCursor status: value: error: true message: Unknown status 'done' '401': $ref: '#/components/responses/Unauthorized' '403': description: >- A missing scope, a suspended tenant, or a subject-bound key asking for another end user's rows with `?subject=`. content: application/json: schema: anyOf: - $ref: '#/components/schemas/ScopeError' - $ref: '#/components/schemas/Error' examples: scope: value: error: true message: This API key is missing the 'checkouts.read' scope. requiredScope: checkouts.read otherSubject: summary: A bound key filtering for somebody else value: error: true message: >- This API key is bound to subject 'user_a91f' and cannot act for another. components: parameters: Limit: name: limit in: query required: false description: Page size. Must be an integer from 1 to 100; anything else is a `400`. schema: type: integer minimum: 1 maximum: 100 default: 20 Cursor: name: cursor in: query required: false description: >- The previous page's `nextCursor` — an ISO 8601 timestamp. Returns rows created strictly before it. schema: type: string format: date-time schemas: CheckoutStatus: type: string title: CheckoutStatus description: '`succeeded`, `failed` and `cancelled` are terminal; nothing leaves them.' enum: - queued - running - awaiting_user_action - succeeded - failed - cancelled CheckoutSummary: type: object title: CheckoutSummary description: >- The list-endpoint shape. No timeline — fetch the full object when you need one. required: - id - status - url - request - createdAt - updatedAt properties: id: type: string format: uuid status: $ref: '#/components/schemas/CheckoutStatus' subject: type: string description: >- Your own id for the end user this checkout is for. **Absent** when the checkout is not tagged to one — the same convention as the full object. examples: - user_a91f url: type: - string - 'null' request: type: - string - 'null' failure: type: object required: - reason properties: reason: $ref: '#/components/schemas/FailureReason' receipt: type: object description: >- Present once a receipt exists. Total and order id only — no `evidence` on the summary. properties: total: $ref: '#/components/schemas/Money' merchantOrderId: type: - string - 'null' pendingUserActionId: type: string format: uuid description: >- Present when this checkout is blocked. Fetch the checkout to see what it is asking for. createdAt: type: string format: date-time updatedAt: type: string format: date-time Error: type: object title: Error description: >- Every error is this object. There are no error codes: match on the HTTP status, treat `message` as text for a human. required: - error - message properties: error: type: boolean const: true message: type: string ScopeError: type: object title: ScopeError description: An out-of-scope request. `requiredScope` saves you parsing the message. required: - error - message - requiredScope properties: error: type: boolean const: true message: type: string requiredScope: $ref: '#/components/schemas/Scope' FailureReason: type: string title: FailureReason description: >- A closed set of four. The human-readable detail lives in the final `terminal` progress item's `data.message`, not here. enum: - max_cost_exceeded - user_cancelled - user_action_expired - automation_failed Money: type: object title: Money required: - amount properties: amount: type: string description: A decimal string — `"42.10"`, never `42.1`. examples: - '42.10' currency: type: string default: USD description: ISO 4217. examples: - USD Scope: type: string title: Scope description: >- `.read` or `.write`, or the wildcard `*`. `write` implies `read` on the same resource. Resources are exactly the route groups under `/v1`. enum: - '*' - checkouts.read - checkouts.write - buyer-profiles.read - buyer-profiles.write - buyer-sessions.read - buyer-sessions.write - webhooks.read - webhooks.write - api-keys.read - api-keys.write - usage.read - usage.write responses: Unauthorized: description: >- Missing, malformed, invalid or revoked bearer token. There is no distinction between "never existed" and "revoked" — that difference is only useful to someone probing. content: application/json: schema: $ref: '#/components/schemas/Error' examples: missing: value: error: true message: Missing bearer token invalid: value: error: true message: Invalid or revoked API key securitySchemes: bearerAuth: type: http scheme: bearer description: >- `Authorization: Bearer ck_test_…` or `ck_live_…`. There is no other auth scheme — no query-string keys, no request signing, no OAuth. ````