PDF Blocks
PricingSupport
Start Free
Go to Page

Response formats and content negotiation

Single-output actions return application/pdf; the split family returns many documents as a ZIP, a JSON envelope, or multipart/mixed, chosen by the Accept header.

Most actions return a single application/pdf document. The four split actions return several documents at once, and you choose how they are packaged with the Accept request header. This page is the reference for that content negotiation — the packaging options, the JSON envelope schema, and what happens when an Accept header matches nothing.

Single-document responses

Every non-split action responds with 200 OK and the processed PDF as the raw body:

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Length: 48213

There is nothing to negotiate — stream the body to a file, as the examples on each action page do.

Multi-document responses

The split family returns many documents from one call: Split by page count, Split at page, Split by file size, and Split into page groups. Output documents are named 00001.pdf, 00002.pdf, and so on, in order. You select the packaging with the Accept request header:

Accept header Response
(none sent) application/zip — the default
application/zip A ZIP archive of the output PDFs
application/json A JSON envelope of base64-encoded documents
multipart/mixed One PDF per part
anything else 406 Not Acceptable

application/zip — the default

With no Accept header (or Accept: application/zip), the response is a ZIP archive whose entries are named 00001.pdf, 00002.pdf, and so on:

cURLbash
curl https://api.pdfblocks.com/v1/split_by_page_count \
  -H 'X-API-Key: your_api_key' \
  -F file=@input.pdf \
  -F page_count=10 \
  -o parts.zip

Unzip parts.zip to get the individual documents.

application/json — the base64 envelope

Request Accept: application/json to get every document inline in one JSON response — convenient when you want to keep the parts in memory or forward them without touching the filesystem:

cURLbash
curl https://api.pdfblocks.com/v1/split_by_page_count \
  -H 'X-API-Key: your_api_key' \
  -H 'Accept: application/json' \
  -F file=@input.pdf \
  -F page_count=10 \
  -o parts.json

The body is a documents array, each entry carrying its name and base64-encoded bytes:

{
  "documents": [
    {
      "name": "00001.pdf",
      "content": "JVBERi0xLjcKJeLjz9MK... (base64)",
      "content_type": "application/pdf"
    },
    {
      "name": "00002.pdf",
      "content": "JVBERi0xLjcKJeLjz9MK... (base64)",
      "content_type": "application/pdf"
    }
  ]
}
documentsarrayrequired

The output PDF documents, in order.

documents[].namestringrequired

The document name — 00001.pdf, 00002.pdf, and so on.

documents[].contentstring (base64)required

The PDF document, base64-encoded. Decode it to recover the raw PDF bytes.

documents[].content_typestringrequired

The media type of the document — application/pdf.

multipart/mixed — one part per document

Request Accept: multipart/mixed to stream the documents as a multipart body with one part per output PDF, in order. Each part has a Content-Type of application/pdf and a Content-Disposition naming it 00001.pdf, 00002.pdf, and so on.

cURLbash
curl https://api.pdfblocks.com/v1/split_by_page_count \
  -H 'X-API-Key: your_api_key' \
  -H 'Accept: multipart/mixed' \
  -F file=@input.pdf \
  -F page_count=10 \
  -o parts.multipart

An unmatched Accept returns 406

If you send an Accept header that matches none of the three formats above — for example Accept: application/pdf on a split action — the API responds with 406 Not Acceptable and an application/problem+json body. Either omit Accept to take the ZIP default, or request one of the supported media types. See Errors for the problem-detail shape.

For end-to-end code that calls a split action and unpacks each format — extracting the ZIP, decoding the JSON envelope, or reading the multipart parts — see the Splitting a PDF guide.