How to Upload a Single Binary File to pdfRest with cURL, Tutorial

Share this page

In this tutorial, we'll walk through how to upload a single binary file to pdfRest with cURL and the Upload Files API Tool. The example sends the file as the raw HTTP request body, supplies its name in a header, and captures the returned resource ID for later API calls.

Why Upload a Single Binary File to pdfRest with cURL?

Uploading a source once and referencing it by resource ID can simplify multi-step workflows. Later calls can reuse the managed file without transferring the same bytes again.

A document-processing service might upload a large PDF at the beginning of a job, then send its ID to compression, extraction, and security operations. The raw binary upload shown here keeps that first transfer compact and returns the identifier needed by those steps.

This upload mode sends the file bytes as the HTTP body rather than wrapping them in multipart form data. The separate content-filename header supplies the name that pdfRest associates with the resource.

cURL Code Example

#!/bin/sh

# 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"

UPLOAD_ID=$(curl --location "$API_URL/upload" \
--header 'api-key: xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--header 'content-filename: filename.pdf' \
--data-binary '@/path/to/file' \
 | jq -r '.files.[0].id')

echo "File successfully uploaded with an ID of: $UPLOAD_ID"

Source for Upload a Single Binary to pdfRest: 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"

The script targets the US service by default and includes the EU hostname as a commented alternative. Keep every call in one workflow on the same regional service.

Send the file as the binary request body

--data-binary '@/path/to/file' \

Unlike multipart upload, --data-binary places the local file bytes directly in the HTTP body and preserves them without form encoding.

Supply authentication and resource metadata

--header 'api-key: xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--header 'content-filename: filename.pdf' \

The API key authenticates the call, while content-filename provides the managed resource name because no multipart file part is present.

Capture the returned resource ID

UPLOAD_ID=$(curl --location "$API_URL/upload" \
--header 'api-key: xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--header 'content-filename: filename.pdf' \
--data-binary '@/path/to/file' \
 | jq -r '.files.[0].id')

--data-binary preserves the uploaded bytes, while jq -r extracts the first file ID from the JSON response into a shell variable.

Beyond the Tutorial

This tutorial gives you a minimal cURL pattern for staging one binary file and retaining its resource ID for compatible pdfRest operations.

Use a meaningful filename and store the returned ID with the job that owns it. Resource IDs remain temporary, so download required results or reuse the file before retention expires, then delete it explicitly when appropriate.

Continue exploring the Upload a Single Binary to pdfRest workflow in API Lab. For the complete Upload a Single Binary to pdfRest request contract, accepted values, defaults, and limitations, consult the Upload Files API Tool documentation.