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

# Migrate from /v1 to /v2

This page shows how to move an integration from `/v1` on `api.cloudraker.com` to API v2. `/v1` continues without changes, so you can move one route at a time.

> **Note**
>
> `/v1` has no end date now. When CloudRaker sets a date, `/v1` answers get `Deprecation`, `Sunset` and `Link` headers. The notice is 6 months. The `Link` header names this page.

## Compare the APIs

| Topic                 | `/v1`                                                                  | `/v2`                                                                                                         |
| --------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| API host              | `https://api.cloudraker.com/v1`                                        | `https://{slug}.cloudraker.run/v2`                                                                            |
| Credential            | An organization API key from **Admin**, then **API keys**              | A `crk_` key from [Dash](https://dash.cloudraker.com/api-keys), or an [OIDC trust](/paperwork/v2/oidc-trusts) |
| Hold the request      | `?wait=N`: 0 to 120 seconds, default 60                                | `Prefer: wait=N`: 1 to 90 seconds, default 30 for most capabilities                                           |
| Answer after the wait | `202` with `statusUrl` in the body                                     | `202` with the job, and the `Location` and `Retry-After` headers                                              |
| Result                | One run object for each capability, for example `extract_run`          | One [Job object](/paperwork/v2/jobs) for all capabilities                                                     |
| Webhook in the body   | `webhook`                                                              | `notify`                                                                                                      |
| Saved webhooks        | `POST /v1/webhooks`                                                    | The [Webhooks](https://dash.cloudraker.com/webhooks) page of Dash                                             |
| Webhook signature     | `x-rk1-signature`: an ES256 JWT, with one JWKS for all customers       | `x-cr-signature`: an RS256 JWT, with one JWKS for each organization                                           |
| Idempotency           | The same key returns the first run. The API does not compare the body. | The same key with another body gives `409 idempotency_key_reused`.                                            |
| Rate limits           | 67 requests per minute for each organization                           | Limits by plan. Read [Rate limits](/paperwork/v2/rate-limits).                                                |
| Error body            | `code`, `message`, `retryable`, `requestId`, `docUrl`                  | The same body. Some [codes change](#change-the-error-codes).                                                  |

## Move an integration

1. Find the slug of your organization in the [Settings](https://dash.cloudraker.com/settings) page of Dash.
2. Create a [`crk_` key](/paperwork/v2/keys). Select the scope of each capability that you call.
3. Add your webhook endpoints on the [Webhooks](https://dash.cloudraker.com/webhooks) page of Dash.
4. Change your webhook verifier. Read [Move your webhooks](#move-your-webhooks).
5. Change one route: the [host and key](#change-the-host-and-the-key), the [wait](#change-the-wait) and the [body](#change-the-body).
6. Change the code that reads the answer. Use the [Job object map](#read-the-job-object).
7. Test the route with a test key, then deploy it with a live key.
8. Move the next route.

> **Warning**
>
> Test keys have their own rate limits, but their jobs use real paperwork credits. A test key cannot start an agent.

Read a run that started on `/v1` through its `/v1` URL until it ends. Do not send its document to `/v2` again. That starts a second job and uses credits again.

Keep your `/v1` key until no code calls `/v1`. Some routes have [no `/v2` route](#routes-with-no-v2-route).

The [TypeScript SDK](/paperwork/v2/sdk) builds the host from the key, sends the idempotency key and verifies webhooks.

## Change the host and the key

**`/v1`**

```bash title="/v1"
curl -X POST "https://api.cloudraker.com/v1/parse?wait=60" \
  -H "Authorization: Bearer $CLOUDRAKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "file": { "url": "https://www.irs.gov/pub/irs-pdf/fw9.pdf" } }'
```

**`/v2`**

```bash title="/v2"
curl -X POST "https://$CRK_SLUG.cloudraker.run/v2/parse" \
  -H "Authorization: Bearer $CRK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=60" \
  -d '{ "file": { "url": "https://www.irs.gov/pub/irs-pdf/fw9.pdf" } }'
```

`{slug}` is the slug of your organization. The slug never changes, and each `crk_` key contains it.

A `/v1` key does not work on `/v2`. The answer is `401 invalid_api_key`. A `crk_` key does not work on `/v1`. A `crk_` key also works only on the host of its own organization.

A `crk_` key can call only the capabilities in its [scopes](/paperwork/v2/authentication#scopes). A missing scope gives `403 insufficient_scope`.

## Map the routes

### Capabilities

| `/v1` route                                                                       | `/v2` route                                 | Change                                                                                                                                                                                    |
| --------------------------------------------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /v1/parse`                                                                  | `POST /v2/parse`                            | None.                                                                                                                                                                                     |
| `POST /v1/parse` with the `processing` value `transcribe` or `transcribe_diarize` | `POST /v2/transcribe`                       | The default is `respond-async`.                                                                                                                                                           |
| `POST /v1/extract`                                                                | `POST /v2/extract`                          | None.                                                                                                                                                                                     |
| `POST /v1/classify`                                                               | `POST /v2/classify`                         | None.                                                                                                                                                                                     |
| `POST /v1/split`                                                                  | `POST /v2/split`                            | `classifyRunId` takes only a `/v1` `clr_` run id. After you move classify to `/v2`, [send `segments`](#change-the-body).                                                                  |
| `POST /v1/fill`                                                                   | `POST /v2/fill`                             | None.                                                                                                                                                                                     |
| `POST /v1/redact`                                                                 | `POST /v2/redact`                           | None.                                                                                                                                                                                     |
| `POST /v1/sign`                                                                   | `POST /v2/sign`                             | The default is `respond-async`. The job reaches `needs_input` when the envelope opens. To void an envelope or resend a signer link, [keep this route on `/v1`](#routes-with-no-v2-route). |
| `POST /v1/compose`                                                                | `POST /v2/generate`                         | Renders a saved template. The output is a file reference. There is no raw PDF answer.                                                                                                     |
| `POST /v1/files/{ref}/convert/markdown`, `/convert/pdf`, `/convert/image`         | `POST /v2/convert`                          | One route for all conversions. The output is a file.                                                                                                                                      |
| `POST /v1/files/{ref}/split/pages`, `POST /v1/files/stitch`                       | `POST /v2/convert`                          | One route for all conversions. The output is a file.                                                                                                                                      |
| `POST /v1/files/{ref}/redline`, `/v1/redline/{sessionId}/*`                       | `/v2/redline/*`                             | A new session takes a file URL only. An `id` gives `400 invalid_request`. The next two rows show the routes that change.                                                                  |
| `POST /v1/redline/{sessionId}/flush`                                              | `/v2/redline/{sessionId}/export`            | The route name changes. The answer is a [Job object](/paperwork/v2/jobs), not a `201` with a file. The job output is a file reference.                                                    |
| `POST /v1/redline/{sessionId}/suggestions/apply`                                  | `/v2/redline/{sessionId}/suggestions/apply` | The answer is a [Job object](/paperwork/v2/jobs), not a `200` with the new revision. Read the job as for any other capability.                                                            |

### Runs and webhooks

| `/v1` route                         | `/v2` route                                                       | Change                                                                           |
| ----------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `GET /v1/runs`                      | `GET /v2/jobs`                                                    | Needs the `jobs:read` scope. Use `capability=extract`, not `object=extract_run`. |
| `GET /v1/runs/{id}`                 | `GET /v2/jobs/{id}`                                               | With `Prefer: wait=N`, the answer is always `200` with the job.                  |
| `POST /v1/runs/{id}/cancel`         | `POST /v2/jobs/{id}/cancel`                                       | Only the credential that created the job can cancel it.                          |
| `GET /v1/runs/{id}/output/{name}`   | Read the URLs in `output`                                         | Read [the output of a job](/paperwork/v2/jobs#read-the-output).                  |
| `/v1/webhooks`, `/v1/webhooks/{id}` | The [Webhooks](https://dash.cloudraker.com/webhooks) page of Dash | Dash manages v2 endpoints.                                                       |
| `GET /v1/webhooks/jwks.json`        | `GET /.well-known/jwks.json`                                      | One JWKS for each organization, on its API host.                                 |

A `/v1` run id does not work on `/v2/jobs`. A job id does not work on `/v1/runs`.

### Routes with no `/v2` route

Keep these routes on `/v1`, with your `/v1` key.

| `/v1` routes                                                                                                     | Note                                                                                                                                                                                        |
| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /v1/compose/batch`, `/v1/compose/configs/*`                                                                | `POST /v2/generate` renders a saved template one time. Create the template on `/v1`.                                                                                                        |
| `POST /v1/pipeline`                                                                                              | Call each capability on `/v2`, or keep the pipeline on `/v1`.                                                                                                                               |
| `POST /v1/extract/batch`                                                                                         | Send one `POST /v2/extract` for each file.                                                                                                                                                  |
| `/v1/files`, `/v1/files/{id}`                                                                                    | `/v2` has no upload route. The `id` of a `POST /v1/files` file works as `{ "id": "…" }` on `/v2`.                                                                                           |
| `/v1/spaces/*`                                                                                                   | `/v2` has no spaces. This includes the capability routes under a space.                                                                                                                     |
| `/v1/templates/*`                                                                                                | Manage templates on `/v1`.                                                                                                                                                                  |
| `/v1/actions/*`, `/v1/extract/configs/*`, `/v1/classify/configs/*`, `/v1/fill/configs/*`, `/v1/redact/configs/*` | Manage saved configs on `/v1`. An `action` in the body of `POST /v2/extract` or `POST /v2/classify` still works.                                                                            |
| `/v1/agents/*`, `/v1/agent-runs/*`                                                                               | `POST /v2/agents/{base}/{agent}` starts a Run agent. It does not replace these routes.                                                                                                      |
| `/v1/paperwork-agents/*`, `/v1/work-sessions/*`                                                                  | Keep these routes on `/v1`.                                                                                                                                                                 |
| `/v1/automations/*`, `/v1/triggers/*`, `/v1/embeds/*`                                                            | Keep these routes on `/v1`.                                                                                                                                                                 |
| `/v1/realtime/transcriptions/*`                                                                                  | `POST /v2/transcribe` reads a file. It does not stream live audio.                                                                                                                          |
| `DELETE /v1/runs/{id}`, `POST /v1/runs/{id}/keep`                                                                | The API keeps a job for 30 days. `/v2` has no purge and no keep.                                                                                                                            |
| `/v1/runs/{id}/audit`, `/envelope`, `/void`, `/signers/{signerId}/resend`                                        | These routes need a `/v1` `sgr_` run id. A `/v2` sign job has no `sgr_` id while the envelope is open, so these routes do not apply to it. If you need them, keep `POST /v1/sign` on `/v1`. |

### Routes outside the `/v1` notice

These routes do not get the `Deprecation` and `Sunset` headers.

| Route           | Note                                                            |
| --------------- | --------------------------------------------------------------- |
| `/v1/signing/*` | The RakeSign API. It stays on `/v1`.                            |
| `/openai/v1/*`  | The OpenAI-compatible API. It has no `/v2` route.               |
| `/process`      | An older route with no version. It has no `/v2` route.          |
| `/me`           | `GET /v2/me` returns the credential of the request, not a user. |
| `/api-keys`     | These routes manage `/v1` keys. Dash manages `crk_` keys.       |

## Change the wait

| `/v1`                     | `/v2`                                                          |
| ------------------------- | -------------------------------------------------------------- |
| `?wait=60`                | `Prefer: wait=60`                                              |
| `?wait=0`                 | `Prefer: respond-async`                                        |
| `?wait=91` to `?wait=120` | `Prefer: wait=90` or less, then continue from the `202`        |
| No `wait` (default 60)    | No preference. The default is `wait=30` for most capabilities. |

`?wait=N` also works on `/v2`, but only from 1 to 90. `?wait=0` and a value above 90 give `400 wait_out_of_range`. The `Prefer` header wins when both are present.

`sign` and `transcribe` default to `respond-async`. Send a preference for `agents`.

A slow call does not fail. At the end of the wait, the job continues and the answer is `202`:

```http
HTTP/1.1 202 Accepted
Location: /v2/jobs/job_01JC9M…
Retry-After: 5
Preference-Applied: wait=30
```

The body of the `202` is the same job. Read the job with `GET /v2/jobs/{id}` and `Prefer: wait=N`, a [stream](/paperwork/v2/streaming) or a [webhook](/paperwork/v2/webhooks).

> **Warning**
>
> Behind a proxy with a 60-second idle timeout, use `wait=55` or less. Set the timeout of your HTTP client higher than the wait.

## Change the body

| `/v1` input                  | `/v2` input                            | Change                                                                                                                                                                                                                                                 |
| ---------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `webhook: { "url": "…" }`    | `notify: { "url": "…" }`               | Rename the field. `webhook` in the body gives `400 invalid_request`.                                                                                                                                                                                   |
| `webhook: { "id": "whe_…" }` | `notify: { "endpoint": "whe_…" }`      | Use the id of a v2 endpoint. Read [Move your webhooks](#move-your-webhooks).                                                                                                                                                                           |
| `ttl`                        | Remove it                              | `ttl` in the body gives `400 invalid_request`. The API keeps a job for 30 days.                                                                                                                                                                        |
| `metadata`                   | `metadata`                             | The API checks it but does not store it. The Job object has no metadata.                                                                                                                                                                               |
| `?output=inline`             | Remove it                              | Read both forms of [the output](/paperwork/v2/jobs#read-the-output).                                                                                                                                                                                   |
| `classifyRunId` on split     | `segments`, after a `/v2` classify job | `classifyRunId` takes only a `/v1` `clr_` run id. A `job_` id fails the job with `invalid_request`, and `error.details.cause` is `classify_run_mismatch`. Run classify with `granularity: "page"`, then copy `output.output.segments` into `segments`. |

If a capability has a `/v1` route with the same name, the body fields that are not in this table do not change. A body is JSON, with a maximum size of 1 MiB. Send a large file by URL.

`/v1` returned `metadata` on each read. On `/v2`, keep your own map from the job id to your identifiers.

## Read the Job object

| `/v1` run field                     | Job field                                        | Note                                                                     |
| ----------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------ |
| `object`, for example `extract_run` | `object` is `job`, and `capability` is `extract` |                                                                          |
| `id`, for example `exr_…`           | `id`, for example `job_…`                        |                                                                          |
| `status`                            | `status`                                         | Read the status table below.                                             |
| `statusUrl`                         | The `Location` header of a `202`                 |                                                                          |
| `output`                            | `output.output`                                  | Read [the output of a job](/paperwork/v2/jobs#read-the-output).          |
| `files`, `file`                     | `output.files`, `output.file`                    | On the durable path only.                                                |
| `error`                             | `error`                                          | A `processing_failed` error has the `/v1` code in `error.details.cause`. |
| `usage`                             | `usage`                                          | `{ credits, units }`. Null while the job runs.                           |
| `createdAt` (on a list)             | `created_at`, `completed_at`                     | Job fields use snake case.                                               |

| `/v1` status  | Job status    |
| ------------- | ------------- |
| `queued`      | `queued`      |
| `processing`  | `running`     |
| `processed`   | `succeeded`   |
| `needs_input` | `needs_input` |
| `failed`      | `failed`      |
| `cancelled`   | `cancelled`   |
| `expired`     | `expired`     |

The API keeps a job for 30 days. A later read gets `404 job_not_found`.

## Move your webhooks

### Create new endpoints

`/v1` saved endpoints are not shared with `/v2`. Add each endpoint again on the [Webhooks](https://dash.cloudraker.com/webhooks) page of Dash. Dash gives it a new `whe_` id.

An old `/v1` id in `notify.endpoint` gives `400 invalid_request`, and the API creates no job.

Keep your `/v1` endpoints until no `/v1` run can send an event.

### Change the verifier

A `/v1` verifier does not verify a v2 webhook. Write a new verifier from [Webhooks](/paperwork/v2/webhooks#verify-the-signature), or use `verifyWebhook` in the [SDK](/paperwork/v2/sdk#verify-a-webhook).

| Item          | `/v1`                                              | `/v2`                                                 |
| ------------- | -------------------------------------------------- | ----------------------------------------------------- |
| Header        | `x-rk1-signature`                                  | `x-cr-signature`                                      |
| Algorithm     | ES256                                              | RS256                                                 |
| Public keys   | `https://api.cloudraker.com/v1/webhooks/jwks.json` | `https://{slug}.cloudraker.run/.well-known/jwks.json` |
| `iss`         | `rakerone-process`                                 | `https://{slug}.cloudraker.run`                       |
| `aud`         | Not present                                        | The exact URL of the endpoint                         |
| Delivery id   | `eventId`                                          | `jti`                                                 |
| Job reference | `processingId`                                     | `job_id`                                              |
| Event type    | `type`                                             | `type`                                                |
| Body hash     | `bodySha256`, base64url                            | `body_sha256`, 64 lowercase hex characters            |

Use `jti` to drop a delivery that you already processed.

The body also changes. `data.job` is the Job object.

### Map the events

| `/v1` event                                           | `/v2` event                                                     |
| ----------------------------------------------------- | --------------------------------------------------------------- |
| `run.completed`                                       | `job.succeeded`                                                 |
| `run.failed`                                          | `job.failed`                                                    |
| `processing.completed`                                | `job.succeeded` or `job.failed`                                 |
| `processing.expired`                                  | `job.expired`                                                   |
| `processing.started`, `file.processed`, `file.failed` | No event. Use a [stream](/paperwork/v2/streaming) for progress. |
| No event                                              | `job.needs_input`, `job.cancelled`                              |
| `agent_run.*`, `space.expired`, work session events   | No event. These events stay on `/v1`.                           |

A job sends one event when it ends. `/v1` sends both `run.completed` and `processing.completed` for one run.

## Change the idempotency keys

The `Idempotency-Key` header stays. The rules change.

| Rule                 | `/v1`                     | `/v2`                        |
| -------------------- | ------------------------- | ---------------------------- |
| Same key, same body  | The first run             | The first job                |
| Same key, other body | The first run             | `409 idempotency_key_reused` |
| Scope of a key       | The organization          | The credential               |
| Replay header        | `idempotent-replay: true` | `idempotent-replayed: true`  |

The API compares the method, the path and the body. A key lives for 24 hours. If your code sends one key with different bodies, change it to send a new key for each new request.

Read [Idempotency](/paperwork/v2/idempotency).

## Change the error codes

The error body stays the same. Switch on `code` and use `retryable`.

| Cause              | `/v1`                   | `/v2`                                                  |
| ------------------ | ----------------------- | ------------------------------------------------------ |
| No credential      | `401 unauthorized`      | `401 missing_credential`                               |
| A bad credential   | `401 invalid_token`     | `401 invalid_api_key` or `401 invalid_token`           |
| No permission      | `403 forbidden`         | `403 insufficient_scope`                               |
| Too many requests  | `429 rate_limited`      | `429 rate_limit_exceeded` or `429 concurrency_limited` |
| No credits         | `402 credits_exhausted` | `402 credits_exhausted`                                |
| Unknown run or job | `404 not_found`         | `404 job_not_found`                                    |

A job can fail after the API accepts it. The answer is then `200` with the job in the `failed` status. Read the [job error codes](/paperwork/v2/jobs#job-error-codes) and [Errors](/paperwork/v2/errors).