> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usepatchwork.co/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> The Patchwork API is organized around REST. JSON in, JSON out, grouped by product.

## Just getting started?

Start with the [introduction](/) or pick a door: [Identify an account](/guides/identify) or [embed an agent](/guides/loom).

## Base URL

```
https://api.usepatchwork.co
```

The API is REST. Resource-oriented URLs, JSON request bodies, JSON responses, standard HTTP verbs and status codes. Every response is an envelope:

```json theme={null}
{ "status": "success", "data": { } }
```

or

```json theme={null}
{ "status": "error", "error": { "message": "…", "code": "…" } }
```

Unknown fields are omitted — we do not send nulls. See [Errors](/api-reference/errors).

## Authentication

Authenticate with a bearer token on every request.

```bash theme={null}
Authorization: Bearer <credential>
```

| Product                                  | Credential                                 |
| ---------------------------------------- | ------------------------------------------ |
| Identify (and the rest of the workbench) | Workspace API key (`sk_…`)                 |
| Loom, direct                             | Session token your backend signs           |
| Loom, relay                              | Workspace API key plus `Patchwork-Subject` |

The credential's form selects the Loom mode: a JWT is direct; anything else is relay. Details in [Authentication](/authentication).

## Products

<CardGroup cols={2}>
  <Card title="Identify" icon="building-columns" href="/api-reference/identify">
    Resolve a bank or wallet identifier. Live.
  </Card>

  <Card title="Loom" icon="sparkles" href="/api-reference/loom">
    Threads, messages, runs, traces, outcomes. Live.
  </Card>

  <Card title="FX rates" icon="chart-line" href="/api-reference/fx-rates">
    Coming soon.
  </Card>

  <Card title="Extract" icon="file-lines" href="/api-reference/extract">
    Coming soon.
  </Card>

  <Card title="Vision" icon="eye" href="/api-reference/vision">
    Coming soon.
  </Card>
</CardGroup>

The dashboard API (`/api/*`) is not part of this reference. It is for the studio, not for your product.

## Versioning

Public endpoints live under `/v1`. Breaking changes get a new prefix. Additive fields may appear on existing objects without a version bump.

## Rate limits

Requests are rate-limited per workspace. A limited call returns `429` with `RATE_LIMITED` and a `Retry-After` header. Successful calls include `RateLimit-Limit` and `RateLimit-Remaining`.

## Idempotency

Identify is a lookup — repeat a call and you get the same resolution (and another charge if the result is `identified`). Loom messages start a run; do not retry a `202` unless you intend a second turn. Outcome posts are safe to retry: a tool call that already has an outcome is a no-op.

## Credits

We charge outcomes, not requests. An `identified` result on Identify. A closed Loom run that is not a platform failure. Promo credits cover first calls. There is no complimentary test lane. `402` means the workspace is out of credits.