Encrypt PDF

Endpoint #

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

Action #

action=encrypt

Description #

The Encrypt PDF action protects a PDF document with password-based encryption using the H2I engine (PixLab).

This action is part of the public /v1/pdf API surface. It accepts a source PDF and returns an encrypted PDF output through a signed URL under the public PDF output path. The public documentation for this action defines userPassword as required and ownerPassword as optional, with the owner password defaulting to the user password.

This action is suitable for workflows such as:

• securing confidential documents
• protecting generated reports
• restricting access to shared files
• safeguarding archived documents

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

Parameters #

action #

Type: string
Required: Yes
Accepted value: encrypt

Specifies that the request should encrypt the uploaded PDF document.

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

userPassword #

Type: string
Required: Yes

Defines the user password for the encrypted PDF.

• required for action=encrypt
• must be provided as a non-empty form field

ownerPassword #

Type: string
Required: No

Defines the owner password for the encrypted PDF.

• optional
• defaults to the same value as userPassword when omitted

Supported Parameters #

The Encrypt PDF action supports the following public parameters:

Parameter	Description
action	Must be encrypt
files	Source PDF upload
userPassword	Required user password
ownerPassword	Optional owner password

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

Full cURL Example #

curl -sS -X POST "https://pixlab.davix.dev/v1/pdf" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: pdf-encrypt-001" \
  -F "action=encrypt" \
  -F "files=@/path/to/document.pdf" \
  -F "userPassword=example-user-password" \
  -F "ownerPassword=example-owner-password"

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

• action=encrypt
• source PDF upload in files
• required userPassword
• optional ownerPassword
• 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=encrypt 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/encrypted-document.pdf",
  "request_id": "req_abc123"
}

Response Fields #

url #

Signed output URL for the generated encrypted 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

A missing qpdf dependency causes PDF encrypt/decrypt requests to fail with invalid_parameter and a qpdf not installed dependency error. That behavior is documented in the dependency notes, but it is better treated as an operational dependency note than a primary customer-facing API error code.

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.

userPassword is required for PDF encryption.

ownerPassword is optional and defaults to the same value as userPassword when omitted.

This action depends on qpdf in the service runtime.

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.