Split PDF

Endpoint #

POST https://pixlab.davix.dev/v1/pdf

Action #

action=split

Description #

The Split PDF action divides a PDF document into multiple separate PDF files using the H2I engine (PixLab).

This action is part of the public /v1/pdf API surface. It accepts a source PDF and splits it into multiple generated PDF outputs based on the requested page ranges. The generated files are returned through signed URLs under the public PDF output path.

This action is suitable for workflows such as:

• separating sections of long reports
• creating per-section documents
• preparing files for automated workflows
• splitting bundled PDFs into smaller deliverables

Request Format #

Requests to /v1/pdf must use:

• Content-Type: multipart/form-data
• API key authentication in request headers
• source PDF upload through the files field

For non-merge PDF actions, the first uploaded PDF file is used as the primary input. This applies to action=split.

Parameters #

action #

Type: string
Required: Yes
Accepted value: split

Specifies that the request should split the uploaded PDF document into multiple output files.

files #

Type: file upload (multipart/form-data)
Required: Yes

The source PDF document.

• uploaded through the files field
• must be a valid PDF upload
• for this action, the first uploaded PDF file is used as the source input

ranges #

Type: string
Required: Yes

Defines the page ranges used to create separate output files.

Accepted format:

• CSV ranges like 1-3,4-5

Constraints:

• parsed as range pairs only
• each range creates one output document

Examples:

• 1-3,4-6
• 1-2,3-5,6-8

prefix #

Type: string
Required: No
Default: split_

Defines the filename prefix used for generated split files.

Supported Parameters #

The Split PDF action supports the following public parameters:

Parameter	Description
action	Must be split
files	Source PDF upload
ranges	CSV ranges used to create separate output files
prefix	Optional filename prefix for generated files

These are the documented public parameters for /v1/pdf action=split.

Full cURL Example #

curl -sS -X POST "https://pixlab.davix.dev/v1/pdf" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: pdf-split-001" \
  -F "action=split" \
  -F "files=@/path/to/document.pdf" \
  -F "ranges=1-3,4-6" \
  -F "prefix=section_"

This example includes the full documented public parameter surface for the Split PDF action:

• action=split
• source PDF upload in files
• required ranges
• optional prefix
• optional idempotency header

Success Response #

Successful /v1/pdf requests return either a single output object or a results array, depending on the action. For action=split, the public success pattern is a multi-output response because each requested range produces a separate generated PDF file. PDF output URLs are signed under /pdf/<file>.

Use this public-safe example:

{
  "results": [
    {
      "url": "https://pixlab.davix.dev/pdf/section_1.pdf"
    },
    {
      "url": "https://pixlab.davix.dev/pdf/section_2.pdf"
    }
  ],
  "request_id": "req_abc123"
}

Response Fields #

results[] #

Array of generated PDF outputs. Each result represents one split output file.

url #

Signed output URL for a generated split PDF file. PDF outputs are served under the public /pdf/<file> path.

request_id #

Request identifier returned by the API when available.

Errors #

The public /v1/pdf endpoint documents the following PDF-route errors:

• missing_field
• invalid_parameter
• unsupported_media_type
• pdf_page_limit_exceeded
• rate_limit_exceeded
• rate_limit_store_unavailable
• monthly_quota_exceeded
• server_busy
• timeout
• pdf_tool_failed

The shared upload/error layer can also return:

• invalid_upload
• file_too_large
• too_many_files
• total_upload_exceeded

HTTP Status Codes #

• 400 → invalid request fields or parameters
• 413 → upload size/count limits exceeded or split page limit exceeded
• 415 → unsupported media type
• 429 → rate limit or monthly quota exceeded
• 503 → timeout, rate-limit store unavailable, or server busy
• 500 → PDF processing failure

Usage Notes #

• Each requested range produces a separate PDF output file.
• ranges must be provided as CSV ranges and is parsed as range pairs only.
• prefix can be used to influence generated output naming.
• Split has a documented page cap and may return pdf_page_limit_exceeded when exceeded.
• Output files are returned through signed URLs. Applications that need long-term storage should store generated files externally rather than treating output URLs as permanent hosting.
• Idempotency-Key is optional and supported for retry-safe request handling. Both Idempotency-Key and X-Idempotency-Key are accepted.