API Reference

Base URL

All API requests are made to:

HTTPS is required for all requests. HTTP connections are rejected.

Authentication

Authenticate by including your API key in the Authorization header:

API keys are created in the Dashboard. Each key can optionally be restricted to specific IP addresses. Keys start with pk_ and are shown only once at creation. An X-API-Key header is accepted as an alternative to Authorization: Bearer.

Convert a PDF

Fetch a PDF from a public URL and return it in your chosen output format. Inline PDFs under 10 MB are processed synchronously (200). Attachment PDFs (headless browser), larger files, requests with async: true, and jobs that exceed your timeout window return a poll URL (202). Use returnMethod: "inline" to embed the converted payload in JSON when the response is synchronous (or on status when using ?returnMethod=inline).

Request body

Example request

{
  "url": "https://example.com/report.pdf",
  "format": "json",
  "pages": "1-5",
  "type": "inline",
  "async": false,
  "returnMethod": "file",
  "timeout": 30,
  "webhook": { "url": "https://example.com/hooks/pdfpipe" }
}

Responses

With returnMethod: "inline", synchronous 200 responses include content (always a string; parse it for the json format), contentType, and for binary formats (png, jpg, webp, binary) contentEncoding: "base64". If inline delivery exceeds the size limit, the API returns a presigned URL instead and sets returnMethodFallback: true with returnMethodFallbackReason.

{
  "requestId": "req_a1b2c3...",
  "status": "complete",
  "format": "json",
  "pagesProcessed": 3,
  "creditsUsed": 1,
  "resultUrl": "https://pdfpipe-results.s3...",
  "expiresAt": "2026-08-24T12:00:00.000Z"
}

{
  "requestId": "req_a1b2c3...",
  "status": "complete",
  "format": "json",
  "pagesProcessed": 3,
  "creditsUsed": 1,
  "contentType": "application/json",
  "content": "{\"pages\":[{\"pageNumber\":1,\"text\":\"...\"}],\"metadata\":{...},\"totalPages\":3,\"extractedAt\":\"...\"}",
  "processingDurationMs": 1840
}

{
  "requestId": "req_a1b2c3...",
  "status": "complete",
  "format": "png",
  "pagesProcessed": 40,
  "creditsUsed": 1,
  "resultUrl": "https://pdfpipe-results.s3...",
  "expiresAt": "2026-08-24T12:00:00.000Z",
  "returnMethodFallback": true,
  "returnMethodFallbackReason": "Result size (7.2MB) exceeds inline limit (5.5MB)"
}

{
  "requestId": "req_a1b2c3...",
  "status": "queued",
  "pollUrl": "/v1/status/req_a1b2c3..."
}

{
  "requestId": "req_a1b2c3...",
  "status": "queued",
  "pollUrl": "/v1/status/req_a1b2c3...",
  "webhook": {
    "url": "https://example.com/hooks/pdfpipe",
    "secret": "whsec_generated_or_provided"
  },
  "message": "Processing did not complete within 30s timeout. Result will be delivered via polling or webhook."
}

{
  "code": "NOT_A_PDF",
  "message": "The URL did not return a PDF file",
  "suggestion": "Verify the URL points directly to a PDF file",
  "statusCode": 422
}

Webhooks

When you include webhook on a convert request that ends up asynchronous, PDFPipe POSTs to your HTTPS URL when processing finishes. Webhooks are available on every tier. The async 202 response includes webhook.url and webhook.secret (generated if you did not supply secret; supplied secrets must be at least 16 characters). Verify deliveries with HMAC-SHA256 over the raw request body using that secret; the request includes X-PDFPipe-Signature: sha256=<hex> (plus X-PDFPipe-Request-Id and X-PDFPipe-Event). The payload carries event (conversion.complete or conversion.failed), requestId, status, format, pagesProcessed, creditsUsed, inline content when the job used returnMethod: "inline" and fits, an error object on failure, and a timestamp. Delivery is retried 3 times (2s, 8s, 32s) on non-2xx responses, with a 10-second timeout per attempt.

Batch Convert

Submit multiple PDF URLs for conversion in a single request. All jobs are processed asynchronously and each URL counts as one request against your quota. The maximum batch size depends on your tier: 5 (Free), 25 (Starter), 50 (Pro), 100 (Business). Larger batches are rejected with VALIDATION_ERROR.

Request body

Example

{
  "urls": [
    { "url": "https://example.com/invoice-1.pdf" },
    { "url": "https://example.com/invoice-2.pdf", "format": "text" },
    {
      "url": "https://example.com/invoice-3.pdf",
      "type": "attachment",
      "pages": "1-3",
      "metadata": { "department": "finance" }
    }
  ],
  "defaults": { "format": "json" },
  "returnMethod": "inline",
  "webhook": { "url": "https://example.com/hooks/batch" }
}

