How to Flatten PDF Layers with cURL, Tutorial

Share this page

By the end of this tutorial, you'll understand how to flatten PDF layers with cURL and the Flatten Layers API Tool. We'll explain the important request pieces so you can move from a working command to an integration that can flatten PDF layers.

Why Flatten PDF Layers with cURL?

Layered PDFs can display different optional content depending on viewer controls or saved visibility settings. Flattening produces a consolidated PDF whose appearance no longer depends on whether a recipient understands or enables those layers.

Engineering drawings provide a common example: a drawing may separate dimensions, notes, and production details into optional-content groups. A cURL workflow can flatten the approved view before it is sent to a vendor or print system.

The endpoint incorporates the currently visible layer content into ordinary page content. It does not provide a later way to recover alternate layer views from the flattened result.

cURL Code Example

# By default, we use the US-based API service. This is the primary endpoint for global use.
API_URL="https://api.pdfrest.com"

# For GDPR compliance and enhanced performance for European users, you can switch to the EU-based service by uncommenting the URL below.
# For more information visit https://pdfrest.com/pricing#how-do-eu-gdpr-api-calls-work
# API_URL="https://eu-api.pdfrest.com"

curl -X POST "$API_URL/flattened-layers-pdf" \
  -H "Accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -H "Api-Key: xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
  -F "file=@/path/to/file" \
  -F "output=example_out"

Source for Flatten PDF Layers: View the cURL sample on GitHub.

Breaking Down the Code

Choose the pdfRest service region

# By default, we use the US-based API service. This is the primary endpoint for global use.
API_URL="https://api.pdfrest.com"

# For GDPR compliance and enhanced performance for European users, you can switch to the EU-based service by uncommenting the URL below.
# For more information visit https://pdfrest.com/pricing#how-do-eu-gdpr-api-calls-work
# API_URL="https://eu-api.pdfrest.com"

Layer flattening uses the hostname assigned to API_URL, with the global service enabled and the EU route shown beneath it. Keeping the operation regional ensures that its input and consolidated output stay addressable by later calls.

Build the authenticated multipart request

curl -X POST "$API_URL/flattened-layers-pdf" \
  -H "Accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -H "Api-Key: xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \

The layered file is posted to /flattened-layers-pdf as one multipart upload. JSON response negotiation and API authentication remain explicit headers, making the shell request easy to inspect.

Upload the input file data

-F "file=@/path/to/file" \

The Flatten PDF Layers request reads the local source from the path after @ and sends its bytes in the multipart file field. For Flatten PDF Layers, cURL treats the path as an upload rather than ordinary form text.

Set the operation-specific fields

-F "output=example_out"

For this operation, output assigns a requested name to the consolidated PDF. Layer visibility comes from the source document state rather than from an additional list of layer names in the request.

Read the generated resource response

curl -X POST "$API_URL/flattened-layers-pdf" \

A successful layer-flattening response describes the newly generated PDF resource. Save its identifier or download information before sending the fixed rendering to a printer, vendor, or another document-processing step.

Beyond the Tutorial

By completing this walkthrough, you can flatten PDF layers from a shell script and deliver a stable rendering to systems without optional-content controls.

Confirm the intended visibility state before sending the request and compare the output with the approved view. Keep the layered source whenever future users may need alternate views or edits.

Continue exploring the Flatten PDF Layers workflow in API Lab. For the complete Flatten PDF Layers request contract, accepted values, defaults, and limitations, consult the Flatten Layers API Tool documentation.

Note: The Flatten PDF Layers example above uploads a file with multipart form data. For source content already stored in pdfRest, the Flatten PDF Layers JSON payload example shows the resource-ID request shape.