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

# Sync and async

The client says how long it holds the connection. A slow call never fails because it is slow. It changes to async, and the job continues.

| Client sends                | Server does                                                                                             |
| --------------------------- | ------------------------------------------------------------------------------------------------------- |
| `Prefer: wait=30`           | Holds the request for up to 30 seconds. `200` with the job when it ends. `202` when it does not.        |
| `Prefer: respond-async`     | Answers `202` at once. An inline job holds the request while it runs. Read [Inline jobs](#inline-jobs). |
| `Accept: text/event-stream` | Streams the events of the job. Read [Streaming](/paperwork/v2/streaming).                               |
| `notify` in the body        | Sends a signed webhook. Read [Webhooks](/paperwork/v2/webhooks). It works with every mode.              |
| No preference               | The default of the capability.                                                                          |

## Wait

`Prefer: wait=N` accepts a whole number from 1 to 90. With no preference, the default of most capabilities is 30. Another value gives `400 wait_out_of_range`.

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

If the job still runs at the end of the wait, the answer is `202` with the same job:

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

{ "object": "job", "id": "job_01JC9M…", "capability": "parse", "status": "running" }
```

`?wait=N` is an alias of `Prefer: wait=N`. The header wins when both are present. The answer has `Preference-Applied` when the API applied a preference of the client.

> **Warning**
>
> Behind a proxy with a 60-second idle timeout, use `wait=55` or less. The status code goes out only at the end of the wait, so the API cannot send bytes to keep the connection open. A cut connection loses nothing: the job continues.

Set the timeout of your HTTP client higher than the wait. The [SDK](/paperwork/v2/sdk) uses a default timeout of 100 seconds.

## Respond async

`Prefer: respond-async` answers `202` at once:

```http
HTTP/1.1 202 Accepted
Location: /v2/jobs/job_01JC9M…
Retry-After: 5
Preference-Applied: respond-async
```

With `Prefer: respond-async, wait=N`, the API holds the request for up to `N` seconds, then answers `202`. `Preference-Applied` names `respond-async` only on a `202`.

An inline job does not answer at once. Read [Inline jobs](#inline-jobs).

## Inline jobs

`generate`, `convert`, and the redline `export` and `apply` jobs are inline jobs. An inline job does all of its work inside the request, so it has a time limit:

| Preference                                                        | The job must end within      |
| ----------------------------------------------------------------- | ---------------------------- |
| No preference, `Prefer: respond-async`, or a `wait` of 25 or more | 55 seconds after the request |
| `Prefer: wait=N` with `N` below 25                                | `N` + 30 seconds             |

A job that runs longer fails with `capability_lost`. Send a smaller file, or split a large `convert` into more jobs.

With `Prefer: respond-async`, the API holds the request while the job runs, for at most 30 seconds. This gives the job the same time as the default wait. A job that ends in that time answers `200` with its output, and the answer has no `Preference-Applied`. A job that still runs answers `202`, and the job continues. A webhook comes in both cases.

## Defaults

With no preference, the capability sets the default:

| Capabilities                                                                                | Default         |
| ------------------------------------------------------------------------------------------- | --------------- |
| `parse`, `extract`, `classify`, `split`, `fill`, `redact`, `generate`, `convert`, `redline` | `wait=30`       |
| `sign`, `transcribe`                                                                        | `respond-async` |

A sign job never answers `200` from the first call: a person signs later. An agent can run for a long time. Send a preference for `agents`.

## After a `202`

Use one of these methods:

* **Webhooks:** the API calls your endpoint when the job ends. Read [Webhooks](/paperwork/v2/webhooks).
* **A stream:** `GET /v2/jobs/{id}` with `Accept: text/event-stream`. Read [Streaming](/paperwork/v2/streaming).
* **A wait:** `GET /v2/jobs/{id}` with `Prefer: wait=N`. The server holds the request until the job ends, needs input, or the wait ends. The answer is `200` with the job. Check `status`, and call again if the job still runs.

A wait also ends when the job reaches `needs_input`, because a client cannot wait for a person.

## Body fields

These fields are in the JSON body of a capability call, next to the input of the capability:

| Field      | Meaning                                                                                                   |
| ---------- | --------------------------------------------------------------------------------------------------------- |
| `deadline` | When the work must finish. Only `"asap"`. Another value gives `400 deadline_not_supported`.               |
| `notify`   | `{ "url": "https://…" }` or `{ "endpoint": "whe_…" }`. Read [Webhooks](/paperwork/v2/webhooks#subscribe). |
| `metadata` | A JSON object of at most 10 KiB. The API checks it and does not store it. The Job object has no metadata. |