---
title: Merge PDF API - Instantly Combine PDFs at Scale
version: 1.0.1
description: Merge multiple PDF files into a single PDF document in the order they are provided. Accepts input files up to 1GB in size via file upload or existing file IDs. Returns a task ID for tracking the merge progress.
openapi: 3.1.1
servers:
  - https://api.apifreaks.com/v1.0
paths: 1
operations: 1
schemas: 3
---

## Table of Contents

- [Merge PDF API - Instantly Combine PDFs at Scale v1.0.1](#merge-pdf-api-instantly-combine-pdfs-at-scale-v101)
  - [Authentication](#authentication)
  - [PDF Operations APIs](#pdf-operations-apis)
    - [mergePdf](#mergepdf)
      - [Parameters](#parameters)
      - [Responses](#responses)
  - [Schemas](#schemas)
    - [PDFResponse](#pdfresponse)
    - [PdfMergeUploadRequest](#pdfmergeuploadrequest)
    - [ErrorResponse](#errorresponse)



# Merge PDF API - Instantly Combine PDFs at Scale v1.0.1

Merge multiple PDF files into a single PDF document in the order they are provided. Accepts input files up to 1GB in size via file upload or existing file IDs. Returns a task ID for tracking the merge 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

### mergePdf

`POST /pdf/merge`

*Combine multiple PDF files into one*

This API merges multiple PDF files into a single PDF, in the order they are provided

> 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|array[string]|false|An array of unique file IDs referencing PDF files previously uploaded to the API Freaks server. Use this parameter to merge existing files without re-uploading them. Provide multiple IDs to merge files in the specified order.|
|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|Specifies the desired name for the resulting merged PDF file. If not provided, a default name will be assigned.|
|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|[PdfMergeUploadRequest](#pdfmergeuploadrequest)|false|Multipart form-data body carrying the PDF file(s) to merge. Alternatively, reference already-uploaded files via the file_id query parameter instead of uploading here.|

##### Enumerated Values

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

> Example responses

> Merge task created successfully

```json
{
  "taskId": "04a06cd5-158d-4191-a45b-6f58249c599d",
  "inputIds": [
    "7a9e4b12-f3c8-4d56-b7e1-8c2f9d0a3e6f"
  ]
}
```

> Bad Request

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

```json
{
  "timestamp": "2026-07-27T10:49:41.432Z",
  "path": "/v1.0/pdf/merge-pdf",
  "status": 400,
  "error": "Missing File or ID",
  "message": "Please provide either a file or a file ID."
}
```

> Unsupported Media Type — File type not supported

```json
{
  "timestamp": "2026-07-27T10:49:42.554Z",
  "path": "/v1.0/pdf/merge-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)|Merge task created successfully|[PDFResponse](#pdfresponse)|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad Request|[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.|

### PdfMergeUploadRequest

Multipart form-data request body containing multiple PDF files to merge.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|file|[string]|false|none|One or more raw PDF file byte streams, each sent as a separate multipart/form-data field named 'file'. Omit this field entirely and pass one or more file_id query parameters instead to merge already-uploaded files.|

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