Tooling

API context for agents

The whole CloudRaker API contract on one page — written to be fetched as Markdown by a coding agent.

View as Markdown

Point a coding agent at https://docs.cloudraker.com/developers/agents.md and it has everything it needs to write a working integration: auth, the request and error envelopes, all six verbs, the run lifecycle, multi-step agent runs, the schema dialect, and the limits.

$curl -s https://docs.cloudraker.com/developers/agents.md

Every page on this site has the same .md twin, and https://docs.cloudraker.com/llms.txt indexes them all. This page is the one to start from.

Base URL and auth

Base URL: https://api.cloudraker.com. Every request carries an organization API key as a bearer token:

Authorization: Bearer $CLOUDRAKER_API_KEY
Content-Type: application/json

One key belongs to one organization; the key is the tenant, so no tenant, account, or workspace id is ever passed. Keys are created in the app under Admin → API keys and shown once. Staging (https://api.staging.raker.one) and development (https://api.dev.raker.one) are separate environments with separate keys.

The six verbs

Each is a single POST that creates a run, is synchronous by default, and accepts ?wait= (0–120 seconds, 60 default). Minimal bodies:

1// POST /v1/extract — document -> JSON matching your schema; add "citations": true for evidence
2{ "file": { "url": "https://example.com/invoice.pdf" }, "citations": true,
3  "schema": { "type": "object", "properties": { "total": { "type": ["number", "null"] } } } }
4
5// POST /v1/extract — no schema: infer one, then extract with it (exploration only)
6{ "file": { "url": "https://example.com/invoice.pdf" }, "hints": "It's an invoice; capture the header fields" }
7
8// POST /v1/extract/batch — one saved action over many files; always 202
9{ "action": "invoice-header", "files": [{ "url": "…" }, { "url": "…" }] }
10
11// POST /v1/parse — document -> markdown + structured JSON, no schema
12{ "file": { "url": "https://example.com/contract.pdf" } }
13
14// POST /v1/redact — destructive PII removal; returns a NEW file
15{ "file": { "id": "<fileId>" }, "categories": ["ssn", "ein"], "mode": "targeted" }
16
17// POST /v1/fill — fill a form PDF from source documents
18{ "template": { "id": "<templateId>" }, "files": [{ "id": "<fileId>" }], "review": "none", "output": "flattened" }
19
20// POST /v1/sign — e-signature envelope; always 202, status needs_input
21{ "file": { "id": "<fileId>" }, "signers": [{ "name": "Jane Doe", "email": "[email protected]" }] }
22
23// POST /v1/pipeline — several capabilities over one file set, in parallel (not chained)
24{ "files": [{ "url": "…" }],
25  "steps": [{ "extract": { "schema": { "type": "object", "properties": {} } } }, { "redact": { "categories": ["ssn"] } }] }

Shared optional fields on every verb: metadata (your own key/values, ≤10 KB, echoed back and filterable), webhook ({url} or {id}), ttl (seconds, default 86400, max 604800), and the idempotency-key request header.

Citations are off by default everywhere. Send "citations": true on POST /v1/extract, on POST /v1/extract/batch, or on an extract step inside a pipeline to get them; on a saved action the grounding install setting does the same and also defaults to false.

extract, redact, fill, and sign also accept action: "<id or slug>" instead of inline config; inline fields win over the saved ones. Save one with POST /v1/actions {capability, name, config}; discover configurable shapes with GET /v1/actions/catalog.

File references

Anywhere a file is taken, the value is one of two shapes — never a multipart upload:

1{ "url": "https://…", "name": "invoice.pdf", "processing": "auto" }  // fetched server-side
2{ "id": "a04d6597-4e34-4a99-94ea-964c289a4c68" }                     // already registered or produced

processing: auto (default), ocr, simple, transcribe, transcribe_diarize. Single-file verbs take file; multi-file verbs take files[] (up to 100). Sending both is a 400.

Register a persistent file with POST /v1/files — either {url, name?} (the source must serve a Content-Length) or {name, mimeType}, which returns an uploadUrl valid 15 minutes that you PUT the bytes to with the identical Content-Type. Poll GET /v1/files/:id until status: "ready". Files a run creates inline expire with the run; files you register do not.

Runs

GET    /v1/runs                   list (filters below)
GET    /v1/runs/:id               status + result; accepts ?wait=
POST   /v1/runs/:id/cancel        stop in-flight work
DELETE /v1/runs/:id               purge now (204, idempotent)
POST   /v1/runs/:id/keep          persist into a space; clears the TTL
GET    /v1/runs/:id/output/:name  302 to a signed download URL

Id prefixes: exr_ extract, par_ parse, rdr_ redact, flr_ fill, sgr_ sign, plr_ pipeline. Treat ids as opaque strings.

Statuses: queued, processing, processed, failed, cancelled, expired, needs_input. output exists only at processed. needs_input means a human is required — a fill review (tasks[]) or an open signature envelope (envelopeUrl).

A synchronous call that doesn’t finish within ?wait= returns 202 with the run handle, never a timeout error — poll statusUrl or use a webhook. Sign runs are exempt from the TTL purge while the envelope is open; every other run and its inline files are purged at expiresAt.

GET /v1/runs takes object, status (the six values above minus queued), limit (1–50, default 20), cursor, and up to three metadata.<key>=<value> pairs. It returns {object:"list", data:[…handles…], has_more, cursor} and is eventually consistent — GET /v1/runs/:id is authoritative.

Agents and agent runs

A separate surface from the verbs and from /v1/runs. An agent is a saved, versioned, multi-step automation (steps + saved actions + sign-off gates); an agent run (agr_…) is one execution of it that can wait days on a person.

GET  /v1/agents                                  agents you can run
GET  /v1/agents/:id                              one agent: tasks[], actions[], version
POST /v1/agent-runs                              start one; ?wait= 0–120, default 60
GET  /v1/agent-runs/:id                          read it; ?wait= 0–120, default 0
POST /v1/agent-runs/:id/approvals/:approvalId     {decision: "approve"|"reject", note?, params?, files?}
POST /v1/agent-runs/:id/tasks/:taskId/complete    {note?, files?} — send {} if neither
1// POST /v1/agent-runs — files 1–200, metadata ≤10 KB, no ttl
2{ "agent": "<agentId>", "files": [{ "url": "https://example.com/intake.pdf" }],
3  "metadata": { "caseId": "42" }, "webhook": { "url": "https://example.com/hooks" } }

Statuses: queued, processing, waiting, paused, completed, failed, cancelled, expired. A completed run with unfinished work also carries incomplete: true; paused (paused.reason) is resumable, not a failure. The run carries tasks[] (executor: "agent"|"human", status: pending|ready|in_progress|completed|skipped), approvals[] (kind: "before"|"output", with the proposed params and files), waiting: {approvals, tasks, summary}, progress.tasks, result, output.files[] (signed ~1 h), error, metadata, expiresAt (~7 days).

Rules that differ from capability runs:

  • A queued agent run must be polled — reading it is what picks it up once its files are prepared. A webhook alone leaves it queued.
  • No list, no cancel, no delete, and agent runs never appear in GET /v1/runs. Keep the agr_ id, or tag runs with metadata.
  • No ttl. Files passed by URL become persistent files. expiresAt (~7 days) is the deadline: an unfinished run parks for good past it.
  • Only executor: "human" steps are completable (422 otherwise); unmet dependsOn or an already-closed step is 409. Rejecting an approval requires note. Deciding the same approval twice is 409.
  • Webhook events: agent_run.waiting, agent_run.approval_requested (minimal — re-read the run for params), agent_run.task_ready, agent_run.completed, agent_run.failed (also carries cancelled/expired; trust data.status). Same signature and JWKS as every other delivery, with processingId carrying the agr_ id.

Extract output

1{
2  "object": "extract_run", "id": "exr_…", "status": "processed",
3  "config": { "schema": { /* the schema actually applied — inline, saved, or inferred */ } },
4  "output": {
5    "value": { "total": 1889.45, "po_number": null },  // alias of documents[0].value
6    "citations": {                                     // only when the run was grounded; field path -> evidence
7      "total": [{ "fileId": "…", "page": 0, "bbox": { "x": 0.1, "y": 0.2, "width": 0.1, "height": 0.02 },
8                  "text": "CAD 1,889.45", "confidence": 5 }],
9      "po_number": [{ "fileId": "…", "notFound": true }]  // declared absent; value is null, never a guess
10    },
11    "documents": [{ "fileId": "…", "name": "invoice.pdf", "status": "done", "value": { /* … */ }, "citations": { /* same shape, per document */ } }]
12  }
13}

page is 0-based; bbox is normalized 0–1 with a top-left origin; confidence is 0–5. Audio grounds with a timecode instead of page/bbox. A notFound entry carries only fileId — no page, bbox, timecode, text, or confidence. A field the document doesn’t contain comes back null, which is why every property should be declared nullable.

Grounding is guaranteed-or-flagged: when citations are on, every filled field comes back with at least one citation or an explicit notFound declaration — a deterministic second model pass cites or declares absent anything the first pass left uncited. When the run was not grounded the citations key is absent entirely, never an empty object. citationsOmitted: true on output means citations were dropped because the result exceeded the size budget; it is output-level only and never appears per document.

Extraction schema dialect

Plain JSON Schema with four constraints, checked before the run starts (400 invalid_schema, with the offending path):

  1. The root must be {"type": "object"}.
  2. Nesting may not exceed 5 levels.
  3. No $defs, $ref, oneOf, anyOf, allOf, const, or pattern — these are the only rejected keywords, and only in keyword positions (a property named pattern is fine). Constrain values with enum; describe formats in description.
  4. The serialized schema must stay under 64 KB.

Making every primitive nullable — {"type": ["string", "null"]} — is recommended, never enforced: a non-nullable field pressures the extractor into inventing a value instead of returning null. It is the single highest-impact change to extraction quality. With citations on, an absent value is also marked notFound rather than left ambiguous.

Add a description per property; it is the strongest accuracy lever. unit controls cardinality: per_document (default), across_documents, rows_per_document.

Errors

Every /v1 failure is the same envelope, with x-request-id also on the response headers:

1{ "code": "invalid_request", "message": "file: provide exactly one of `file` or `files`",
2  "retryable": false, "requestId": "req_…", "docUrl": "https://docs.cloudraker.com/developers/errors#invalid_request" }

Branch on code, never on message. Common codes: unauthorized, invalid_token (401); invalid_request, invalid_schema, action_unknown, file_ineligible, run_too_large, schema_too_large (400); not_found (404); file_not_ready, output_not_ready, already_kept, pipeline_running (409); run_expired (410); file_fetch_failed, webhook_endpoint_not_found, webhook_endpoint_disabled (422); rate_limited (429); internal_error, file_unreadable, file_upload_failed (5xx). Retry only where retryable is true.

Rate limits

At least 67 requests per minute per organization, shared across every /v1 endpoint — a guaranteed floor enforced per edge location, so a distributed caller may sustain more. Over it: 429, code: "rate_limited", Retry-After: 60. Nothing is started and nothing is billed. Respect Retry-After, then back off exponentially with jitter. One batch call and one long-poll each cost a single request, which is why both beat looping.

Webhooks

Send webhook: {"url": "https://…"} on any verb, or register an endpoint with POST /v1/webhooks and reference it as webhook: {"id": …}. Deliveries are signed JWTs verified against GET /v1/webhooks/jwks.json (public, unauthenticated, never rate limited). Run metadata is not included in deliveries — re-fetch the run by id.

Rules that save you a debugging session

  • Nothing a /v1 run touches appears in the CloudRaker app until you POST /v1/runs/:id/keep. That is deliberate — ephemeral by default.
  • Schema inference (hints, no schema) picks its own field names and can differ between runs. Use it once to discover the shape, then pin config.schema or save it as an action.
  • hints with a schema or an action is a 400; use instructions instead.
  • POST /v1/extract/batch has a strict body — schema and hints are rejected, not ignored — and always returns 202. citations is accepted there.
  • Pipeline steps run in parallel over the same files. A step never consumes another step’s output.
  • A produced file is registered a moment after processed; until then output.file.url and /output/:name return 409 output_not_ready (retryable, never 404). Wait a moment and ask again.
  • Reuse fileIds instead of re-sending URLs: the document is neither re-fetched nor re-parsed.

Full reference

  • OpenAPI: https://docs.cloudraker.com/openapi.json — the full gateway spec, including POST /v1/extract/batch and GET /v1/runs. It is re-exported whenever the surface changes; where it and this page ever disagree, this page is right.
  • Markdown index for agents: https://docs.cloudraker.com/llms.txt
  • MCP server: https://mcp.cloudraker.com — see MCP server
  • Human-readable start: Agent quickstart, Quickstart