Parse

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

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 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). Finished in time gives 200 with download URLs; otherwise 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 don’t need to call this first — POST /v1/extract does it as part of the run.

Quickstart

The sample below uses a blank IRS Form W-9 as a public, stable test document, so 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 once status is processed. The download URLs are short-lived; fetch the content rather than storing the URL.

Reuse the returned file id (files[0].id) in later calls — pass {"file": {"id": "<file id>"}} to extract and the document is 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, ?wait= between 0 and 120 seconds, and a 202 handle instead of a timeout error when the cap is reached.

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 will normally come back as 202 — pass ?wait=0 and poll or use a webhook for those.

Save as an action

Parsing has no configuration to save, so there’s nothing to turn into an action — it doesn’t appear in GET /v1/actions/catalog either. The saved-configuration path applies to extract, redact, fill, and sign.

Next steps