> ## Documentation Index
> Fetch the complete documentation index at: https://pdfbase.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete reference for every PDFBase endpoint.

## Base URL

```
https://api.pdfbase.dev/v1
```

All endpoints are versioned. The current version is `v1`.

## Authentication

All requests require a Bearer token:

```bash theme={null}
Authorization: Bearer pk_live_xxx
```

See [Authentication](/docs/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](/docs/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:

```json theme={null}
{
  "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:

```bash theme={null}
GET /v1/pdfs?limit=25&starting_after=pdf_x7Kf9m
```

```json theme={null}
{
  "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 |

<Note>
  Compression is not a standalone endpoint. Pass `compress: "low" | "medium" | "high"` on any endpoint that produces a PDF. See [Compress a PDF](/docs/api-reference/edit/compress) for details.
</Note>

### 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.