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

# Streaming

Send `Accept: text/event-stream` on `POST /v2/{capability}` or on `GET /v2/jobs/{id}`. The answer is a stream of server-sent events (SSE) for one job.

```bash
curl -N -X POST "https://$CRK_SLUG.cloudraker.run/v2/parse" \
  -H "Authorization: Bearer $CRK_API_KEY" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{ "file": { "url": "https://www.irs.gov/pub/irs-pdf/fw9.pdf" } }'
```

`-N` turns off the curl buffer. A `POST` stream has a `Location: /v2/jobs/{id}` header, so you can also read the job later.

## Frames

Each event has an `id`, an `event` type and a JSON `data` line:

```text
id: 1
event: job.progress
data: {"seq":1,"type":"job.progress","created_at":"2026-11-07T14:02:12Z","job_id":"job_01JC9M…","data":{"step":1,"total":6,"message":"Parsing page 1"}}

id: 2
event: job.succeeded
data: {"seq":2,"type":"job.succeeded","created_at":"2026-11-07T14:02:13Z","job_id":"job_01JC9M…","data":{"job":{"object":"job","id":"job_01JC9M…","status":"succeeded"}}}
```

| Event             | Terminal | `data`                                                         |
| ----------------- | -------- | -------------------------------------------------------------- |
| `job.progress`    | No       | `{step?, total?, message?}`: the progress of the job.          |
| `job.needs_input` | No       | `{job}`: the job as it was at the event. The stream continues. |
| `job.succeeded`   | Yes      | `{job}`: the final job, with its `output`.                     |
| `job.failed`      | Yes      | `{job}`: the final job, with its `error`.                      |
| `job.cancelled`   | Yes      | `{job}`: the final job.                                        |
| `job.expired`     | Yes      | `{job}`: the final job.                                        |

The stream ends after the terminal event. A run that fails during a `POST` stream gives the terminal event `job.failed` in the stream, not a `503`.

`seq` is unique in the job and goes up. It can have gaps, because a new progress event can replace the one before it. For an agent job, `seq` is the seq of the Run event.

## Heartbeats

The API writes the comment line `: hb` every 15 seconds. It keeps the connection open through a proxy. An SSE client ignores a comment line.

## Resume a stream

A stream ends after 15 minutes, even if the job continues. A connection can also break. Resume with the last event id that you read:

```bash
curl -N "https://$CRK_SLUG.cloudraker.run/v2/jobs/job_01JC9M…" \
  -H "Authorization: Bearer $CRK_API_KEY" \
  -H "Accept: text/event-stream" \
  -H "Last-Event-ID: 2"
```

The API sends the events with a higher `seq`, then the live events.

| Result                                        | Answer                    |
| --------------------------------------------- | ------------------------- |
| The job ended, and the client has every event | `204`                     |
| `Last-Event-ID` is not a whole number         | `400 invalid_request`     |
| The credential cannot read the job            | `404 job_not_found`       |
| Too many open streams on this tenant          | `429 concurrency_limited` |

A `Prefer: wait` preference does not apply to a stream.

If the API cannot open a stream on `POST /v2/{capability}`, it answers with the JSON of the job, as with no stream. Check the `content-type` of the answer.

An open stream of a key ends when you revoke the key or it expires. The stream stops with no terminal event and no job output. A stream of a `crt_` token ends when you delete its trust.