Submit a document for splitting

POST

split

curl --request POST \
  --url https://api.orion.file.ai/prod/v1/split \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-api-key: <api-key>' \
  --form file=@example-file \
  --form 'custom_instruction=<string>' \
  --form 'ranges=<string>' \
  --form 'callback_url=<string>' \
  --form 'client_ref=<string>'

import requests

url = "https://api.orion.file.ai/prod/v1/split"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = {
    "custom_instruction": "<string>",
    "ranges": "<string>",
    "callback_url": "<string>",
    "client_ref": "<string>"
}
headers = {"x-api-key": "<api-key>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('file', '<string>');
form.append('custom_instruction', '<string>');
form.append('ranges', '<string>');
form.append('callback_url', '<string>');
form.append('client_ref', '<string>');

const options = {method: 'POST', headers: {'x-api-key': '<api-key>'}};

options.body = form;

fetch('https://api.orion.file.ai/prod/v1/split', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "job_id": "job_01J9ZK3V6Q8W",
  "status": "queued",
  "created_at": "2023-11-07T05:31:56Z",
  "poll_url": "<string>"
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

Request · Response · Guide: Split & classify

More details

One endpoint covers all split modes; the mode is selected by the payload (not a separate endpoint):

no options -> normal split (the engine detects boundaries)
custom_instruction -> custom (guided) split
ranges -> deterministic split (explicit page ranges) Supplying both custom_instruction and ranges is a 422.

Always returns 202 Accepted with a job_id; results are retrieved via GET /v1/jobs/ (result.documents carries the per-split page ranges) or delivered to callback_url when the job settles.Supported input types: application/pdf, image/png, image/jpeg, image/tiff. Any other content type is rejected with 415.

Authorizations

x-api-key

string

header

required

API key for authentication

Body

multipart/form-data

file

required

The document. Must be application/pdf, image/png, image/jpeg, or image/tiff.

custom_instruction

string

Optional guided-split instruction, e.g. "group the invoice and packing list as one document". Selects custom (guided) split. Mutually exclusive with ranges.

ranges

string

Optional explicit page ranges as a JSON string of 1-indexed, inclusive [start, end] pairs, e.g. "[[1,3],[4,6]]". Selects deterministic split (no LLM judgment). Mutually exclusive with custom_instruction.

callback_url

string

Optional HTTPS URL to receive the extraction.job.settled webhook when the job settles. A blank value is treated as omitted.

client_ref

string

Opaque caller-supplied reference, echoed on the job and webhook payload.

Maximum string length: 256

Response

Job accepted and queued.

job_id

string

required

Example:

"job_01J9ZK3V6Q8W"

status

enum<string>

required

Available options:

queued

Example:

"queued"

created_at

string<date-time>

required

poll_url

string<uri-reference>

required

URL of GET /v1/jobs/{job_id}.

Submit a document for splitting

curl --request POST \
  --url https://api.orion.file.ai/prod/v1/split \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-api-key: <api-key>' \
  --form file=@example-file \
  --form 'custom_instruction=<string>' \
  --form 'ranges=<string>' \
  --form 'callback_url=<string>' \
  --form 'client_ref=<string>'

import requests

url = "https://api.orion.file.ai/prod/v1/split"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = {
    "custom_instruction": "<string>",
    "ranges": "<string>",
    "callback_url": "<string>",
    "client_ref": "<string>"
}
headers = {"x-api-key": "<api-key>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('file', '<string>');
form.append('custom_instruction', '<string>');
form.append('ranges', '<string>');
form.append('callback_url', '<string>');
form.append('client_ref', '<string>');

const options = {method: 'POST', headers: {'x-api-key': '<api-key>'}};

options.body = form;

fetch('https://api.orion.file.ai/prod/v1/split', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "job_id": "job_01J9ZK3V6Q8W",
  "status": "queued",
  "created_at": "2023-11-07T05:31:56Z",
  "poll_url": "<string>"
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

Get started

Endpoints

Submit a document for splitting

Authorizations

Body

Response