Document API

How it works

Upload a file to get an opaque document handle, run operations that reference handles and return new handles, then download the result. Handles let you chain operations without re-uploading. Documents auto-expire after 24 hours.

Base URL https://browsepdf.co/api/v1

Authentication

Send your API key as a Bearer token on every request:

Authorization: Bearer <YOUR_API_KEY>

Quickstart

# 1. Upload a document → returns { "id": "..." }
curl -X POST https://browsepdf.co/api/v1/documents \
  -H "Authorization: Bearer $KEY" \
  -F "file=@contract.pdf"

# 2. Run an operation → returns { "document": "..." }
curl -X POST https://browsepdf.co/api/v1/operations/watermark \
  -H "Authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"document":"<id>","text":"CONFIDENTIAL","tile":true}'

# 3. Download the result
curl -L https://browsepdf.co/api/v1/documents/<id>/download \
  -H "Authorization: Bearer $KEY" -o out.pdf

Operations

One-shot operations at POST /operations/{name}, referencing document handles.

Pipelines

Compose operations into a DAG so document handles flow between steps with no intermediate downloads — one request, one round trip.

curl -X POST https://browsepdf.co/api/v1/pipelines \
  -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{
    "inputs": { "src": "<docId>" },
    "nodes": {
      "conv": { "op": "convert", "in": "src" },
      "mark": { "op": "watermark", "in": "conv", "options": { "text": "DRAFT" } }
    },
    "output": "mark"
  }'

Returns the final document (or a job when a node is async). On a node error it stops and reports which nodes completed and which failed.

Async & jobs

Slow operations (convert, ocr) and large inputs return { "job": "..." } with HTTP 202. Poll GET /jobs/{id} or pass a webhook_url. Force async on any operation with the header Prefer: respond-async.

Errors & limits

Errors use a consistent shape with a matching HTTP status:

{ "error": { "code": "insufficient_credits", "message": "..." } }

Requests are rate-limited per key; responses include RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers. Metadata is free; other operations cost credits (see the table above).

For AI agents & LLMs

The API is designed to be agent-friendly: composable operations, file handles instead of blobs, and machine-readable discovery via the OpenAPI spec, /llms.txt, and /llms-full.txt.