Merge PDF

Endpoint #

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

Action #

action=merge

Description #

The Merge PDF action combines multiple PDF files into a single PDF document using the H2I engine (PixLab).

Applications send one or more PDF files in a single multipart/form-data request. By default, files are merged in the order they are uploaded. When sortByName=true is provided, files are sorted alphabetically by filename before merging. This action is part of the public /v1/pdf API surface and uses the PDF processing flow that writes outputs under the public PDF output path.

This action is suitable for workflows such as:

• combining reports
• merging invoices
• assembling multiple PDF documents into one output file

Request Format #

Requests to /v1/pdf use:

• Content-Type: multipart/form-data
• API key authentication in headers
• one or more PDF uploads in the files field

The public API accepts:

• X-Api-Key: <YOUR_API_KEY>
• Authorization: Bearer <YOUR_API_KEY>

Parameters #

action #

Type: string
Required: Yes
Accepted value: merge

Selects the PDF merge operation.

files #

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

One or more PDF files to merge.

• uploaded through the files field
• must be PDF files
• used for merge and other multi-file PDF operations

sortByName #

Type: boolean-like
Required: No
Default: false

Controls file ordering before merge.

• false → files are merged in upload order
• true → files are sorted alphabetically by filename before merging

Supported Parameters #

The Merge PDF action supports the following parameters:

Parameter	Description
action	Must be merge
files	One or more uploaded PDF files
sortByName	Optional alphabetical sorting before merge

No other action-specific PDF parameters are required for action=merge. Other /v1/pdf parameters belong to other PDF actions such as rotate, watermark, extract, split, or to-images.

Full cURL Example #

curl -sS -X POST "https://pixlab.davix.dev/v1/pdf" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: pdf-merge-001" \
  -F "action=merge" \
  -F "files=@/path/to/file-01.pdf" \
  -F "files=@/path/to/file-02.pdf" \
  -F "files=@/path/to/file-03.pdf" \
  -F "sortByName=false"

This example includes the full supported parameter surface for the Merge PDF action:

• action=merge
• one or more files uploads
• optional sortByName
• optional idempotency header

The external docs also support both Idempotency-Key and X-Idempotency-Key header names.

Success Response #

Successful /v1/pdf requests return either a single output object or a results array, depending on the action. The public external PDF reference documents these success output patterns:

• single output: { url, ...metadata }
• multi output: { results: [{ url, ... }] }

PDF output URLs are returned under the /pdf/<file> output path.

Use this conservative public example:

{
  "url": "https://pixlab.davix.dev/pdf/merged-file.pdf",
  "request_id": "req_abc123"
}

Response Fields #

url #

Signed output URL for the generated merged PDF. PDF outputs are returned under the public /pdf/<file> output path.

request_id #

Request identifier returned by the API when available.

Errors #

The public /v1/pdf reference documents the following error set for PDF actions:

• 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 system 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 PDF 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 #

• Multiple PDF files can be uploaded in a single merge request.
• By default, merge order follows upload order. sortByName=true changes the order to alphabetical by filename.
• Output is returned as a signed URL under the public PDF output path.
• The API supports idempotency headers for retry-safe request handling.
• API keys for /v1/* routes must be sent in request headers.