Document extraction API

Set BASE to the Rahunko origin, choose a workspace and use a Bearer key with the required scope. The sequence sends one immutable file through upload, processing, review and export.

Read the API reference

011. Create the upload intent

Prepare the exact file metadata locally, write it to intent.json and send the upload intent with the required write scope. The response gives you upload.id for the next step.

Use an idempotency key between 8 and 128 characters from the safe character set.
The declared hash must be SHA-256 of the exact file bytes.
A retry with the same body is replayed. A different body returns a conflict.

BASE="https://your-rahunko-origin.example"
WORKSPACE_ID="ws_123"
API_KEY="rk_replace_with_your_key"
BYTE_LENGTH=$(wc -c < march.pdf | tr -d ' ')
SHA256=$(shasum -a 256 march.pdf | awk '{print $1}')

cat > intent.json <<JSON
{
  "fileName": "march.pdf",
  "mediaType": "application/pdf",
  "byteLength": $BYTE_LENGTH,
  "sha256": "$SHA256",
  "sourceKind": "pdf"
}
JSON

curl -X POST "$BASE/api/v1/workspaces/$WORKSPACE_ID/uploads" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: march-2026-upload-01" \
  -H "Content-Type: application/json" \
  --data-binary @intent.json

022. Send bytes and finalize

Send the same bytes whose length and digest you declared, then finalize with an empty JSON object. Finalize returns 202 with the document, job and initial revision.

Send Content-Length matching the declared byte length.
Wrong length, MIME type, file signature or hash is rejected.
Finalize accepts the empty JSON object {}.

UPLOAD_ID="upload_from_intent_response"

curl -X PUT "$BASE/api/v1/workspaces/$WORKSPACE_ID/uploads/$UPLOAD_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/pdf" \
  -H "X-Content-SHA256: $SHA256" \
  --data-binary "@march.pdf"

curl -X POST "$BASE/api/v1/workspaces/$WORKSPACE_ID/uploads/$UPLOAD_ID/finalize" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

033. Follow status and export

Follow the job until processing is complete, read the document and use the current matching revision for export. The export response is the file itself, so the command saves it directly.

Replace 3 with the current document and review revision.
Cancel with POST .../documents/{documentId}/cancel and {"revision":N}.
Delete with DELETE .../documents/{documentId} and the same revision body.

JOB_ID="job_from_finalize_response"
DOCUMENT_ID="document_from_finalize_response"
REVISION=3

curl "$BASE/api/v1/workspaces/$WORKSPACE_ID/jobs/$JOB_ID" \
  -H "Authorization: Bearer $API_KEY"

curl "$BASE/api/v1/workspaces/$WORKSPACE_ID/documents/$DOCUMENT_ID" \
  -H "Authorization: Bearer $API_KEY"

curl "$BASE/api/v1/workspaces/$WORKSPACE_ID/documents/$DOCUMENT_ID/export?format=csv&revision=$REVISION" \
  -H "Authorization: Bearer $API_KEY" \
  -o march.csv

API errors are JSON with a stable code: commonly 401 for an invalid key, 403 for a missing scope, 409 for a state or revision conflict and 422 for rejected bytes.