Merge PDF API

Merge several PDFs from public URLs or file uploads into a single PDF. The combined size of all input files can be up to 256 MB. The result is written to the run's default key-value store as merged.pdf, together with a machine-readable OUTPUT record.

The Actor uses an enterprise-grade PDF engine to copy every page into one document, preserving the order of the input list. It is intended to be called through the Apify API or from Apify Console.

Input

Field	Type	Default	Description
pdfUrls	array of strings	Two sample PDFs	Public HTTP(S) URLs of the PDFs to merge, in output order.
pdfFiles	array of strings	-	Uploaded PDFs or Apify key-value store record URLs. Takes precedence over pdfUrls.

Provide one or more PDFs. If both fields are empty, the Actor runs with two sample PDFs so the merge can be tested immediately. When pdfFiles contains at least one file, the pdfUrls field is ignored for that run.

For backwards compatibility, the legacy string fields url and fileUpload are still accepted when the array fields are empty. New integrations should use pdfUrls and pdfFiles.

Only PDF input is accepted. URLs do not need to end in .pdf; the downloaded content is checked for a PDF header before merging starts. Password-protected PDFs are rejected because their pages cannot be read without the password. The combined size of all input PDFs must not exceed 256 MB.

Output

The merged PDF is stored in the run's default key-value store under merged.pdf with content type application/pdf.

When the run finishes, the Output tab in Apify Console lists the merged PDF and links to the OUTPUT record. These links are defined in .actor/output_schema.json.

An OUTPUT JSON record describes the result:

{
  "success": true,
  "message": "Merged 2 PDFs (5.1 MB, 12 pages) into one PDF (5.0 MB). The result is stored as \"merged.pdf\" in the run's key-value store.",
  "input": {
    "files": 2,
    "bytes": 5347738,
    "mb": "5.1 MB",
    "pages": 12,
    "sources": [
      {
        "source": "https://example.com/first.pdf",
        "filename": "first.pdf",
        "bytes": 3145728,
        "mb": "3.0 MB",
        "pages": 8
      },
      {
        "source": "https://example.com/second.pdf",
        "filename": "second.pdf",
        "bytes": 2202010,
        "mb": "2.1 MB",
        "pages": 4
      }
    ]
  },
  "output": {
    "key": "merged.pdf",
    "storeId": "STORE_ID",
    "filename": "merged.pdf",
    "contentType": "application/pdf",
    "bytes": 5242880,
    "mb": "5.0 MB",
    "pages": 12,
    "downloadUrl": "https://api.apify.com/v2/key-value-stores/STORE_ID/records/merged.pdf?signature=..."
  },
  "pricing": {
    "eventName": "pdf-mb",
    "unitPriceUsd": 0.001,
    "chargedEvents": 6,
    "estimatedCostUsd": 0.006,
    "charged": true,
    "actorStart": {
      "eventName": "apify-actor-start",
      "unitPriceUsd": 0.002,
      "events": 1,
      "estimatedCostUsd": 0.002,
      "chargedAutomatically": true
    },
    "estimatedTotalCostUsd": 0.008
  },
  "limits": {
    "memoryMb": 512,
    "maxMemoryMb": 512,
    "diskMb": 1024,
    "maxInputBytes": 268435456,
    "maxInputMb": 256
  }
}

On failure, success is false, error.code identifies the problem, and error.message contains a user-facing explanation. The OUTPUT record is written for both successful and failed runs.

Filename rules

The output key is always merged.pdf. Source filenames appear only in the OUTPUT metadata and are sanitized before use with a cross-platform filename cleaner. Directory components are removed, characters that are invalid in filenames are stripped, reserved device names are defused, and trailing dots or spaces are removed. The remaining name is then normalized to letters, digits, ., _, and -, and truncated to a safe length. For example, hello world.pdf becomes hello_world.pdf.

Pricing

The Actor uses pay-per-event (PPE) pricing with two charges.

Per-run fee

