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 one multipart request. CloudRaker parses each file and runs the actions. It holds the results for a TTL you choose, then purges everything. You get a processing id to poll. You can also receive signed webhooks as each event happens.

This is the fastest way to turn documents into structured data from your backend. You do not set up spaces or manage files.

For new integrations, use the JSON capability endpoints — extract and parse. They take a file URL or id instead of multipart. They 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.

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 that carries the 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 — the time results live before auto-purge. Default 24h, max 7 days.

processingKind is one of:

ValueFor
doc-simpleText-native documents, fastest path
doc-ocrScanned or image documents that need OCR
doc-autoCloudRaker chooses 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: CloudRaker ingests and parses each file. It dispatches the declared actions and collects the results. It emits webhooks, holds everything until the TTL, then purges it.

The platform caps the request body at approximately 100 MB. For large files, register them into a space with the presigned upload flow instead. That flow streams directly to object storage.

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

Poll for status and results

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

Query parameters

  • include — comma-separated list of content, results, evidence. The API inlines these heavier payloads only when you request 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 you request them with include.

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

Action results

actions[].result arrives with include=results, once that action’s status is done. Its shape depends on what the action produces.

Actions that extract data (extract) return the grounded result. docs[] holds one entry per source file, data holds the extracted fields, and evidence cites them. Citations are heavy, so they appear only with include=results,evidence.

1{
2  "version": 1,
3  "unit": "per_document",
4  "fieldKeys": ["total"],
5  "docs": [
6    { "id": "file_…", "name": "invoice.pdf", "status": "done",
7      "data": { "total": "1240.00" },
8      "evidence": { "total": [{ "fileId": "file_…", "page": 2, "text": "1,240.00" }] } }
9  ]
10}

Actions that produce a file (redact, fill, sign, generate, split) return output and files. output is the action’s own report. files resolves the ids in output.documentIds to download links valid about one hour — fetch them before they expire, or poll again for fresh ones.

1{
2  "output": { "documentIds": ["file_…"], "summary": { "PERSON": 3 }, "skipped": 0 },
3  "files": [
4    { "id": "file_…", "name": "consult-redacted.pdf", "url": "https://cdn.cloudraker.com/…" }
5  ]
6}

Actions that return neither — classify, connector-call — carry output alone, with no files.

When there is no result

FieldMeaning
result presentThe action produced this result.
result: nullThe action produced no result. A fact about the run, not a failure.
resultErrorThe result could not be read — the platform, not your call. Poll again; the run itself is unaffected.

result: null and resultError are distinct. Do not treat a missing result as an error, and do not treat a read failure as an empty result.

Poll responses

StatusBodyMeaning
200ProcessStatusFound. Poll 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

Cancels in-flight work immediately. 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, and deletes the files. It emits a processing.expired webhook. The id then answers 410 for a short grace window (~24h), then 404 after the hard wipe. Fetch everything you need before expiresAt, or set a longer 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.