Label documents, or find where each one starts

{
  "object": "string",
  "id": "string",
  "status": "queued",
  "expiresAt": "string",
  "statusUrl": "string",
  "files": [
    {
      "id": "string",
      "name": "string",
      "status": "string",
      "error": "string"
    }
  ],
  "file": {
    "id": "string",
    "name": "string",
    "status": "string",
    "error": "string"
  },
  "error": {
    "code": "string",
    "message": "string"
  },
  "metadata": {},
  "config": {
    "classes": [
      {
        "id": "invoice",
        "description": "A bill from a supplier listing line items, quantities and a total amount due."
      }
    ],
    "granularity": "document",
    "rules": {
      "minPages": 1.1
    }
  },
  "usage": {
    "pages": 1.1,
    "parse": 1.1,
    "split": 1.1
  },
  "output": {
    "granularity": "document",
    "classId": "string",
    "confidence": 1.1,
    "reasoning": "string",
    "documents": [
      {
        "fileId": "string",
        "status": "string",
        "error": "string",
        "classId": "string",
        "confidence": 1.1,
        "reasoning": "string"
      }
    ],
    "pages": [
      {
        "page": 1.1,
        "classId": "string",
        "documentStart": true,
        "confidence": 1.1,
        "reasoning": "string"
      }
    ],
    "segments": [
      {
        "startPage": 1.1,
        "endPage": 1.1,
        "classId": "string",
        "confidence": 1.1
      }
    ],
    "unassignedPages": [
      1.1
    ]
  }
}

Classify decides what a file is. Split cuts it — they are two calls, and this is the only one that runs a model.

Send classes: at least two, each an {id, description}. The description is the accuracy lever — there is no training data — and the id is your branch key, returned untouched. One class is the catch-all; supply {"id": "other", …} or one is injected and echoed back in config.

Two granularities:

`granularity`	Answer	Billed
`document` (default)	one label for the whole file	the first and last window only
`page`	one label per page, plus derived `segments[]`	every page

Page mode is what feeds split: the model marks the first page of each document, and contiguous, non-overlapping segments[] are derived from that in code — so two invoices back to back come back as two segments, not one. Pass the run id to POST /v1/split as classifyRunId.

confidence is 0–5. A low score never rewrites the label: threshold it yourself, and re-run with a sharper description when the model is unsure.

1 {
2   "file": { "url": "https://acme.example/scans/mail.pdf" },
3   "classes": [
4     { "id": "invoice", "description": "A bill from a supplier with line items and a total due." },
5     { "id": "contract", "description": "A signed agreement with clauses and signature blocks." }
6   ],
7   "granularity": "page"
8 }

Waiting for the result

Sync by default: the call holds open until the run finishes, up to ?wait= seconds (default 60, max 120, 0 returns immediately).

Outcome	Response
Finished inside the window	`200` with the full run
Still running at the cap	`202` with `{object, id, status, statusUrl}`

The 202 is a graceful degrade, never an error — poll the run or wait for a webhook. Replaying an idempotency-key returns the original run alongside an idempotent-replay: true response header.

Learn more: Classification guide