Apify charges the synthetic apify-actor-start event automatically at $0.002 per start ($2 per 1,000 runs). It applies to every run, including runs that later fail, and is not charged by the Actor code.

Because the Actor's memory is fixed at 512 MB, each run incurs exactly one start event ($0.002).

Per-MB fee

The Actor charges the event pdf-mb once per started megabyte of the total input size, at $0.001 per event:

• 1 byte to 1 MB -> 1 event -> $0.001
• 5.1 MB total -> 6 events -> $0.006
• 128 MB total -> 128 events -> $0.128
• 256 MB total -> 256 events -> $0.256

This event is charged only after the merged PDF has been saved to the key-value store. Failed runs, including oversized, non-PDF, and password-protected inputs, are not charged for pdf-mb.

Total cost

Total input	Start fee	pdf-mb	Total
1 byte to 1 MB	$0.002	$0.001	$0.003
5.1 MB	$0.002	$0.006	$0.008
128 MB	$0.002	$0.128	$0.130
256 MB	$0.002	$0.256	$0.258

The pricing object in OUTPUT reports both the pdf-mb charge and the automatic start fee.

Size limits

The Actor runs with 512 MB of memory and 1 GB of disk (Apify gives each run disk space equal to twice its memory). To leave headroom for the merge engine and the output file, the total input limit is half the memory:

max total input size = memory / 2 = 256 MB

Memory	Disk	Maximum total input
512 MB (fixed)	1 GB	256 MB

The Actor checks the remote Content-Length of every input before downloading. If a server does not report a size, the same limit is enforced while streaming the download. An oversized set of files produces an OUTPUT record with error.code = "FILE_TOO_LARGE" and no pdf-mb charge.

Files whose combined size exceeds 256 MB cannot be processed by this Actor; remove some files, use smaller PDFs, or merge them in several runs. The default run timeout is 10 minutes.

Calling the API

Start an asynchronous run with a list of URLs:

curl -X POST "https://api.apify.com/v2/acts/OWNER~merge-pdf-api/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pdfUrls": [
      "https://www.pdfpdf.com/samples/pptdemo1.pdf",
      "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"
    ]
  }'

The response contains data.id, data.defaultKeyValueStoreId, and data.status. Poll the run, then read the metadata and download the result:

curl "https://api.apify.com/v2/actor-runs/RUN_ID?token=$APIFY_TOKEN"

curl "https://api.apify.com/v2/key-value-stores/STORE_ID/records/OUTPUT?token=$APIFY_TOKEN"

curl -OJ "https://api.apify.com/v2/key-value-stores/STORE_ID/records/merged.pdf?token=$APIFY_TOKEN"

Synchronous call (waits for the run to finish):

curl -X POST "https://api.apify.com/v2/acts/OWNER~merge-pdf-api/run-sync?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pdfUrls":["https://example.com/first.pdf","https://example.com/second.pdf"]}'

Uploading files is also supported. Upload the PDFs to a key-value store, then pass their record URLs as pdfFiles:

curl -X POST "https://api.apify.com/v2/acts/OWNER~merge-pdf-api/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pdfFiles": [
      "https://api.apify.com/v2/key-value-stores/STORE_ID/records/first.pdf",
      "https://api.apify.com/v2/key-value-stores/STORE_ID/records/second.pdf"
    ]
  }'

Error codes

Code	Meaning
INVALID_INPUT	Missing/invalid URL list or unsupported scheme.
DOWNLOAD_FAILED	An input PDF could not be downloaded (DNS, TLS, HTTP 4xx/5xx, timeout).
EMPTY_FILE	One of the input sources returned an empty file.
NOT_A_PDF	One of the inputs is not a valid PDF or has no readable pages.
PASSWORD_PROTECTED	One of the PDFs is encrypted and needs a password.
MERGE_FAILED	The merge engine could not produce the merged PDF.
UPLOAD_FAILED	The result could not be written to the key-value store.
FILE_TOO_LARGE	The combined input exceeds the run's memory-derived limit.
TEMP_DIR_FAILED	The run could not create a temporary directory.