Split

Segment a multi-document PDF into individual logical documents. Returns page ranges for each detected document.

Cost$0.03/page

Latency~0.5s

HyperLM

Step 1: Upload your document — call POST /v1/documents/upload to get a document_key

Request

Headers

Name	Type	Required	Allowed values	Description
`X-API-Key`	`string`	required	—	Your HyperAPI key (hk_live_* or hk_test_*).
`X-Async`	`string`	optional	`truefalse`	Set to "true" to process asynchronously and receive a job ID.

Body

Name	Type	Required	Description
`document_key`	`string`	required	S3 document key obtained from the presigned upload endpoint (/v1/documents/upload).
`options`	`string`	optional	Optional JSON object of splitter tuning knobs, sent as a single JSON-encoded string. Invalid JSON or a non-object value returns HTTP 400. Accepted keys: `use_thinking` (bool, default `true`) enables extended step-by-step reasoning for higher segmentation accuracy at higher latency; `segment_classes` (object mapping `<class_label>` → `{description: string, standalone: bool}` — the primary segmentation knob; `standalone: true` means a page of that class always begins a new segment); `extend_segment_classes` (bool, optional) merges your `segment_classes` with the built-in defaults instead of replacing them (auto-disabled when `custom_domain_guidelines` is set); `custom_domain_guidelines` (object) provides domain-specific segmentation guidance — `domain_name` (string, required) plus optional `identifier_patterns`, `binding_patterns`, `heuristics`, and `examples` (strings; omitted fields are excluded from the prompt).

Query Parameters

Name	Type	Default	Allowed values	Description
`mode`	`string`	`default`	—	Router-level task-routing selector (picks the `split:<mode>` binding). The split service exposes no depth modes of its own, so leave this at `default`; all split tuning is done through the `options` request-body field.

Code examples

# Get a document_key first: see POST /v1/documents/upload
curl -X POST "https://apis.hyperbots.com/v1/split?mode=default" \
  -H "X-API-Key: hk_live_your_key_here" \
  -F "document_key=550e8400-e29b-41d4-a716-446655440000"

# Get a document_key first: see POST /v1/documents/upload
curl -X POST "https://apis.hyperbots.com/v1/split?mode=default" \
  -H "X-API-Key: hk_live_your_key_here" \
  -F "document_key=550e8400-e29b-41d4-a716-446655440000"

Response

200 OK

application/json

JSON

{
  "status": "success",
  "request_id": "req_01j9z...",
  "task": "split",
  "model_used": "HyperLM",
  "result": {
    "segments": [
      { "document_index": 0, "start_page": 1, "end_page": 3, "type": "invoice" },
      { "document_index": 1, "start_page": 4, "end_page": 5, "type": "receipt" }
    ]
  },
  "duration_ms": 490,
  "metadata": { "pages": 5 }
}

{
  "status": "success",
  "request_id": "req_01j9z...",
  "task": "split",
  "model_used": "HyperLM",
  "result": {
    "segments": [
      { "document_index": 0, "start_page": 1, "end_page": 3, "type": "invoice" },
      { "document_index": 1, "start_page": 4, "end_page": 5, "type": "receipt" }
    ]
  },
  "duration_ms": 490,
  "metadata": { "pages": 5 }
}