> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pdfnoodle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Split PDF

> Split a single PDF file into multiple smaller PDFs. You can split by specific page ranges or at regular intervals.

<Note>
  This tool requires a publicly accessible PDF URL. If your file is stored locally or in memory, you can upload it to our temporary bucket first using the [Get Signed Upload URL](/api-reference/tools/get-signed-upload-url) endpoint.
</Note>

POST [https://api.pdfnoodle.com/v1/tools/split-pdf](https://api.pdfnoodle.com/v1/tools/split-pdf)

## Request

<CodeGroup>
  ```bash cURL theme={null}
  # Split by intervals (every 2 pages)
  curl --location 'https://api.pdfnoodle.com/v1/tools/split-pdf' \
  --header 'Authorization: Bearer pdfnoodle_api_123456789' \
  --header 'Content-Type: application/json' \
  --data '{
      "url": "https://example.com/large-document.pdf",
      "splitMode": "intervals",
      "interval": 2,
      "finalFilename": "chapter.pdf",
      "expiration": 3600
  }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.pdfnoodle.com/v1/tools/split-pdf", {
    method: "POST",
    headers: {
      Authorization: "Bearer pdfnoodle_api_123456789",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      url: "https://example.com/large-document.pdf",
      splitMode: "intervals",
      interval: 2,
      finalFilename: "chapter.pdf",
      expiration: 3600,
    }),
  });

  const result = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.pdfnoodle.com/v1/tools/split-pdf',
      headers={
          'Authorization': 'Bearer pdfnoodle_api_123456789',
          'Content-Type': 'application/json'
      },
      json={
          'url': 'https://example.com/large-document.pdf',
          'splitMode': 'intervals',
          'interval': 2,
          'finalFilename': 'chapter.pdf',
          'expiration': 3600
      }
  )

  result = response.json()
  ```
</CodeGroup>

## Response

<CodeGroup>
  ```json Success (200 OK) theme={null}
  {
    "status": "SUCCESS",
    "totalParts": 3,
    "fileName": "chapter.pdf",
    "urlValidUntil": "2025-01-01T02:00:00.000Z",
    "urls": [
      "https://s3.amazonaws.com/.../chapter_1.pdf",
      "https://s3.amazonaws.com/.../chapter_2.pdf",
      "https://s3.amazonaws.com/.../chapter_3.pdf"
    ],
    "zipUrl": "https://s3.amazonaws.com/.../chapter.zip"
  }
  ```

  ```json Validation Error (400 Bad Request) theme={null}
  {
    "message": "ranges is ranges is required when splitMode is \"ranges\""
  }
  ```
</CodeGroup>

The response contains an array of `urls`, each pointing to a split part of the original PDF. Parts are named using the pattern `{filename}_{partNumber}.pdf` (e.g., `chapter_1.pdf`, `chapter_2.pdf`).

A `zipUrl` is also included, which points to a `.zip` archive containing all split parts for convenient bulk download.

All files are stored persistently and can be re-downloaded at any time from the [dashboard logs](https://app.pdfnoodle.com/logs).

## Split Modes

There are two ways to split a PDF:

### Intervals Mode (default)

Splits the PDF every N pages. For example, a 10-page PDF with `interval: 3` will produce 4 parts: pages 1-3, 4-6, 7-9, and 10.

```json theme={null}
{
  "url": "https://example.com/document.pdf",
  "splitMode": "intervals",
  "interval": 3
}
```

### Ranges Mode

Splits the PDF by specific page ranges. Use comma-separated ranges like `1-3,5,7-10`.

```json theme={null}
{
  "url": "https://example.com/document.pdf",
  "splitMode": "ranges",
  "ranges": "1-3,5,7-10"
}
```

<Warning>
  When using `splitMode: "ranges"`, the `ranges` parameter is required. When using `splitMode: "intervals"`, the `interval` parameter is required.
</Warning>

## Operation Tracking

Each split operation creates a record in your dashboard logs, allowing you to:

* View all past split operations with their status and metadata
* Re-download split files at any time via the logs table
* Track usage across your team

<Note>
  **Business and Scale plans**: Split operations are unlimited and do not count toward your PDF generation quota.

  **Starter plans**: Split operations count toward your total volume quota.
</Note>

## Async Mode

By default, the request waits for the split to complete before returning a response. If you set `async: true`, the endpoint returns immediately with a `requestId` and `statusUrl` that you can use to poll for the result.

```json Async Response (200 OK) theme={null}
{
  "requestId": "pdfnoodle_request_123456789",
  "statusUrl": "https://api.pdfnoodle.com/v1/tools/status/pdfnoodle_request_123456789",
  "message": "The tool is being executed asynchronously. Check the status using the status URL."
}
```

Use the [Get Tool Status](/api-reference/tools/get-tool-status) endpoint to check the result.

### Request Timeout (>30 seconds)

<Warning>
  Even without `async: true`, if the operation takes more than 30 seconds it will automatically be processed in the background.
</Warning>

If the split takes longer than 30 seconds, you'll receive a `202 Accepted` response with a `requestId` and `statusUrl` to poll for the result:

```json Timeout (202 Accepted) theme={null}
{
  "requestId": "pdfnoodle_request_123456789",
  "statusUrl": "https://api.pdfnoodle.com/v1/tools/status/pdfnoodle_request_123456789",
  "message": "Couldn't complete the operation within 30 seconds, it is being processed asynchronously. Check the status using the status URL."
}
```

## Parameters

<ParamField body="url" type="string" required>
  A valid, publicly accessible URL pointing to the PDF file you want to split.
</ParamField>

<ParamField body="splitMode" type="string" default="intervals">
  The method to use for splitting. Must be either `"ranges"` or `"intervals"`.
  Default: `"intervals"`.
</ParamField>

<ParamField body="ranges" type="string">
  Specific page ranges to extract (e.g., `"1-3,5,7-10"`). Required when
  `splitMode` is `"ranges"`.
</ParamField>

<ParamField body="interval" type="number" default="1">
  Split the PDF every N pages. Must be at least 1. Required when `splitMode` is
  `"intervals"`. Default: `1`.
</ParamField>

<ParamField body="finalFilename" type="string">
  The base filename for the split parts. Must end with `.pdf`. Each part will be
  named `{basename}_{partNumber}.pdf`. If not provided, the original filename
  from the URL will be used, or a random name will be generated.
</ParamField>

<ParamField body="expiration" type="number" default="3600">
  Number of seconds that the generated signed URLs will take to expire. Must be
  between 60 (1 minute) and 604800 (7 days). Default: 3600 (1 hour).
</ParamField>

<ParamField body="async" type="boolean" default="false">
  If `true`, the request returns immediately with a `requestId` and `statusUrl`
  instead of waiting for the operation to complete. You can then poll the
  [Get Tool Status](/api-reference/tools/get-tool-status) endpoint to check
  when the result is ready.
</ParamField>