Classify decides what a file is. [Split](https://docs.cloudraker.com/capabilities/split) cuts it — they are two calls, and this is the only one that runs a model. Send `classes`: at least two, each an `{id, description}`. The description is the accuracy lever — there is no training data — and the `id` is your branch key, returned untouched. One class is the catch-all; supply `{"id": "other", …}` or one is injected and echoed back in `config`. **Two granularities:** | `granularity` | Answer | Billed | | --- | --- | --- | | `document` (default) | one label for the whole file | the first and last window only | | `page` | one label per page, plus derived `segments[]` | every page | Page mode is what feeds split: the model marks the first page of each document, and contiguous, non-overlapping `segments[]` are derived from that in code — so two invoices back to back come back as two segments, not one. Pass the run id to [POST /v1/split](https://docs.cloudraker.com/capabilities/split) as `classifyRunId`. `confidence` is 0–5. A low score never rewrites the label: threshold it yourself, and re-run with a sharper `description` when the model is unsure. ```json { "file": { "url": "https://acme.example/scans/mail.pdf" }, "classes": [ { "id": "invoice", "description": "A bill from a supplier with line items and a total due." }, { "id": "contract", "description": "A signed agreement with clauses and signature blocks." } ], "granularity": "page" } ``` ### Waiting for the result Sync by default: the call holds open until the run finishes, up to `?wait=` seconds (default `60`, max `120`, `0` returns immediately). | Outcome | Response | | --- | --- | | Finished inside the window | `200` with the full run | | Still running at the cap | `202` with `{object, id, status, statusUrl}` | <Note> The `202` is a graceful degrade, never an error — poll [the run](https://docs.cloudraker.com/api/cloud-raker-api/runs/get-run) or wait for a [webhook](https://docs.cloudraker.com/api/cloud-raker-api/webhooks/create-webhook-endpoint). Replaying an `idempotency-key` returns the original run alongside an `idempotent-replay: true` response header. </Note> **Learn more:** [Classification guide](https://docs.cloudraker.com/capabilities/classify)

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

spaceIdstringRequired

Query parameters

waitintegerOptional0-120Defaults to 60

How many seconds to hold the request open waiting for the run to finish.

Finishing inside the window returns 200 with the full run; running past it returns 202 with a statusUrl to poll. Send 0 to skip waiting entirely and always get the 202.

Request

This endpoint expects an object.

classeslist of objectsOptional

The classes to choose from, at least 2 and at most 50. Required unless you name a saved action that carries them.

One class is the catch-all. Supply one with id: "other", or one is injected for you and echoed back on the run — a closed set with no exit makes the model guess.

granularityenumOptional

What one label covers. document (the default) answers once for the whole file and bills only the pages sent to the model; page answers per page, derives segments[] from where documents start, and bills every page.

rulesobjectOptional

Page mode only. A segment shorter than minPages (default 1) merges into its neighbour.

instructionsstringOptional<=4000 characters

Free-form guidance applied on top of the class descriptions — how to treat continuation sheets, which class wins a tie.

pageRangeobjectOptional

The pages to consider, 1-based inclusive. Defaults to the first 750 pages, which is also the maximum — a wider range is a page_limit_exceeded error, never a silent truncation.

actionstringOptional>=1 character

A saved classify config to run, by id or slug. Config you send inline is merged over it.

fileobjectOptional

An input file, given one of two ways.

{ "url": "…", "name"?: "…", "processing"?: "…" } — fetched over http(s) for this run and purged with it.
{ "id": "…" } — a file you already registered with POST /v1/files, reusable across runs and never re-parsed.

fileslist of objectsOptional

metadatamap from strings to anyOptional

Arbitrary JSON you attach to the run and get back on every read of it.

Use it to carry your own identifiers — an order number, a customer id — so a webhook or a polled run reconciles without a lookup table. Capped at 10 KB serialized.

webhookobjectOptional

Where to deliver this run’s events, given one of two ways.

{ "url": "…" } — a one-off https endpoint for this run only.
{ "id": "whe_…" } — a saved endpoint from POST /v1/webhooks. Runs hold the reference, so pausing or re-pointing that endpoint applies to this run too.

Deliveries are at-least-once and signed — dedupe on eventId and verify against GET /v1/webhooks/jwks.json.

ttlintegerOptional1-604800Defaults to 86400

How long, in seconds, to keep this run and its files before purging them automatically.

The maximum is 604800 (7 days). The deadline comes back as expiresAt on every read of the run. Call POST /v1/runs/{id}/keep before then to clear the TTL and move the results into a space permanently.

E-signature runs are exempt — an envelope waits for its signers however long that takes.

Response

The finished run.

object"classify_run"

idstring

statusenum

Where the run is in its life.

Status	Meaning
`queued`	Accepted, not started
`processing`	Work in flight
`needs_input`	Waiting for an external action, such as an e-signature
`processed`	Finished; `output` is populated
`failed`	Finished unsuccessfully
`cancelled`	Stopped on request
`expired`	TTL elapsed and the data was purged

The last four are terminal.

expiresAtstring or null

statusUrlstring

fileslist of objects

fileobjectOptional

errorobjectOptional

Why the run failed. Present whenever status is failed, and only then.

code is the stable, snake_case reason (input_unavailable, parse_failed, …); message is the human-readable detail. Per-file and per-step failures are also reported in files[].error and, for a pipeline, steps[].error.

metadatamap from strings to anyOptional

configobjectOptional

usageobjectOptional

outputobjectOptional

The labels. Present once status is processed.

In document mode classId, confidence and reasoning are the first document’s, and documents[] is authoritative for a multi-file run. In page mode pages[] is the raw per-page answer and segments[] is what POST /v1/split consumes.

Errors

400

Bad Request Error

422

Unprocessable Entity Error

429

Too Many Requests Error

Classify decides what a file is. Split cuts it — they are two calls, and this is the only one that runs a model.

Two granularities:

`granularity`	Answer	Billed
`document` (default)	one label for the whole file	the first and last window only
`page`	one label per page, plus derived `segments[]`	every page

confidence is 0–5. A low score never rewrites the label: threshold it yourself, and re-run with a sharper description when the model is unsure.

1 {
2   "file": { "url": "https://acme.example/scans/mail.pdf" },
3   "classes": [
4     { "id": "invoice", "description": "A bill from a supplier with line items and a total due." },
5     { "id": "contract", "description": "A signed agreement with clauses and signature blocks." }
6   ],
7   "granularity": "page"
8 }

Waiting for the result

Sync by default: the call holds open until the run finishes, up to ?wait= seconds (default 60, max 120, 0 returns immediately).

Outcome	Response
Finished inside the window	`200` with the full run
Still running at the cap	`202` with `{object, id, status, statusUrl}`

The 202 is a graceful degrade, never an error — poll the run or wait for a webhook. Replaying an idempotency-key returns the original run alongside an idempotent-replay: true response header.

Learn more: Classification guide

$	curl -X POST https://api.cloudraker.com/v1/spaces/spaceId/classify \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{}'

1	{
2	"file": { "url": "https://acme.example/scans/mail.pdf" },
3	"classes": [
4	{ "id": "invoice", "description": "A bill from a supplier with line items and a total due." },
5	{ "id": "contract", "description": "A signed agreement with clauses and signature blocks." }
6	],
7	"granularity": "page"
8	}