# PDF Splitting
Split PDFs into page ranges, ZIP archives, or private files.
## API Overview
- **HTTP Protocol:** HTTPS
- **HTTP Method:** POST
- **HTTP Endpoint:** https://api.gugudata.io/v1/imagerecognition/pdf-splitter
- **Response Type:** application/json; charset=utf-8
- **DEMO Endpoint:** https://api.gugudata.io/v1/imagerecognition/pdf-splitter/demo
- **Live Demo:** https://gugudata.io/demo/pdf-splitter
- **Postman:** https://www.postman.com/gugudata/gugudata-io
- **LLM Page:** https://gugudata.io/details/pdf-splitter/llm
- **Raw Markdown:** https://gugudata.io/details/pdf-splitter/llm.md
## Remote MCP
- **MCP Endpoint:** https://mcp.gugudata.io/mcp
- **MCP Guide:** https://gugudata.io/mcp/
- **Authorization:** OAuth authorization opens in the browser; do not paste appkeys into MCP clients.
- **Tool Scope:** MCP clients receive GuGuData API tools available to the authorized account.
## Data & API Features
- Predictable page ranges: Split a PDF into ordered parts using a configurable number of pages per file.
- Upload or URL input: Submit a PDF file or a publicly accessible PDF URL.
- Individual files or ZIP: Receive separate PDF parts or package all parts in one ZIP archive.
- Public or private delivery: Choose direct public links or controlled private-file downloads.
- Stable file ordering: Keep generated parts in source-page order for reliable document workflows.
- Document preparation: Prepare large PDFs for review, distribution, archiving, or downstream processing.
## API Request Parameters
| Name | Type | Is Required | Default Value | Remark |
| --- | --- | --- | --- | --- |
| appkey | string | true | YOUR_APPKEY | API key used to authenticate the request. |
| file | file | false | | A PDF upload. Provide exactly one of file or file_url. Maximum 20 MiB and 100 pages. |
| file_url | string | false | https://storage.gugudata.io/pdf/demo.pdf | A public HTTP or HTTPS PDF URL. Provide exactly one of file or file_url. |
| page_size | integer | false | 100 | Pages per output PDF, from 1 to 100. |
| is_zip | boolean | false | true | Return one ZIP archive when true, or individual PDF files when false. |
| storage | string | false | public | Use public for direct download URLs or private for controlled downloads. |
## API Response Parameters
| Name | Type | Remark |
| --- | --- | --- |
| dataStatus.requestParameter | string | Privacy-safe summary of the normalized request. |
| dataStatus.statusCode | integer | Application-level status code. |
| dataStatus.statusDescription | string | Human-readable application status message. |
| dataStatus.responseDateTime | string | Time at which the response was generated. |
| dataStatus.dataTotalCount | integer | Number of matching or returned records for this request. |
| data.uuid | string | Identifier for this split result. |
| data.num_files | integer | Number of logical PDF parts created. |
| data.pdf_files | array<string> | Public download URLs. Empty in private storage mode. |
| data.storage | string | The selected storage mode when private output is used. |
| data.files | array<object> | Private file references for controlled downloads. |
| data.files[].file_id | string | Private file identifier used to create a temporary download link. |
| data.files[].file_name | string | Generated output file name. |
| data.files[].content_type | string | Generated file media type. |
| data.files[].size_bytes | integer | Generated file size in bytes. |
| data.files[].index | integer | Stable output order. |
## API Response Status Codes
| Status Code | Explanation of Status Code | Remarks |
| --- | --- | --- |
| 200 | Request processed successfully. | Some endpoints expose a separate application-level status field in the response body, such as `dataStatus.statusCode`. |
| 400 | Invalid request parameters or request format. | Check required fields, data types, and request body format. |
| 401 | Missing or unknown application key. | Provide a valid `appkey` with the request. |
| 403 | The application key is recognized but access is not allowed. | The key may be expired, inactive, or not permitted for the requested API. |
| 429 | Request rate or trial usage limit exceeded. | Reduce request frequency and retry with backoff. If a trial allowance is exhausted, check Trial Keys for remaining requests and subscribe to continue. |
| 500 | Internal service error. | Retry later or contact support if the error persists. |
| 503 | Upstream service unavailable. | Retry later; the requested upstream dependency is temporarily unavailable. |
## cURL Example
```bash
curl --location 'https://api.gugudata.io/v1/imagerecognition/pdf-splitter?appkey=YOUR_APPKEY' --form 'file=@localfile_path.pdf' --form 'file_url=https://storage.gugudata.io/pdf/demo.pdf' --form 'page_size=100' --form 'is_zip=true' --form 'storage=public'
```