# API reference

The pdf-mcp REST API generates and modifies PDFs. Depending on the endpoint, it accepts JSON or multipart form data and returns a binary PDF or JSON.

## Base URL

```
https://api.pdf-mcp.io
```

## Authentication

All API requests require a Bearer token in the Authorization header:

```
Authorization: Bearer YOUR_API_KEY
```

See [Authentication](https://pdf-mcp.io/docs/authentication) for details on obtaining and managing API keys.

## Response format

Successful responses return either:
- **Binary PDF** - For in-memory PDF output (default storage mode)
- **JSON** - For storage mode responses with presigned URLs

Error responses always return JSON:

```json
{
  "error": "Error description",
  "message": "Detailed error message"
}
```

---

## PDF generation endpoints

### POST /htmlToPdf

Convert HTML to PDF. Supports CSS styling, base URL resolution, and optional S3 storage.

**Content-Type:** `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `html` | string | Yes | HTML content to convert |
| `css` | string | No | Additional CSS styles to apply |
| `filename` | string | No | Output filename (default: "document.pdf") |
| `base_url` | string | No | Base URL for resolving relative URLs in HTML |
| `storage` | object | No | Storage configuration (see below) |

**Example request:**

```bash
curl -X POST https://api.pdf-mcp.io/htmlToPdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1>Invoice #12345</h1><p>Amount: $99.00</p>",
    "css": "body { font-family: Arial; }",
    "filename": "invoice.pdf"
  }' \
  --output invoice.pdf
```

**Response:** Binary PDF file or JSON with presigned URL (when using storage mode).

See [HTML to PDF](https://pdf-mcp.io/docs/api-html-to-pdf) for full documentation.

---

### POST /textToPdf

Convert plain text to PDF with monospace formatting.

**Content-Type:** `application/json` or `multipart/form-data`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `text` | string | Yes | Plain text content |
| `font_size` | number | No | Font size in points (default: 12) |
| `filename` | string | No | Output filename (default: "document.pdf") |
| `storage` | object | No | Storage configuration |

**Example request:**

```bash
curl -X POST https://api.pdf-mcp.io/textToPdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, World!\nThis is plain text.",
    "font_size": 14
  }' \
  --output document.pdf
```

See [Text to PDF](https://pdf-mcp.io/docs/api-text-to-pdf) for full documentation.

---

### POST /imageToPdf

Convert one or more images to a PDF document.

**Content-Type:** `application/json` or `multipart/form-data`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `images_base64` | array | Conditional | List of base64-encoded images (JSON) |
| `files` | file[] | Conditional | Image file uploads (multipart only) |
| `filename` | string | No | Output filename (default: "document.pdf") |
| `storage` | object | No | Storage configuration |

**Example request (multipart):**

```bash
curl -X POST https://api.pdf-mcp.io/imageToPdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@page1.png" \
  -F "files=@page2.png" \
  -F "filename=scanned-document.pdf" \
  --output scanned-document.pdf
```

See [Image to PDF](https://pdf-mcp.io/docs/api-image-to-pdf) for full documentation.

---

## PDF manipulation endpoints

### POST /extractText

Extract text content from a PDF file.

**Content-Type:** `application/json` or `multipart/form-data`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pdf_base64` | string | Conditional | Base64-encoded PDF (JSON) |
| `pdf_url` | string | Conditional | URL to fetch PDF from (JSON) |
| `file` | file | Conditional | PDF file upload (multipart) |
| `pages` | array/string | No | Specific pages to extract (1-indexed) |

**Example request:**

```bash
curl -X POST https://api.pdf-mcp.io/extractText \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F "pages=1,2,3"
```

**Response:**

```json
{
  "text": "Combined text from all pages...",
  "pages": [
    {"page": 1, "text": "Page 1 content..."},
    {"page": 2, "text": "Page 2 content..."}
  ],
  "total_pages": 5
}
```

