Flatten PDF Forms

Endpoint #

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

Action #

action=flatten

Description #

The Flatten PDF Forms action flattens PDF form content using the H2I engine (PixLab).

This action is part of the public /v1/pdf API surface. It accepts a source PDF and returns a generated PDF output through a signed URL under the public PDF output path. The public external example documents this action with a form-flatten toggle named flattenForms.

This action is suitable for workflows such as:

• finalizing PDF documents before distribution
• preparing PDFs for downstream handling
• producing non-interactive output versions of form-based PDFs

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=flatten.

Parameters #

action #

Type: string
Required: Yes
Accepted value: flatten

Specifies that the request should process the uploaded PDF using the flatten action.

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

flattenForms #

Type: boolean or string
Required: No
Default: true

Form flatten toggle for the flatten action. The public external cURL example documents this field explicitly.

Supported Parameters #

The Flatten PDF Forms action supports the following public parameters:

Parameter	Description
action	Must be flatten
files	Source PDF upload
flattenForms	Form flatten toggle

These are the documented public parameters for /v1/pdf action=flatten in the uploaded external example set.

Full cURL Example #

curl -sS -X POST "https://pixlab.davix.dev/v1/pdf" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: pdf-flatten-001" \
  -F "action=flatten" \
  -F "files=@/path/to/document.pdf" \
  -F "flattenForms=true"

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

• action=flatten
• source PDF upload in files
• flattenForms
• optional idempotency header

Success Response #

Successful /v1/pdf requests return either a single output object or a results array, depending on the action. For public documentation, action=flatten is safest documented as a single generated PDF output returned through a signed URL. PDF output URLs are served under /pdf/<file>.

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

Response Fields #

url #

Signed output URL for the generated flattened PDF. 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 other request-size-related PDF limits
• 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 #

Idempotency-Key is optional and supported for retry-safe request handling. Both Idempotency-Key and X-Idempotency-Key are accepted.

This action accepts a source PDF and returns a generated PDF output.

flattenForms is the public toggle documented for the flatten action and defaults to true.

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.