Document Split

Split rule suggestion and split runs are queued operations (202, poll GET /v1/operations/{operationId}); split PDF download stays synchronous.

Suggest split rules

POST

https://api.providus.ai

/v1/split/rules/suggest

Requires a parsed file and debits exactly 1 credit before enqueueing. Queued, not synchronous: responds 202 with { operation_id, status } and the suggestion runs asynchronously — poll GET /v1/operations/{operationId} for progress and output (output.rules). A request that re-attaches to an already-completed operation (same idempotency key) returns 200 with the rules inline instead. Retrying a failed/cancelled attempt starts a fresh attempt and re-charges; the ledger records each attempt under its own :attempt-N idempotency key.

Suggest split rules › Request Body

SplitRulesSuggestRequest

file_id

string · uuid · required

model_id

string

reasoning_level

string · enum

Enum values:

none

low

medium

high

Default: medium

idempotency_key

string

Suggest split rules › Responses

Split rules (idempotent replay of an already-completed run)

Queued document workflow. Poll GET /v1/operations/{operationId} until status is completed or failed; output is null until then.

Operation

operation_id

string

operation_type

string · enum

Enum values:

split_run

extract_run

classify_run

edit_run

split_rules_suggest

schema_generate

status

string · enum

Enum values:

queued

in_progress

completed

failed

cancelled

object

Populated only once status is completed.

error

string

created_at

string · date-time

completed_at

string · date-time

POST/v1/split/rules/suggest

curl https://api.providus.ai/v1/split/rules/suggest \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'x-docai-org-id: <api-key>' \
  --data '{
  "model_id": "lmstudio/qwen3-vl-32b-instruct-mlx",
  "reasoning_level": "medium",
  "idempotency_key": "idempotency_key",
  "file_id": "00000000-0000-0000-0000-000000000000"
}'

Example Request Body

{
  "model_id": "lmstudio/qwen3-vl-32b-instruct-mlx",
  "reasoning_level": "medium",
  "idempotency_key": "idempotency_key",
  "file_id": "00000000-0000-0000-0000-000000000000"
}

json

Example Responses

{
  "operation_id": "op_7f3a9c21",
  "operation_type": "split_run",
  "status": "completed",
  "progress": {
    "done": 4,
    "total": 4,
    "phase": "writing"
  },
  "output": {
    "documents": 4
  },
  "error": null,
  "created_at": "2026-08-19T10:02:11.000Z",
  "completed_at": "2026-08-19T10:04:37.000Z"
}

json

application/json

Enqueue a document split run

POST

https://api.providus.ai

/v1/split/runs

Requires a parsed file and debits exactly 1 credit before enqueueing. Queued, not synchronous: responds 202 with { operation_id, status } and the split runs asynchronously — poll GET /v1/operations/{operationId} for progress and output. A request that re-attaches to an already-completed operation (same idempotency key) returns 200 with the split session inline instead. Retrying a failed/cancelled attempt starts a fresh attempt and re-charges (the failed attempt's credit was already refunded); the ledger records each attempt under its own :attempt-N idempotency key.

Enqueue a document split run › Request Body

SplitRunRequest

file_id

string · uuid · required

object[] · required

model_id

string

reasoning_level

string · enum

Enum values:

none

low

medium

high

Default: medium

idempotency_key

string

Enqueue a document split run › Responses

Split session (idempotent replay of an already-completed run)

Queued document workflow. Poll GET /v1/operations/{operationId} until status is completed or failed; output is null until then.

Operation

operation_id

string

operation_type

string · enum

Enum values:

split_run

extract_run

classify_run

edit_run

split_rules_suggest

schema_generate

status

string · enum

Enum values:

queued

in_progress

completed

failed

cancelled

object

Populated only once status is completed.

error

string

created_at

string · date-time

completed_at

string · date-time

POST/v1/split/runs

curl https://api.providus.ai/v1/split/runs \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'x-docai-org-id: <api-key>' \
  --data '{
  "model_id": "lmstudio/qwen3-vl-32b-instruct-mlx",
  "reasoning_level": "medium",
  "idempotency_key": "idempotency_key",
  "file_id": "00000000-0000-0000-0000-000000000000",
  "rules": [
    {}
  ]
}'

Example Request Body

{
  "model_id": "lmstudio/qwen3-vl-32b-instruct-mlx",
  "reasoning_level": "medium",
  "idempotency_key": "idempotency_key",
  "file_id": "00000000-0000-0000-0000-000000000000",
  "rules": [
    {}
  ]
}

json

Example Responses

{
  "operation_id": "op_7f3a9c21",
  "operation_type": "split_run",
  "status": "completed",
  "progress": {
    "done": 4,
    "total": 4,
    "phase": "writing"
  },
  "output": {
    "documents": 4
  },
  "error": null,
  "created_at": "2026-08-19T10:02:11.000Z",
  "completed_at": "2026-08-19T10:04:37.000Z"
}