See [Extract Text](https://pdf-mcp.io/docs/api-extract-text) for full documentation.

---

### POST /grepPdf

Search for text patterns within a PDF. Like `grep` but for PDFs, with page numbers, positions, and context.

**Content-Type:** `application/json` or `multipart/form-data`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pdf_base64` | string | Conditional | Base64-encoded PDF (JSON) |
| `pdf_url` | string | Conditional | URL to fetch PDF from (JSON) |
| `file` | file | Conditional | PDF file upload (multipart) |
| `pattern` | string | Yes | Search pattern (plain text or regex) |
| `regex` | boolean | No | Treat pattern as regex (default: false) |
| `ignore_case` | boolean | No | Case-insensitive search (default: true) |
| `pages` | array/string | No | Specific pages to search (1-indexed) |
| `context` | number | No | Characters of context around matches (default: 100) |
| `count_only` | boolean | No | Only return match counts (default: false) |

**Example request:**

```bash
curl -X POST https://api.pdf-mcp.io/grepPdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F "pattern=invoice" \
  -F "context=50"
```

**Response:**

```json
{
  "pattern": "invoice",
  "total_matches": 3,
  "pages_with_matches": 2,
  "matches": [
    {
      "page": 1,
      "match_count": 2,
      "details": [
        {
          "match": "invoice",
          "start": 150,
          "end": 157,
          "context": "...your invoice number is..."
        }
      ]
    }
  ],
  "total_pages": 10
}
```

See [Grep PDF](https://pdf-mcp.io/docs/api-grep-pdf) for full documentation.

---

### POST /pdfToImage

Convert PDF pages to images (PNG or JPEG).

**Content-Type:** `application/json` or `multipart/form-data`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pdf_base64` | string | Conditional | Base64-encoded PDF (JSON) |
| `pdf_url` | string | Conditional | URL to fetch PDF from (JSON) |
| `file` | file | Conditional | PDF file upload (multipart) |
| `pages` | array/string | No | Specific pages to convert (1-indexed) |
| `format` | string | No | Output format: "png" or "jpeg" (default: "png") |
| `dpi` | number | No | Resolution in DPI (default: 200) |

**Example request:**

```bash
curl -X POST https://api.pdf-mcp.io/pdfToImage \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F "pages=1" \
  -F "format=png" \
  -F "dpi=150"
```

**Response:**

```json
{
  "images": [
    {
      "page": 1,
      "format": "png",
      "image_base64": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "total_pages": 10
}
```

See [PDF to Image](https://pdf-mcp.io/docs/api-pdf-to-image) for full documentation.

---

### POST /pageCount

Get the page count of a PDF file.

**Content-Type:** `application/json` or `multipart/form-data`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pdf_base64` | string | Conditional | Base64-encoded PDF (JSON) |
| `pdf_url` | string | Conditional | URL to fetch PDF from (JSON) |
| `file` | file | Conditional | PDF file upload (multipart) |

**Example request:**

```bash
curl -X POST https://api.pdf-mcp.io/pageCount \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf"
```

**Response:**

```json
{
  "page_count": 42
}
```

See [Page Count](https://pdf-mcp.io/docs/api-page-count) for full documentation.

---

### POST /extractPages

Extract or rearrange specific pages from a PDF.

**Content-Type:** `application/json` or `multipart/form-data`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pdf_base64` | string | Conditional | Base64-encoded PDF (JSON) |
| `pdf_url` | string | Conditional | URL to fetch PDF from (JSON) |
| `file` | file | Conditional | PDF file upload (multipart) |
| `pages` | array/string | Yes | Pages to extract (1-indexed), e.g., [1, 3, 2, 5] or "1,3,2,5" |
| `filename` | string | No | Output filename (default: "extracted.pdf") |
| `storage` | object | No | Storage configuration |

**Example request:**

```bash
curl -X POST https://api.pdf-mcp.io/extractPages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F "pages=1,3,5" \
  -F "filename=selected-pages.pdf" \
  --output selected-pages.pdf
```

See [Extract Pages](https://pdf-mcp.io/docs/api-extract-pages) for full documentation.

---

### POST /mergePdfs

Merge multiple PDF documents into a single file.

**Content-Type:** `application/json` or `multipart/form-data`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pdfs_base64` | array | Conditional | List of base64-encoded PDFs (JSON) |
| `pdfs_url` | array | Conditional | List of URLs to fetch PDFs from (JSON) |
| `files` | file[] | Conditional | Multiple PDF file uploads (multipart) |
| `filename` | string | No | Output filename (default: "merged.pdf") |

**Example request:**

```bash
curl -X POST https://api.pdf-mcp.io/mergePdfs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@chapter1.pdf" \
  -F "files=@chapter2.pdf" \
  -F "files=@chapter3.pdf" \
  -F "filename=complete-book.pdf" \
  --output complete-book.pdf
```

See [Merge PDFs](https://pdf-mcp.io/docs/api-merge-pdfs) for full documentation.

---

## File management endpoints

### GET /files

List stored documents for the authenticated user.

**Query parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | number | 50 | Maximum documents to return (max: 100) |
| `offset` | number | 0 | Number of documents to skip for pagination |
| `storage_mode` | string | - | Filter by storage mode ("default" or "byob") |

**Example request:**

```bash
curl -X GET "https://api.pdf-mcp.io/files?limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:**

```json
{
  "documents": [
    {
      "id": "abc123...",
      "filename": "invoice.pdf",
      "storage_mode": "default",
      "file_size_bytes": 45678,
      "page_count": 2,
      "source_endpoint": "/htmlToPdf",
      "url": "https://s3.amazonaws.com/...",
      "signed_url_expires_at": "2024-01-16T10:30:00Z",
      "expires_at": null,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}
```

---

### GET /files/search

Search documents by keyword using full-text search.

**Query parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `q` | string | - | Search query (required) |
| `mode` | string | "fulltext" | Search mode: "fulltext" or "grep" |
| `limit` | number | 20 | Maximum results (max: 100) |

**Example request:**

```bash
curl -X GET "https://api.pdf-mcp.io/files/search?q=invoice&mode=fulltext" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:**

```json
{
  "results": [
    {
      "document": {
        "id": "abc123...",
        "filename": "invoice.pdf",
        "url": "https://s3.amazonaws.com/..."
      },
      "rank": 0.85,
      "snippet": "...your invoice total is $99.00..."
    }
  ],
  "total": 5,
  "query": "invoice",
  "mode": "fulltext"
}
```

---

### GET /files/{document_id}

Get a single document by ID with a fresh signed URL.

**Path parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `document_id` | string | UUID of the document |

**Query parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `expires_in` | number | 3600 | Signed URL expiry in seconds (max: 604800) |

**Example request:**

```bash
curl -X GET "https://api.pdf-mcp.io/files/abc123?expires_in=7200" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

### DELETE /files/{document_id}

Delete a document by ID. The API removes the file from S3, soft-deletes its database record, and hides it from file listings.

**Path parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `document_id` | string | UUID of the document to delete |

**Example request:**

```bash
curl -X DELETE "https://api.pdf-mcp.io/files/abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:**

```json
{
  "deleted": true,
  "document_id": "abc123",
  "message": "Document abc123 has been deleted"
}
```

---

### GET /files/{document_id}/download

Download a document's PDF binary directly. Proxies the file from S3 and returns the raw PDF.

**Path parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `document_id` | string | UUID of the document to download |

**Example request:**

```bash
curl -X GET "https://api.pdf-mcp.io/files/abc123/download" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output document.pdf
```

**Response:** Binary PDF file with `Content-Disposition: attachment` header.

See [Files API](https://pdf-mcp.io/docs/api-files) for full documentation.

---

## Utility endpoints

### GET /health

Check API health status. No authentication required.

**Example request:**

```bash
curl -X GET https://api.pdf-mcp.io/health
```

**Response:**

```json
{
  "status": "ok"
}
```

---

## Storage configuration

Control how generated PDFs are stored and returned. Available for `/htmlToPdf`, `/textToPdf`, `/imageToPdf`, `/extractPages`, and `/mergePdfs`.

See [Storage modes](https://pdf-mcp.io/docs/storage-modes) for storage behavior, REST and MCP defaults, and the `return_binary` parameter.

**Storage object:**

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `mode` | string | `memory` | Storage mode: `memory`, `default`, or `byob` |
| `filename` | string | auto | Custom filename for stored PDFs |
| `expires_in` | number | `3600` | Signed URL expiration in seconds (60-604800) |
| `retention_days` | number | `14` | Auto-delete after N days (1-365) |

**Modes:**

- **`memory`**: return the PDF binary without storing it (REST default)
- **`default`**: store the PDF in the pdf-mcp S3 bucket and return a signed URL
- **`byob`**: store the PDF in your own S3 bucket (requires configuration)

**`return_binary` parameter:**

All PDF-producing endpoints also accept a top-level `return_binary` boolean (default: `false`). When `true` with `default` or `byob` storage, the file is stored to S3 as normal **and** the binary PDF is returned in the response instead of JSON metadata. Storage info is available in custom headers (`X-Document-Id`, `X-Storage-Mode`, `X-Storage-Url`).

**Example with storage:**

```bash
curl -X POST https://api.pdf-mcp.io/htmlToPdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1>Report</h1>",
    "storage": {
      "mode": "default",
      "filename": "report-2024.pdf",
      "expires_in": 86400,
      "retention_days": 30
    }
  }'
```

**Example with `return_binary`:**

```bash
curl -X POST https://api.pdf-mcp.io/htmlToPdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1>Report</h1>",
    "storage": { "mode": "default" },
    "return_binary": true
  }' \
  --output report.pdf
```

**Storage response (JSON):**

```json
{
  "success": true,
  "document_id": "abc123...",
  "url": "https://s3.amazonaws.com/...",
  "filename": "report-2024.pdf",
  "file_size_bytes": 45678,
  "page_count": 2,
  "storage_mode": "default",
  "expires_at": "2024-02-15T10:30:00Z",
  "signed_url_expires_at": "2024-01-16T10:30:00Z"
}
```

---

## Credit usage

| Endpoint | Credits |
|----------|---------|
| `/htmlToPdf` | 1.0 for the first page + 0.01 per additional page |
| `/renderTemplate` | 1.0 for the first page + 0.01 per additional page |
| `/pdfToImage` | 1.0 for the first page + 0.01 per additional page |
| `/templates/generate` | 1.0 per successful request |
| `/extractText` | 0.01 |
| `/grepPdf` | 0.01 |
| `/textToPdf` | 0.01 |
| `/imageToPdf` | 0.01 |
| `/pageCount` | 0.01 |
| `/extractPages` | 0.01 |
| `/mergePdfs` | 0.01 |
| `/getFormFields` | 0.01 |
| `/fillForm` | 0.01 |
| `/cropPdf` | 0.01 |
| `/files/search` | 0.01 |
| `/files`, `/files/upload`, `/files/{id}`, `/files/{id}/download`, `DELETE /files/{id}` | Free |
| Direct template CRUD, preview, schema, version, asset, and theme management endpoints | Free |

---

## Error codes

| Code | Description |
|------|-------------|
| 400 | Bad Request - Invalid input or missing required fields |
| 401 | Unauthorized - Missing or invalid Authorization header |
| 402 | Payment Required - Insufficient credits |
| 403 | Forbidden - Invalid API key or insufficient permissions |
| 404 | Not Found - Document or resource not found |
| 500 | Internal Server Error - Processing failed |
| 502 | Bad Gateway - Storage operation failed |

See [Error codes](https://pdf-mcp.io/docs/api-reference#error-codes) for the full error reference.