Parse

POST /v1/parse takes one document. It returns readable markdown plus a structured JSON representation with layout and page information. It needs no schema and no configuration. Use it when you want the document’s content, not specific fields.

How it works

1. You send a file: a URL, or the id of a file you already have.
2. CloudRaker fetches the bytes and reads the document. Born-digital PDFs are read directly, scans through OCR, office files through conversion, and audio through transcription.
3. The call holds until parsing finishes, up to ?wait= seconds (60 by default, 120 max). If parsing finishes in time, you get 200 with download URLs. If not, you get 202 with a run id to poll.
4. The run and its files expire on their own (ttl, 24 hours by default).

Extraction parses too, so you do not need to call this first. POST /v1/extract parses as part of the run.

Quickstart

The sample below uses a blank IRS Form W-9 as a public, stable test document. The call works with no local files.

$
curl -X POST https://api.cloudraker.com/v1/parse \
>
  -H "Authorization: Bearer $CLOUDRAKER_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "file": { "url": "https://www.irs.gov/pub/irs-pdf/fw9.pdf", "name": "w9.pdf" }
>
  }'

Example response

1
{
2
  "object": "parse_run",
3
  "id": "par_01KYD1M2XT5Q8VB3NRWY7CDEFG",
4
  "status": "processed",
5
  "expiresAt": "2026-07-26T15:57:41.907Z",
6
  "statusUrl": "/v1/runs/par_01KYD1M2XT5Q8VB3NRWY7CDEFG",
7
  "files": [
8
    { "id": "4c9de1b7-8a30-42f5-b0e6-1d7f5c2a9b44", "name": "w9.pdf", "status": "processed" }
9
  ],
10
  "file": { "id": "4c9de1b7-8a30-42f5-b0e6-1d7f5c2a9b44", "name": "w9.pdf", "status": "processed" },
11
  "output": {
12
    "markdownUrl": "https://cdn.cloudraker.com/acme/4c9de1b7-8a30-42f5-b0e6-1d7f5c2a9b44/processed.md?token=…&fn=w9.pdf",
13
    "jsonUrl": "https://cdn.cloudraker.com/acme/4c9de1b7-8a30-42f5-b0e6-1d7f5c2a9b44/processed.json?token=…&fn=w9.pdf"
14
  }
15
}

Key fields

output appears only after status is processed. The download URLs are short-lived. Fetch the content instead of storing the URL.

Reuse the returned file id (files[0].id) in later calls. Pass {"file": {"id": "<file id>"}} to extract. The document is then not fetched or parsed again.

Configuration

processing on the file ref picks how the document is read:

Sync vs async

Identical to extract: synchronous by default, with ?wait= between 0 and 120 seconds. When the cap is reached, you get a 202 handle, not a timeout error.

1
{
2
  "object": "parse_run",
3
  "id": "par_01KYD1M2XT5Q8VB3NRWY7CDEFG",
4
  "status": "processing",
5
  "statusUrl": "/v1/runs/par_01KYD1M2XT5Q8VB3NRWY7CDEFG"
6
}

Long audio and large scanned documents normally come back as 202. For those, pass ?wait=0, then poll or use a webhook.

Save as a config

Parsing has no configuration to save. There is no /v1/parse/configs library and nothing in GET /v1/actions/catalog. The saved-config path applies to extract, redact, and fill.

Next steps