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_live_ and are shown only once at creation.

Convert a PDF

Convert a PDF from a URL into your chosen output format. Files under 10 MB are processed synchronously (200). Larger files, requests with async: true, or 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",
  "type": "inline",
  "async": false,
  "returnMethod": "file",
  "timeout": 30,
  "webhook": { "url": "https://example.com/hooks/pdfpipe" }
}

Responses

With returnMethod: "inline", synchronous 200 responses include content, contentType, and for binary formats (png, jpg, webp, binary, base64) contentEncoding: "base64". If inline delivery exceeds size limits, the API may return a presigned URL instead and set returnMethodFallback: true with returnMethodFallbackReason.

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

{
  "requestId": "req_01J9X7K2M...",
  "status": "complete",
  "format": "json",
  "pagesProcessed": 3,
  "creditsUsed": 1,
  "returnMethod": "inline",
  "contentType": "application/json",
  "content": { "pages": [ { "page": 1, "text": "..." } ] },
  "returnMethodFallback": false
}

{
  "requestId": "req_01J9X7K2M...",
  "status": "pending",
  "pollUrl": "/v1/status/req_01J9X7K2M..."
}

{
  "requestId": "req_01J9X7K2M...",
  "status": "pending",
  "pollUrl": "/v1/status/req_01J9X7K2M...",
  "webhook": {
    "url": "https://example.com/hooks/pdfpipe",
    "secret": "whsec_generated_or_provided"
  },
  "message": "Example: job queued after synchronous processing exceeded your timeout (1–60s)."
}

Webhooks

When you include webhook on a convert request that ends up asynchronous, PDFPipe POSTs to your HTTPS URL when processing finishes. The async 202 response includes webhook.url and webhook.secret (generated if you did not supply secret). 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).

Batch Convert

Submit multiple PDF URLs for conversion in a single request. All jobs are processed asynchronously. The maximum batch size depends on your tier.

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",
      "returnMethod": "file",
      "webhook": { "url": "https://example.com/hooks/invoice-3" }
    }
  ],
  "defaults": {
    "format": "json",
    "returnMethod": "inline",
    "webhook": { "url": "https://example.com/hooks/batch-default" }
  }
}

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

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

{
  "requestId": "req_01J9X7K2M...",
  "status": "complete",
  "format": "json",
  "type": "inline",
  "pagesProcessed": 3,
  "creditsUsed": 1,
  "returnMethod": "inline",
  "contentType": "application/json",
  "content": { "pages": [ { "page": 1, "text": "..." } ] },
  "returnMethodFallback": false,
  "processingDurationMs": 4230,
  "createdAt": "2026-02-22T11:00:00.000Z",
  "updatedAt": "2026-02-22T11:00:04.230Z"
}

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.

{
  "month": "2026-02",
  "requestCount": 47,
  "tier": "starter"
}

API Keys

{
  "keys": [
    {
      "keyId": "a1b2c3d4e5f6",
      "name": "Production key",
      "prefix": "pk_live_",
      "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_live_",
  "key": "pk_live_abc123...full_key_here"
}

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

{
  "keyId": "a1b2c3d4e5f6",
  "name": "Production key",
  "prefix": "pk_live_",
  "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 and human-readable message:

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

Rate Limits

Rate limits are applied per account on a monthly billing cycle. When you exceed your limit, requests return a 429 status. Business tier accounts can configure overage billing instead.

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.