Parse a document or audio file

POST

https://api.cloudraker.com/v1/spaces/:spaceId/parse

POST

/v1/spaces/:spaceId/parse

$ curl -X POST https://api.cloudraker.com/v1/spaces/spaceId/parse \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "file": {
>     "url": "string"
>   }
> }'

1 {
2   "object": "string",
3   "id": "string",
4   "status": "queued",
5   "expiresAt": "string",
6   "statusUrl": "string",
7   "files": [
8     {
9       "id": "string",
10       "name": "string",
11       "status": "string",
12       "error": "string"
13     }
14   ],
15   "file": {
16     "id": "string",
17     "name": "string",
18     "status": "string",
19     "error": "string"
20   },
21   "error": {
22     "code": "string",
23     "message": "string"
24   },
25   "metadata": {},
26   "tasks": [
27     {
28       "id": "string",
29       "title": "string",
30       "url": "string"
31     }
32   ],
33   "output": {
34     "markdownUrl": "string",
35     "jsonUrl": "string",
36     "markdown": "string"
37   }
38 }

Turns any document or audio file into clean markdown plus structured JSON — audio becomes a transcript.

Nothing else runs: parsing is the whole job, and output carries markdownUrl and jsonUrl (signed, ~1 hour). Add ?output=inline for a one-call response that also carries markdown and parsed json. Inline source is capped at 1 MiB across both artifacts; larger output keeps the URLs only. Point file at a URL, or at a file you already registered with POST /v1/files.

Choosing an engine with file.processing:

Value	Use it for
`auto`	The default — self-upgrades to OCR when the page is a scan
`ocr`	Force optical character recognition
`simple`	Text-layer only, fastest
`transcribe`	Audio and video
`transcribe_diarize`	Audio and video, with speaker labels

1 { "file": { "url": "https://www.irs.gov/pub/irs-pdf/fw9.pdf" } }

Waiting for the result

Sync by default: the call holds open until the run finishes, up to ?wait= seconds (default 60, max 120, 0 returns immediately).

Outcome	Response
Finished inside the window	`200` with the full run
Still running at the cap	`202` with `{object, id, status, statusUrl}`
Parked for a human	`202` right away, `status: "needs_input"` plus `tasks[]`

The 202 is a graceful degrade, never an error — poll the run or wait for a webhook. Replaying an idempotency-key returns the original run alongside an idempotent-replay: true response header.

Learn more: Parsing guide

Turns any document or audio file into clean markdown plus structured JSON — audio becomes a transcript. Nothing else runs: parsing is the whole job, and `output` carries `markdownUrl` and `jsonUrl` (signed, ~1 hour). Add `?output=inline` for a one-call response that also carries `markdown` and parsed `json`. Inline source is capped at 1 MiB across both artifacts; larger output keeps the URLs only. Point `file` at a URL, or at a file you already registered with [POST /v1/files](https://docs.cloudraker.com/api/cloud-raker-api/files/create-file). **Choosing an engine** with `file.processing`: | Value | Use it for | | --- | --- | | `auto` | The default — self-upgrades to OCR when the page is a scan | | `ocr` | Force optical character recognition | | `simple` | Text-layer only, fastest | | `transcribe` | Audio and video | | `transcribe_diarize` | Audio and video, with speaker labels | ```json { "file": { "url": "https://www.irs.gov/pub/irs-pdf/fw9.pdf" } } ``` ### Waiting for the result Sync by default: the call holds open until the run finishes, up to `?wait=` seconds (default `60`, max `120`, `0` returns immediately). | Outcome | Response | | --- | --- | | Finished inside the window | `200` with the full run | | Still running at the cap | `202` with `{object, id, status, statusUrl}` | | Parked for a human | `202` right away, `status: "needs_input"` plus `tasks[]` | <Note> The `202` is a graceful degrade, never an error — poll [the run](https://docs.cloudraker.com/api/cloud-raker-api/runs/get-run) or wait for a [webhook](https://docs.cloudraker.com/api/cloud-raker-api/webhooks/create-webhook-endpoint). Replaying an `idempotency-key` returns the original run alongside an `idempotent-replay: true` response header. </Note> **Learn more:** [Parsing guide](https://docs.cloudraker.com/capabilities/parse)

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

spaceIdstringRequired

Query parameters

waitintegerOptional0-120Defaults to 60

How many seconds to hold the request open waiting for the run to finish.

Finishing inside the window returns 200 with the full run; running past it returns 202 with a statusUrl to poll. Send 0 to skip waiting entirely and always get the 202.

outputenumOptionalDefaults to urls

How parsed source content is returned.

urls returns signed download URLs. inline also returns markdown and parsed JSON when their combined payload is at most 1 MiB; larger content falls back to the URLs only.

Allowed values:

Request

This endpoint expects an object.

fileobjectRequired

An input file, given one of two ways.

{ "url": "…", "name"?: "…", "processing"?: "…" } — fetched over http(s) for this run and purged with it.
{ "id": "…" } — a file you already registered with POST /v1/files, reusable across runs and never re-parsed.

metadatamap from strings to anyOptional

Arbitrary JSON you attach to the run and get back on every read of it.

Use it to carry your own identifiers — an order number, a customer id — so a webhook or a polled run reconciles without a lookup table. Capped at 10 KB serialized.

webhookobjectOptional

Where to deliver this run’s events, given one of two ways.

{ "url": "…" } — a one-off https endpoint for this run only.
{ "id": "whe_…" } — a saved endpoint from POST /v1/webhooks. Runs hold the reference, so pausing or re-pointing that endpoint applies to this run too.

Deliveries are at-least-once and signed — dedupe on eventId and verify against GET /v1/webhooks/jwks.json.

ttlintegerOptional1-604800Defaults to 86400

How long, in seconds, to keep this run and its files before purging them automatically.

The maximum is 604800 (7 days). The deadline comes back as expiresAt on every read of the run. Call POST /v1/runs/{id}/keep before then to clear the TTL and move the results into a space permanently.

E-signature runs are exempt — an envelope waits for its signers however long that takes.

Response

The finished run.

object"parse_run"

idstring

statusenum

Where the run is in its life.

Status	Meaning
`queued`	Accepted, not started
`processing`	Work in flight
`needs_input`	Parked for a person — see `tasks[]`
`processed`	Finished; `output` is populated
`failed`	Finished unsuccessfully
`cancelled`	Stopped on request
`expired`	TTL elapsed and the data was purged

The last four are terminal.

expiresAtstring or null

statusUrlstring

fileslist of objects

fileobjectOptional

errorobjectOptional

Why the run failed. Present whenever status is failed, and only then.

code is the stable, snake_case reason (input_unavailable, parse_failed, …); message is the human-readable detail. Per-file and per-step failures are also reported in files[].error and, for a pipeline, steps[].error.

metadatamap from strings to anyOptional

taskslist of objectsOptional

The human steps currently blocking the run. Present while status is needs_input.

Each task has a url — a ready-made page you can send a person to — or you can drive it yourself through GET and POST /v1/runs/{id}/task. E-signature runs never carry tasks[]: their signing links are signer-held secrets, so use envelopeUrl instead.

outputobjectOptional

The parsed document. Present once status is processed.

Both links are signed and valid for about an hour: markdownUrl for the readable form, jsonUrl for the structured one. With ?output=inline, markdown and parsed json are included too when their combined payload is at most 1 MiB; larger content falls back to the URLs only.

Errors

400

Bad Request Error

422

Unprocessable Entity Error

429

Too Many Requests Error