API Reference

Base URL

https://api.pdfbase.dev/v1

All endpoints are versioned. The current version is v1.

Authentication

All requests require a Bearer token:

Authorization: Bearer pk_live_xxx

See Authentication for key types and scopes.

Credits

Every response that consumes credits includes balance headers:

X-Credits-Remaining: 4,287
X-Credits-Used: 1
X-Credits-Warning: Balance low. 47 credits remaining.

The warning header only appears when your balance drops below 100. See Pricing for credit packs and auto-refill.

Request format

Content type: application/json
All request bodies are JSON
All timestamps are ISO 8601 in UTC
File uploads use multipart/form-data (merge, watermark, extract endpoints only)

Response format

Every response includes an object field identifying the resource type:

{
  "id": "pdf_x7Kf9m",
  "object": "pdf",
  "status": "completed",
  ...
}

Resource IDs

All IDs are prefixed by resource type for easy identification:

Resource	Prefix	Example
PDF	`pdf_`	`pdf_x7Kf9m`
Template	`tpl_`	`tpl_abc123`
Batch	`bat_`	`bat_def456`
File	`file_`	`file_ghi789`
Event	`evt_`	`evt_jkl012`
Webhook Endpoint	`we_`	`we_mno345`

Pagination

List endpoints return paginated results using cursor-based pagination:

GET /v1/pdfs?limit=25&starting_after=pdf_x7Kf9m

{
  "object": "list",
  "data": [...],
  "has_more": true,
  "next_cursor": "pdf_abc123"
}

Parameter	Type	Default	Description
`limit`	integer	25	Number of results (1-100)
`starting_after`	string	—	Cursor for forward pagination
`ending_before`	string	—	Cursor for backward pagination

Endpoint map

Phase 1 — Create (Launch)

Method	Endpoint	Description
`POST`	`/v1/pdfs`	Create a PDF from HTML, URL, or raw content
`GET`	`/v1/pdfs/:id`	Retrieve a PDF and its metadata
`GET`	`/v1/pdfs`	List all PDFs
`POST`	`/v1/templates`	Create a reusable template
`GET`	`/v1/templates/:id`	Retrieve a template
`GET`	`/v1/templates`	List all templates
`PATCH`	`/v1/templates/:id`	Update a template
`DELETE`	`/v1/templates/:id`	Delete a template
`POST`	`/v1/templates/:id/render`	Render a template with data
`POST`	`/v1/batches`	Create a batch job
`GET`	`/v1/batches/:id`	Retrieve batch status and results

Phase 2 — Edit + Convert

Method	Endpoint	Description
`POST`	`/v1/pdfs/merge`	Merge multiple PDFs into one
`POST`	`/v1/pdfs/split`	Split a PDF into separate pages
`POST`	`/v1/pdfs/watermark`	Add text or image watermark
`POST`	`/v1/convert/office`	Convert DOCX/XLSX/PPTX to PDF
`POST`	`/v1/convert/image`	Generate thumbnail from a PDF page

Compression is not a standalone endpoint. Pass compress: "low" | "medium" | "high" on any endpoint that produces a PDF. See Compress a PDF for details.

Phase 3 — Extract

Method	Endpoint	Description
`POST`	`/v1/extract/text`	Extract text content from a PDF
`POST`	`/v1/extract/tables`	Extract structured table data
`POST`	`/v1/extract/ocr`	OCR a scanned PDF
`POST`	`/v1/extract/structured`	AI-powered structured extraction (invoice to JSON)

The full OpenAPI specification is available at https://api.pdfbase.dev/v1/openapi.json. All SDKs are auto-generated from this spec.

PDFs

Templates

Batches

Edit

Extract

Convert

API Reference

Base URL

Authentication

Credits

Request format

Response format

Resource IDs

Endpoint map

Phase 1 — Create (Launch)

Phase 2 — Edit + Convert

Phase 3 — Extract

​Base URL

​Authentication

​Credits

​Request format

​Response format

​Resource IDs

​Pagination

​Endpoint map

​Phase 1 — Create (Launch)

​Phase 2 — Edit + Convert

​Phase 3 — Extract

Base URL

Authentication

Credits

Request format

Response format

Resource IDs

Pagination

Endpoint map

Phase 1 — Create (Launch)

Phase 2 — Edit + Convert

Phase 3 — Extract