{
  "batchId": "batch_a1b2c3d4e5f6...",
  "requests": [
    { "requestId": "req_...", "url": "https://example.com/invoice-1.pdf", "status": "queued" },
    { "requestId": "req_...", "url": "https://example.com/invoice-2.pdf", "status": "queued" },
    { "requestId": "req_...", "url": "https://example.com/invoice-3.pdf", "status": "queued" }
  ],
  "pollUrl": "/v1/batch/batch_a1b2c3d4e5f6..."
}

Poll Request Status

Poll the status of an asynchronous conversion request. Returns the current status and, when complete, a presigned result URL or inline content depending on query parameters.

Query parameters

Response

Status values: pending, processing, complete, failed. Once your plan's retention window has passed, a complete request returns resultUrl: null and expired: true. A failed request includes an error object with code, message, and suggestion.

{
  "requestId": "req_a1b2c3...",
  "status": "complete",
  "format": "json",
  "type": "inline",
  "detectedType": "inline",
  "pagesProcessed": 3,
  "creditsUsed": 1,
  "resultUrl": "https://pdfpipe-results.s3...",
  "expiresAt": "2026-08-24T12:00:00.000Z",
  "processingDurationMs": 4230,
  "createdAt": "2026-08-23T11:00:00.000Z",
  "updatedAt": "2026-08-23T11:00:04.230Z"
}

{
  "requestId": "req_a1b2c3...",
  "status": "complete",
  "format": "json",
  "type": "inline",
  "detectedType": "inline",
  "pagesProcessed": 3,
  "creditsUsed": 1,
  "contentType": "application/json",
  "content": "{\"pages\":[{\"pageNumber\":1,\"text\":\"...\"}],...}",
  "processingDurationMs": 4230,
  "createdAt": "2026-08-23T11:00:00.000Z",
  "updatedAt": "2026-08-23T11:00:04.230Z"
}

{
  "requestId": "req_a1b2c3...",
  "status": "failed",
  "format": "json",
  "type": "attachment",
  "error": {
    "code": "ATTACHMENT_DOWNLOAD_FAILED",
    "message": "The headless browser could not download the PDF from this URL",
    "suggestion": "The page may require JavaScript interaction or authentication"
  },
  "createdAt": "2026-08-23T11:00:00.000Z",
  "updatedAt": "2026-08-23T11:00:08.000Z"
}

Batch Status

Check the overall status of a batch job and get individual request results.

{
  "batchId": "batch_a1b2c3d4e5f6...",
  "total": 3,
  "completed": 2,
  "failed": 0,
  "pending": 1,
  "requests": [
    { "requestId": "req_...", "status": "complete", "resultUrl": "https://..." },
    { "requestId": "req_...", "status": "complete", "resultUrl": "https://..." },
    { "requestId": "req_...", "status": "processing" }
  ]
}

Usage

Returns your current month's usage statistics.

{
  "tier": "starter",
  "month": "2026-08",
  "requestsUsed": 47,
  "requestsLimit": 500,
  "remaining": 453,
  "testRequestsUsed": 2,
  "testRequestsLimit": 10,
  "testRequestsRemaining": 8,
  "resetsAt": "2026-09-01T00:00:00.000Z"
}

API Keys

{
  "keys": [
    {
      "keyId": "a1b2c3d4e5f6",
      "name": "Production key",
      "prefix": "pk_a1b2c",
      "allowedIps": ["203.0.113.10"],
      "createdAt": "2026-01-15T10:00:00.000Z",
      "revokedAt": null
    }
  ]
}

{
  "name": "Production key",
  "allowedIps": ["203.0.113.10"]
}

{
  "keyId": "a1b2c3d4e5f6",
  "name": "Production key",
  "prefix": "pk_a1b2c",
  "key": "pk_a1b2c3d4...full_key_here"
}

{
  "allowedIps": ["203.0.113.10", "198.51.100.0"]
}

{
  "keyId": "a1b2c3d4e5f6",
  "name": "Production key",
  "prefix": "pk_a1b2c",
  "allowedIps": ["203.0.113.10", "198.51.100.0"],
  "createdAt": "2026-01-15T10:00:00.000Z"
}

Error Codes

Errors return a JSON body with a code, a human-readable message, and the statusCode. Errors about the source PDF or URL also carry a suggestion.

{
  "code": "VALIDATION_ERROR",
  "message": "url: URL must use http or https protocol",
  "statusCode": 400
}

Request and account errors

Source URL and PDF errors

Returned synchronously with the HTTP status shown, or inside the error object of a failed status/batch entry when the job ran asynchronously. Each includes a suggestion.

Rate Limits

Quotas are applied per account on a monthly cycle that resets on the 1st. When you exceed your limit on Free, Starter, or Pro, requests return 429 RATE_LIMIT_EXCEEDED. Business accounts are not capped; requests beyond 20,000 are billed at the overage rate. The Free tier also allows at most 25 attachment (headless browser) PDFs per month. Webhooks, page ranges, batch, and auto-detection are available on all tiers.

Dashboard AI Help is separate from PDF conversion quotas: paid plans (Starter+) include an in-dashboard assistant (Claude) at /dashboard/chat with documentation-grounded answers. Free tier does not include AI Help. Limit: 50 questions per user per calendar day (UTC). See also Getting Started.