> This page is for Paperwork API, version v2.
> For other versions, use one of these documentation indexes:
> - v1 (default): https://docs.cloudraker.com/paperwork/v1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cloudraker.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cloudraker.com/_mcp/server.

# API v2

API v2 is the CloudRaker API for documents and agents. Each organization has its own API host. `/v1` on `api.cloudraker.com` continues without changes.

> **Note**
>
> API v2 is in beta.

## The API host

```text
https://{slug}.cloudraker.run/v2
```

`{slug}` is the slug of your organization. The slug never changes. [Dash](https://dash.cloudraker.com/settings) shows it in **Settings**. Each `crk_` key contains it.

## How it works

* **Every call creates a job.** `200` and `202` return the same [Job object](/paperwork/v2/jobs).
* **The client selects the delivery.** Read the result in the answer, in a stream or in a webhook. The headers select the mode, not the route.
* **A slow call does not fail.** When the wait ends, the job continues and the answer is `202`. Read [Sync and async](/paperwork/v2/sync-and-async).
* **Credentials stay in your organization.** You create [API keys](/paperwork/v2/keys) and [OIDC trusts](/paperwork/v2/oidc-trusts) in Dash.
* **A failed job costs nothing.** The job records its use in paperwork credits when it ends.

## Capabilities

Each capability has one route and one [scope](/paperwork/v2/authentication#scopes). The scope name is the capability name.

| Capability   | Route                            | Scope              |
| ------------ | -------------------------------- | ------------------ |
| `parse`      | `POST /v2/parse`                 | `parse`            |
| `extract`    | `POST /v2/extract`               | `extract`          |
| `classify`   | `POST /v2/classify`              | `classify`         |
| `split`      | `POST /v2/split`                 | `split`            |
| `fill`       | `POST /v2/fill`                  | `fill`             |
| `redact`     | `POST /v2/redact`                | `redact`           |
| `generate`   | `POST /v2/generate`              | `generate`         |
| `convert`    | `POST /v2/convert`               | `convert`          |
| `redline`    | `/v2/redline/*`                  | `redline`          |
| `sign`       | `POST /v2/sign`                  | `sign`             |
| `transcribe` | `POST /v2/transcribe`            | `transcribe`       |
| `agents`     | `POST /v2/agents/{base}/{agent}` | `agents` and `run` |

A `POST` body is JSON, with a maximum size of 1 MiB. Send a large file by URL. A capability that reads a file takes `{ "url": "https://…" }` or `{ "id": "…" }`. The `id` is a file that you registered with `POST /v1/files`.

The `agents` capability refuses test keys with `403 test_key_not_allowed`, because Run has no test mode.

## Other routes

| Route                                                                | Purpose                                    |
| -------------------------------------------------------------------- | ------------------------------------------ |
| [`GET /v2/me`](/paperwork/v2/authentication#read-the-credential)     | The credential of the request.             |
| [`GET /v2/jobs`](/paperwork/v2/jobs#list-jobs)                       | List jobs. Needs `jobs:read`.              |
| [`GET /v2/jobs/{id}`](/paperwork/v2/jobs#read-a-job)                 | Read a job, or wait for it.                |
| [`POST /v2/jobs/{id}/cancel`](/paperwork/v2/jobs#cancel-a-job)       | Cancel a job.                              |
| [`POST /v2/oauth/token`](/paperwork/v2/oidc-trusts#exchange-a-token) | Exchange an OIDC token for a `crt_` token. |
| `GET /v2/health`                                                     | A public health check. No credential.      |

## Next steps

* Parse a file: [Quickstart](/paperwork/v2/quickstart).
* Pick a credential: [Authentication](/paperwork/v2/authentication).
* Understand the job: [Jobs](/paperwork/v2/jobs).
* Use TypeScript: [SDK](/paperwork/v2/sdk).