REST API Overview

Integrate PDF processing into your applications with the Mapsoft PDF Hub REST API.

Introduction

The Mapsoft PDF Hub REST API provides programmatic access to the full suite of PDF processing tools. You can convert, merge, split, protect, compress, extract text, and perform dozens of other operations on PDF documents by sending HTTP requests to our endpoints.

The API is designed around REST principles. All endpoints accept standard HTTP methods, use JSON for structured responses, and return appropriate HTTP status codes. File uploads use multipart/form-data encoding.

Base URL

All API requests should be made to the following base URL:

https://pdf.mapsoft.com/api/pdf/

All endpoints are served over HTTPS. Plain HTTP requests will be rejected.

Request Format

All API endpoints accept POST requests with multipart/form-data content type. This is the standard encoding for file uploads and allows you to send both files and parameters in a single request.

A typical request includes:

• Authentication headers — X-Api-Key and X-Api-Secret (required on every request)
• File field — The PDF or document file to process (field name: file)
• Parameter fields — Operation-specific options such as page ranges, output formats, or passwords

POST /api/pdf/convert HTTP/1.1
Host: pdf.mapsoft.com
X-Api-Key: your-api-key
X-Api-Secret: your-api-secret
Content-Type: multipart/form-data; boundary=----FormBoundary

------FormBoundary
Content-Disposition: form-data; name="file"; filename="document.docx"
Content-Type: application/octet-stream

(binary file data)
------FormBoundary--

Response Format

API responses vary depending on the operation:

Response Type	Content-Type	Description
File download	application/pdf, application/zip, etc.	The processed file is returned directly in the response body. Used by conversion, merge, split, and similar operations.
JSON data	application/json	Structured data such as extracted text, metadata, or analysis results.
Error	application/json	Error details including a message and HTTP status code.

For file download responses, the Content-Disposition header contains the suggested filename:

Content-Disposition: attachment; filename="output.pdf"

Rate Limits

To ensure fair usage and maintain service quality, the API enforces rate limits on all requests.

Limit	Value
Requests per minute	60
Requests per hour	500
Maximum file size	100 MB (200 MB for merge)
Concurrent requests	5

When you exceed a rate limit, the API returns a 429 Too Many Requests response. The Retry-After header indicates how many seconds to wait before retrying.

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

Status Code	Meaning
200 OK	Request succeeded. Response contains the processed file or data.
400 Bad Request	Invalid parameters, missing required fields, or unsupported file format.
401 Unauthorized	Missing or invalid API key/secret.
403 Forbidden	API key does not have permission for this operation.
413 Payload Too Large	File exceeds the maximum allowed size.
429 Too Many Requests	Rate limit exceeded. See Retry-After header.
500 Internal Server Error	An unexpected error occurred on the server.

Error responses are returned as JSON:

{
    "error": "Invalid file format",
    "message": "The uploaded file is not a valid PDF document.",
    "statusCode": 400
}

API Sections