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

# API overview

> POST /v1/render request body, success headers, and related endpoints.

Base URL: `https://spoolpdf-api.nandra.dev` (local Compose: `http://localhost:8080`).

Interactive playgrounds for each operation are in this tab. Auth for `/v1/render` is Bearer (`spool_live_…`).

## Endpoints

| Method | Path               | Auth                   | Success                       |
| ------ | ------------------ | ---------------------- | ----------------------------- |
| `POST` | `/v1/render`       | Bearer API key         | `application/pdf`             |
| `POST` | `/v1/trial/render` | None (IP rate-limited) | `application/pdf`             |
| `GET`  | `/healthz`         | None                   | `{ "ok": true }`              |
| `GET`  | `/readyz`          | None                   | `{ "ok": true, "checks": … }` |

## Render body

Exactly one of `html` or `url`. Optional fields:

| Field                                                               | Notes                                                                     |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `format`                                                            | A0–A6, Letter, Legal, Tabloid, Ledger, `{width}x{height}`, `{width}xauto` |
| `paper_width` / `paper_height`                                      | Must be set together                                                      |
| `landscape`, `print_background`, `scale`, `zoom`                    | `zoom` aliases `scale`                                                    |
| `margin`, `header`, `footer`                                        | Header/footer: page and total placeholders (double curly braces)          |
| `wait_delay`                                                        | Go duration, max 30s                                                      |
| `wait_for_selector`, `wait_for_expression`, `wait_for_network_idle` | SPA waits                                                                 |
| `extra_http_headers`                                                | No `Cookie` or hop-by-hop names                                           |
| `cookies`                                                           | `name`, `value`, `domain` required                                        |
| `sandbox`                                                           | Watermarked; does not increment usage                                     |
| `pages`                                                             | e.g. `1-3,6`; not with `single_page` / auto height                        |
| `single_page`                                                       | Implied by `{width}xauto`                                                 |
| `emulate_media`                                                     | `print` or `screen`                                                       |
| `css`, `javascript`                                                 | Inline or public URL (SSRF-checked)                                       |
| `raise_for_status`                                                  | `true` = fail 3xx/4xx/5xx; `false` = allow error pages                    |
| `auth`                                                              | HTTP Basic; not with `Authorization` header                               |
| `lazy_load_images`                                                  | Scroll so lazy images load                                                |
| `metadata`                                                          | `title`, `author`, `subject`, `keywords`                                  |

## Success headers

* `X-Request-Id` — always
* `X-Usage-Count` — authenticated render when the usage write succeeds (omitted for sandbox)
* `X-Sandbox` — `true` when `sandbox` was requested
* `X-Usage-Overage` — `true` when the monthly included quota is exceeded

OpenAPI source: `mintlify/openapi.yaml` (kept in sync with `docs/openapi.yaml`).