The pdf-mcp API provides a RESTful interface for PDF generation and manipulation. Endpoints accept JSON or multipart form data and return binary PDFs or JSON responses.

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 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:

{
  "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

Example Request:

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 for full documentation.

POST /textToPdf

Convert plain text to PDF with monospace formatting.

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

Example Request:

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 for full documentation.

POST /imageToPdf

Convert one or more images to a PDF document.

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

Example Request (Multipart):

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 for full documentation.

PDF Manipulation Endpoints

POST /extractText

Extract text content from a PDF file.

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

Example Request:

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:

{
  "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 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

Example Request:

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:

{
  "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 for full documentation.

POST /pdfToImage

Convert PDF pages to images (PNG or JPEG).

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

Example Request:

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:

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

See PDF to Image for full documentation.

POST /pageCount

Get the page count of a PDF file.

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

Example Request:

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

Response:

{
  "page_count": 42
}

See Page Count for full documentation.

POST /extractPages

Extract or rearrange specific pages from a PDF.

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

Example Request:

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 for full documentation.

POST /mergePdfs

Merge multiple PDF documents into a single file.

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

Example Request:

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 for full documentation.

File Management Endpoints

GET /files

List stored documents for the authenticated user.

Query Parameters:

Example Request:

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

Response:

{
  "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:

Example Request:

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

Response:

{
  "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:

Query Parameters:

Example Request:

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. Removes from both S3 storage and database.

Path Parameters:

Example Request:

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

Response:

{
  "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:

Example Request:

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 for full documentation.

Utility Endpoints

GET /health

Check API health status. No authentication required.

Example Request:

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

Response:

{
  "status": "ok"
}

Storage Configuration

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

For a comprehensive guide covering storage behavior, channel defaults (REST vs MCP), and the return_binary parameter, see Storage Modes.

Storage Object:

Modes:

• memory — Return PDF binary directly, no persistence (REST default)
• default — Store in pdf-mcp S3 bucket, return signed URL
• byob — Store 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:

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:

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):

{
  "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

Error Codes

See Error Codes for complete error documentation.