---
title: PDF Split API Reference
version: 1.0.0
description: Split a PDF file into individual pages or groups of pages. Returns a task ID for tracking the split progress.
openapi: 3.1.1
servers:
  - https://api.apifreaks.com/v1.0
paths: 1
operations: 1
schemas: 3
---

## Table of Contents

- [PDF Split API Reference v1.0.0](#pdf-split-api-reference-v100)
  - [Authentication](#authentication)
  - [PDF Operations APIs](#pdf-operations-apis)
    - [splitPdf](#splitpdf)
      - [Parameters](#parameters)
      - [Responses](#responses)
  - [Schemas](#schemas)
    - [PDFResponse](#pdfresponse)
    - [PdfFileUploadRequest](#pdffileuploadrequest)
    - [ErrorResponse](#errorresponse)



# PDF Split API Reference v1.0.0

Split a PDF file into individual pages or groups of pages. Returns a task ID for tracking the split progress.

Base URLs:

* [https://api.apifreaks.com/v1.0](https://api.apifreaks.com/v1.0)

## Authentication

* API Key (ApiKeyAuthHeader)
    - Parameter Name: **X-apiKey**, in: header. Pass your API key via the X-apiKey request header.

* API Key (ApiKeyAuthQuery)
    - Parameter Name: **apiKey**, in: query. Pass your API key via the apiKey query parameter.

## PDF Operations APIs

### splitPdf

`POST /pdf/split`

*Split a PDF into smaller files*

This API splits a PDF into multiple parts based on specified page numbers or ranges.

> Body parameter

```yaml
file: string

```

#### Parameters

|Name|In|Type|Required|Description|
|---|---|---|---|---|
|format|query|string|false|Specifies the desired format for the API response. Choose 'json' for a JSON object or 'xml' for an XML structure.|
|file_id|query|string|false|The unique ID of a PDF file already uploaded to the API Freaks server. Use this as an alternative to uploading a new file directly.|
|destroy|query|boolean|false|If set to `true`, the input file(s) will be permanently deleted from the server immediately after the output PDF is generated.|
|output|query|string|false|The desired base name for the output PDF files after splitting. If not provided, a default naming convention will be used.|
|pages|query|array[string]|false|Defines the page numbers or ranges where the PDF should be split. Provide individual pages and/or ranges in any order (for example: "1-4,9-5,16-last"). Separate entries with commas and use hyphens for ranges.|
|webhook_url|query|string|false|The URL to which the webhook notification will be sent after the task is completed.|
|webhook_failure_notification|query|boolean|false|If true, a notification will also be sent by email in case the webhook request fails all the retries.  The email notification will be sent to the requesting user or their organization’s admin if part of one.|
|X-Webhook-Authorization|header|string|false|Optional custom header for webhook requests. Format: `Key:Value` (e.g., `Authorization:Bearer token123`). This will be sent as an HTTP header in the webhook call.|
|body|body|[PdfFileUploadRequest](#pdffileuploadrequest)|false|Multipart form-data body carrying the PDF file to split. Alternatively, reference an already-uploaded file via the file_id query parameter instead of uploading here.|

##### Detailed descriptions

**pages**: Defines the page numbers or ranges where the PDF should be split. Provide individual pages and/or ranges in any order (for example: "1-4,9-5,16-last"). Separate entries with commas and use hyphens for ranges.

Special keywords (use alone):

• `even` — split at every even-numbered page

• `odd` — split at every odd-numbered page

• `all` — split the PDF into single-page files

The keyword `last` can be used anywhere in the string, in combination with page numbers or ranges (for example: "5-last", "last-2", "1,last,9").

Examples:
- "1,4-2,last"
- "odd"
- "all"
- "last,2-5"

Invalid example: "1,odd" (mixing a keyword other than "last" with specific pages/ranges is not allowed). You can pass multiple pages entries to produce multiple output files.

##### Enumerated Values

|Parameter|Value|
|---|---|
|format|json|
|format|xml|

> Example responses

> Split task created successfully. Malformed or out-of-range page specifications are not rejected synchronously — the task is created, then fails asynchronously; poll the task status endpoint and check for status "failed" with an error/message pair.

```json
{
  "taskId": "a533a95c-b3fb-49f0-abb1-bef2f3e805ef",
  "inputIds": [
    "62f910b6-69ce-4cbc-8285-eee5f16467be"
  ]
}
```

> Bad Request — Invalid file ID

```json
{
  "error": "Invalid File ID Provided",
  "message": "Please provide a valid file ID",
  "path": "/v1.0/pdf/split",
  "status": 400,
  "timestamp": "2026-07-27T10:54:00.793Z"
}
```

> Unsupported Media Type — File type not supported

```json
{
  "timestamp": "2026-07-27T10:54:01.347Z",
  "path": "/v1.0/pdf/split-pdf",
  "status": 415,
  "error": "Unsupported File Type",
  "message": "The provided file type is not supported. Refer to the documentation for valid file types."
}
```

#### Responses

|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Split task created successfully. Malformed or out-of-range page specifications are not rejected synchronously — the task is created, then fails asynchronously; poll the task status endpoint and check for status "failed" with an error/message pair.|[PDFResponse](#pdfresponse)|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad Request — Invalid file ID|[ErrorResponse](#errorresponse)|
|415|[Unsupported Media Type](https://tools.ietf.org/html/rfc7231#section-6.5.13)|Unsupported Media Type — File type not supported|[ErrorResponse](#errorresponse)|

#### Response Headers

|Status|Header|Type|Format|Description|
|---|---|---|---|---|
|200|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|400|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|415|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|

To perform this operation, you must be authenticated by means of one of the following methods:
ApiKeyAuthHeader, ApiKeyAuthQuery

## Schemas

### PDFResponse

Response containing the task ID and input file IDs for a PDF processing task.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|taskId|string|true|none|Task ID of the requested task, used to check the task status.|
|inputIds|[string]|false|none|File IDs for the input files provided for the task. Not returned when destroy parameter is true.|

### PdfFileUploadRequest

Multipart form-data request body containing the PDF file to process.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|file|string(binary)|false|none|Raw PDF file bytes sent as a multipart/form-data field named 'file'. Omit this field entirely and pass file_id in the query string instead to use an already-uploaded file.|

### ErrorResponse

Standard error envelope returned by the API on failed requests.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|error|string|false|none|Short error category or exception type.|
|message|string|true|none|Human-readable error message describing the failure.|
|path|string|false|none|API endpoint path that produced the error.|
|status|integer|false|none|HTTP status code returned with the error.|
|timestamp|string(date-time)|false|none|Timestamp when the error occurred (ISO 8601).|