# 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
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](/docs/api/split-pdf-by-page-count),
[Split at page](/docs/api/split-pdf-at-page),
[Split by file size](/docs/api/split-pdf-by-file-size), and
[Split into page groups](/docs/api/split-pdf-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:

```bash title="cURL"
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:

```bash title="cURL"
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:

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

<ParamField name="documents" type="array" required>
  The output PDF documents, in order.
</ParamField>

<ParamField name="documents[].name" type="string" required>
  The document name — `00001.pdf`, `00002.pdf`, and so on.
</ParamField>

<ParamField name="documents[].content" type="string (base64)" required>
  The PDF document, base64-encoded. Decode it to recover the raw PDF bytes.
</ParamField>

<ParamField name="documents[].content_type" type="string" required>
  The media type of the document — `application/pdf`.
</ParamField>

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

```bash title="cURL"
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](/docs/api/errors) for the problem-detail shape.

<Tip>
  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](/docs/api/splitting-a-pdf) guide.
</Tip>