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 or requests with async: true return a poll URL (202).

Request body

Example request

{
  "url": "https://example.com/report.pdf",
  "format": "json",
  "type": "inline",
  "async": false
}

Responses

{
  "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": "pending",
  "pollUrl": "/v1/status/req_01J9X7K2M..."
}

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" }
  ],
  "defaults": {
    "format": "json"
  }
}

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

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

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.