Process documents

Process API

Upload documents and run actions in one call, then poll for parsed text, extractions, and evidence.
View as Markdown

The /process API is a one-call ingestion pipeline. You send files and an optional list of actions in a single multipart request; CloudRaker parses each file, runs the actions, holds the results for a TTL you choose, and then auto-purges everything. You get back a processing id to poll — and, if you want, signed webhooks as each event happens.

It’s the fastest way to turn documents into structured data from your own backend, with no spaces or manual file management to wire up.

For new integrations, prefer the JSON capability endpoints — extract and parse. They take a file URL or id instead of multipart, return the result in the same call, and cite every extracted field. /process stays supported and unchanged for the integrations already on it.

Authorization is org-level: the caller must be an org API key or an org admin.

The flow

1

Start a pipeline

POST /process with your files and options.

2

Poll for status and results

GET /process/{id} until status is done (or failed / expired).

3

(Optional) purge early

DELETE /process/{id} cancels in-flight work and deletes everything now — or let it expire on its own.

Start a pipeline

POST /process takes multipart/form-data: one part named options (JSON) plus one part per file you declare.

The options part

1{
2  "files": [
3    { "field": "invoice", "processingKind": "doc-auto" }
4  ],
5  "actions": ["<installedActionId or slug>"],   // optional; default []
6  "callbackUrl": "https://example.com/webhooks/rakerone",  // optional
7  "durationSeconds": 86400              // optional TTL; default 86400 (24h), max 604800 (7d)
8}
  • files[] — one entry per file. field must match the name of a multipart part carrying that file’s bytes. processingKind is optional.
  • actions[] — the installed actions to run against the ingested files. Each entry is an installed action’s id or its per-organization slug — the two are interchangeable everywhere the API takes an installed action. Optional; defaults to none.
  • callbackUrl — a receiver for signed webhook events. Optional.
  • durationSeconds — how long results live before auto-purge. Default 24h, max 7 days.

processingKind is one of:

ValueFor
doc-simpleText-native documents, fastest path
doc-ocrScanned / image documents needing OCR
doc-autoLet CloudRaker choose between simple and OCR
audio-transcribeAudio → transcript
audio-transcribe-and-diarizeAudio → transcript with speaker labels

Request

$curl -X POST https://api.cloudraker.com/process \
>  -H "Authorization: Bearer $RAKERONE_API_KEY" \
>  -F 'options={"files":[{"field":"invoice","processingKind":"doc-auto"}]};type=application/json' \
>  -F 'invoice=@./invoice.pdf'

Response — 201

1{
2  "processingId": "…",
3  "expiresAt": "2026-07-21T00:00:00.000Z",
4  "statusUrl": "/process/<processingId>"
5}

Pipeline order: each file is ingested and parsed → any declared actions are dispatched → results are collected → webhooks are emitted → everything is held until the TTL, then auto-purged.

The request body is capped by the platform (on the order of 100 MB). For large files, register them into a space with the presigned upload flow instead, which streams straight to object storage.

Possible errors: 400 (malformed multipart or manifest), 403 (caller is neither an org admin nor an org API key).

Poll for status and results

GET
/process/:id
1curl https://api.cloudraker.com/process/id \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json"
Try it

Query parameters

  • include — comma-separated list of content, results, evidence. These heavier payloads are inlined only when you ask for them.
  • format — json (default) or markdown.

ProcessStatus response

1{
2  "processingId": "…",
3  "status": "preprocessing | running | done | failed | expired",
4  "expiresAt": "…",
5  "files": [
6    { "fileId": "…", "fileName": "invoice.pdf", "processingKind": null,
7      "status": "…", "error": null, "content": null }
8  ],
9  "actions": [
10    { "runId": null, "installedActionId": "…", "status": "…", "error": null, "result": null }
11  ]
12}

content (per file), results (per action), and evidence appear only when requested via include.

Audio files have no markdown byproduct. include=content&format=markdown returns null for audio content — use format=json.

Poll responses

StatusBodyMeaning
200ProcessStatusFound — keep polling until status is done, failed, or expired
404{"error":"not_found"}Unknown id, or hard-wiped after the grace window
410{"error":"expired"}Purged, still inside the post-TTL grace window

Purge early

DELETE
/process/:id
1curl -X DELETE https://api.cloudraker.com/process/id \
2     -H "Authorization: Bearer <token>"
Try it

Immediately cancels in-flight work and deletes files, runs, and stored results. Returns 204.

TTL and lifecycle

A pipeline lives until expiresAt (durationSeconds from creation; default 24h, max 7 days). At expiry, CloudRaker cancels runs, purges outputs, deletes the files, emits a processing.expired webhook, and then serves the id as 410 for a short grace window (~24h) before hard-wiping it to 404. Fetch everything you need before expiresAt, or extend the TTL at creation.

Where to go next

Webhooks

Verify the signed events /process emits, instead of polling.

Files and uploads

The space-scoped presigned upload flow for large files and persistent storage.