Cut a PDF into child files by page range | CloudRaker documentation

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

{
  "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": {},
  "usage": {
    "pages": 1.1,
    "parse": 1.1,
    "split": 1.1
  },
  "output": {
    "files": [
      {
        "id": "string",
        "name": "string",
        "url": "string"
      }
    ],
    "file": {
      "id": "string",
      "name": "string",
      "url": "string"
    },
    "classifyRunId": "string",
    "splits": [
      {
        "index": 1.1,
        "startPage": 1.1,
        "endPage": 1.1,
        "pageCount": 1.1,
        "classId": "string",
        "confidence": 1.1,
        "fileId": "string",
        "fileName": "string"
      }
    ],
    "documentIds": [
      "string"
    ]
  }
}

Classify decides. Split cuts — it runs no model, has no classes and no configuration.

PDF only. Office, image, audio and video inputs fail the run with unsupported_split_source.

Send exactly one of:

segments — your own ranges, 1-based inclusive, ascending, non-overlapping, at most 100. Gaps are allowed. This path costs no model call at all.
classifyRunId — a page-mode classify run on the same file. Its segments[] are used as-is, with classId and confidence echoed onto each child.

Each child is a real file with its own fileId, ready for POST /v1/extract; output.documentIds is the same list flattened. Children inherit the parent’s metadata, gain metadata.parentRunId, land in the parent’s space and share the run’s TTL — call keep to move parent and children together.

Send materialize: false to get the ranges back without creating anything: the safe first call on a large packet.

1 {
2   "file": { "id": "file_01K3F…" },
3   "classifyRunId": "clr_01K3F…"
4 }

Children are parsed right after the split, so they are immediately usable by any verb. Each child’s parse is billed as a normal parse. usage itemizes it.

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: Split guide

[Classify](https://docs.cloudraker.com/capabilities/classify) decides. Split cuts — it runs no model, has no classes and no configuration. **PDF only.** Office, image, audio and video inputs fail the run with `unsupported_split_source`. Send exactly one of: - `segments` — your own ranges, 1-based inclusive, ascending, non-overlapping, at most 100. Gaps are allowed. This path costs no model call at all. - `classifyRunId` — a page-mode classify run on the same file. Its `segments[]` are used as-is, with `classId` and `confidence` echoed onto each child. Each child is a real file with its own `fileId`, ready for [POST /v1/extract](https://docs.cloudraker.com/api/cloud-raker-api/capabilities/extract); `output.documentIds` is the same list flattened. Children inherit the parent's `metadata`, gain `metadata.parentRunId`, land in the parent's space and share the run's TTL — call [keep](https://docs.cloudraker.com/api/cloud-raker-api/runs/keep-run) to move parent and children together. Send `materialize: false` to get the ranges back without creating anything: the safe first call on a large packet. ```json { "file": { "id": "file_01K3F…" }, "classifyRunId": "clr_01K3F…" } ``` <Note> Children are parsed right after the split, so they are immediately usable by any verb. Each child's parse is billed as a normal parse. `usage` itemizes it. </Note> ### 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:** [Split guide](https://docs.cloudraker.com/capabilities/split)

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.

fileobjectRequired

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.

segmentslist of objectsOptional

The ranges to cut, 1-based inclusive, ascending and non-overlapping, at most 100. Gaps are allowed — drop a separator page on purpose. Send this or classifyRunId, never both.

classifyRunIdstringOptional>=1 character

A page-mode classify run to take the ranges from. Its output.segments are copied verbatim, classId and confidence included. The run must be on the same file and must not have expired.

materializebooleanOptionalDefaults to true

Whether to create the child files. false returns the ranges only and creates nothing — the safe first call on a large packet.

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"split_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

usageobjectOptional

outputobjectOptional

The children. Present once status is processed.

splits[].fileId is the authoritative id of each child, ready for POST /v1/extract; documentIds[] is the same list flattened. classId and confidence are echoed from whatever you supplied — split has no opinion about what a page is. With materialize: false the ranges come back with no fileId.

Errors

400

Bad Request Error

422

Unprocessable Entity Error

429

Too Many Requests Error

Classify decides. Split cuts — it runs no model, has no classes and no configuration.

PDF only. Office, image, audio and video inputs fail the run with unsupported_split_source.

Send exactly one of:

segments — your own ranges, 1-based inclusive, ascending, non-overlapping, at most 100. Gaps are allowed. This path costs no model call at all.
classifyRunId — a page-mode classify run on the same file. Its segments[] are used as-is, with classId and confidence echoed onto each child.

Send materialize: false to get the ranges back without creating anything: the safe first call on a large packet.

1 {
2   "file": { "id": "file_01K3F…" },
3   "classifyRunId": "clr_01K3F…"
4 }

Children are parsed right after the split, so they are immediately usable by any verb. Each child’s parse is billed as a normal parse. usage itemizes it.

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: Split guide

1	{
2	"file": { "id": "file_01K3F…" },
3	"classifyRunId": "clr_01K3F…"
4	}