json

application/json

Download split PDF page range

POST

https://api.providus.ai

/v1/split/download

Returns a PDF page range from the source file. This endpoint does not debit credits.

Download split PDF page range › Request Body

SplitDownloadRequest

file_id

string · uuid · required

startPage

integer · min: 1 · required

endPage

integer · min: 1 · required

title

string · required

Download split PDF page range › Responses

PDF bytes

string · binary

Operations Document Classification

DocAI Control Plane API

Document Split

Split rule suggestion and split runs are queued operations (202, poll GET /v1/operations/{operationId}); split PDF download stays synchronous.

Suggest split rules

POST

https://api.providus.ai

/v1/split/rules/suggest

Suggest split rules › Request Body

SplitRulesSuggestRequest

file_id

string · uuid · required

model_id

string

reasoning_level

string · enum

Enum values:

none

low

medium

high

Default: medium

idempotency_key

string

Suggest split rules › Responses

Split rules (idempotent replay of an already-completed run)

Queued document workflow. Poll GET /v1/operations/{operationId} until status is completed or failed; output is null until then.

Operation

operation_id

string

operation_type

string · enum

Enum values:

split_run

extract_run

classify_run

edit_run

split_rules_suggest

schema_generate

status

string · enum

Enum values:

queued

in_progress

completed

failed

cancelled

object

Populated only once status is completed.

error

string

created_at

string · date-time

completed_at

string · date-time

POST/v1/split/rules/suggest

curl https://api.providus.ai/v1/split/rules/suggest \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'x-docai-org-id: <api-key>' \
  --data '{
  "model_id": "lmstudio/qwen3-vl-32b-instruct-mlx",
  "reasoning_level": "medium",
  "idempotency_key": "idempotency_key",
  "file_id": "00000000-0000-0000-0000-000000000000"
}'

Example Request Body

{
  "model_id": "lmstudio/qwen3-vl-32b-instruct-mlx",
  "reasoning_level": "medium",
  "idempotency_key": "idempotency_key",
  "file_id": "00000000-0000-0000-0000-000000000000"
}

json

Example Responses

{
  "operation_id": "op_7f3a9c21",
  "operation_type": "split_run",
  "status": "completed",
  "progress": {
    "done": 4,
    "total": 4,
    "phase": "writing"
  },
  "output": {
    "documents": 4
  },
  "error": null,
  "created_at": "2026-08-19T10:02:11.000Z",
  "completed_at": "2026-08-19T10:04:37.000Z"
}

json

application/json

Enqueue a document split run

POST

https://api.providus.ai

/v1/split/runs

Enqueue a document split run › Request Body

SplitRunRequest

file_id

string · uuid · required

object[] · required

model_id

string

reasoning_level

string · enum

Enum values:

none

low

medium

high

Default: medium

idempotency_key

string

Enqueue a document split run › Responses

Split session (idempotent replay of an already-completed run)

Queued document workflow. Poll GET /v1/operations/{operationId} until status is completed or failed; output is null until then.

Operation

operation_id

string

operation_type

string · enum

Enum values:

split_run

extract_run

classify_run

edit_run

split_rules_suggest

schema_generate

status

string · enum

Enum values:

queued

in_progress

completed

failed

cancelled

object

Populated only once status is completed.

error

string

created_at

string · date-time

completed_at

string · date-time

POST/v1/split/runs

curl https://api.providus.ai/v1/split/runs \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'x-docai-org-id: <api-key>' \
  --data '{
  "model_id": "lmstudio/qwen3-vl-32b-instruct-mlx",
  "reasoning_level": "medium",
  "idempotency_key": "idempotency_key",
  "file_id": "00000000-0000-0000-0000-000000000000",
  "rules": [
    {}
  ]
}'

Example Request Body

{
  "model_id": "lmstudio/qwen3-vl-32b-instruct-mlx",
  "reasoning_level": "medium",
  "idempotency_key": "idempotency_key",
  "file_id": "00000000-0000-0000-0000-000000000000",
  "rules": [
    {}
  ]
}

json

Example Responses

{
  "operation_id": "op_7f3a9c21",
  "operation_type": "split_run",
  "status": "completed",
  "progress": {
    "done": 4,
    "total": 4,
    "phase": "writing"
  },
  "output": {
    "documents": 4
  },
  "error": null,
  "created_at": "2026-08-19T10:02:11.000Z",
  "completed_at": "2026-08-19T10:04:37.000Z"
}

json

application/json

Download split PDF page range

POST

https://api.providus.ai

/v1/split/download

Returns a PDF page range from the source file. This endpoint does not debit credits.

Download split PDF page range › Request Body

SplitDownloadRequest

file_id

string · uuid · required

startPage

integer · min: 1 · required

endPage

integer · min: 1 · required

title

string · required

Download split PDF page range › Responses

PDF bytes

string · binary

Operations Document Classification