API reference

Request and response details for pdf-mcp PDF endpoints

On this page

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

Plain text

https://api.pdf-mcp.io

Authentication

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

Plain text

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:

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:

Shell

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

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:

Shell

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

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

Shell

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

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:

Shell

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

Shell

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

Shell

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

Shell

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

Shell

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

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:

Shell

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:

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:

Shell

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:

Shell

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:

Shell

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:

Shell

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:

Shell

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:

Shell

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

Shell

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:

Shell

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 for the full error reference.