> ## 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.

# Signup

> Self-serve account creation. The one unauthenticated write on the API.

## Create a sandbox account

```http theme={null}
POST /v1/signup
```

Success: `201`.

No authentication. Returns a sandbox-only tenant and one `ck_test_` key.

```bash theme={null}
curl -sX POST https://api.farthing.ai/v1/signup \
  -H 'content-type: application/json' \
  -d '{"name":"Acme Agents","email":"you@example.com"}'
```

### Body

Both fields are optional; an empty body works.

<ParamField body="name" type="string">
  1–120 characters. Your organisation's name, for our records. Falls back to `email`, then to
  `"sandbox tenant"`.
</ParamField>

<ParamField body="email" type="string">
  A valid email, max 200 characters. How we reach you — not a login. There is no password and
  no session; the API key is the only credential.
</ParamField>

### Response

```json theme={null}
{
  "tenantId": "6f0f2f39-8a34-4a8f-9a1a-1d0f4b9a2c77",
  "name": "Acme Agents",
  "sandboxOnly": true,
  "sandboxMerchants": ["your-sandbox-store.myshopify.com"],
  "apiKey": "ck_test_3sQd7yQ0mHq9pP2rVwXk1tLb"
}
```

<ResponseField name="tenantId" type="string">
  Your tenant UUID. Everything you create is scoped to it.
</ResponseField>

<ResponseField name="sandboxOnly" type="boolean">
  Always `true` for a self-serve signup. See [Sandbox](/sandbox).
</ResponseField>

<ResponseField name="sandboxMerchants" type="string[]">
  The hosts you may target. Read this rather than hard-coding it.
</ResponseField>

<ResponseField name="apiKey" type="string">
  Shown once. Only a SHA-256 hash is stored — nothing can recover it.
</ResponseField>

<Warning>
  Save `apiKey` immediately. If you lose it before making any other call, you have no way to
  authenticate and no way to recover the tenant — sign up again.
</Warning>

### Errors

| Status | Message                                                | Cause                                    |
| ------ | ------------------------------------------------------ | ---------------------------------------- |
| `400`  | `Invalid request` (with `issues`)                      | `name` or `email` failed validation.     |
| `403`  | `Self-serve signup is closed`                          | Signup is disabled platform-wide.        |
| `429`  | `Too many signups from this address. Try again later.` | More than 3 from one IP in an hour.      |
| `429`  | `Signups are temporarily paused. Get in touch.`        | More than 200 platform-wide in 24 hours. |

## Why this can be open

A signup produces a real, working key that drives the entire product — a real browser, a
real merchant storefront, a real variant prompt, real card entry, a genuinely placed order.

It is safe to leave open because the tenant it creates is confined to merchants we control.
Every other guardrail limits how much money moves; sandbox is the one that decides whether
real money is reachable at all. See [Sandbox](/sandbox).