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

# Create a PDF

> Generate a PDF from HTML content, a URL, or raw markup.

## Phase

**Phase 1 (Launch)** — Core endpoint. Ships day one.

## Request

<ParamField body="html" type="string">
  HTML content to render as a PDF. Supports full CSS, JavaScript, web fonts, SVG, Canvas — anything Chromium renders. Mutually exclusive with `url`.
</ParamField>

<ParamField body="url" type="string">
  URL of a page to render as PDF. PDFBase loads the page in a headless Chromium browser and captures it. Mutually exclusive with `html`.
</ParamField>

<ParamField body="output" type="string" default="url">
  How to return the generated PDF.

  * `url` — Returns a signed download URL (recommended). File is stored for your plan's retention period.
  * `base64` — Returns the raw PDF as a base64-encoded string in the response body. Holds the rendering slot until transfer completes.
</ParamField>

<ParamField body="format" type="string" default="a4">
  Page size. One of: `a4`, `a3`, `a5`, `letter`, `legal`, `tabloid`, or a custom object.
</ParamField>

<ParamField body="custom_size" type="object">
  Custom page dimensions. Overrides `format`.

  * `width` (string) — e.g., `"210mm"`, `"8.5in"`, `"800px"`
  * `height` (string) — e.g., `"297mm"`, `"11in"`, `"1200px"`
</ParamField>

<ParamField body="margin" type="string | object" default="20mm">
  Page margins. Pass a string for uniform margins (`"20mm"`) or an object for per-side control:

  * `top` (string)
  * `right` (string)
  * `bottom` (string)
  * `left` (string)
</ParamField>

<ParamField body="landscape" type="boolean" default="false">
  Render in landscape orientation.
</ParamField>

<ParamField body="scale" type="number" default="1">
  Scale of the webpage rendering. Range: `0.1` to `2.0`.
</ParamField>

<ParamField body="header" type="object">
  Page header. Rendered on every page.

  * `html` (string) — HTML content for the header. Supports Chromium's special classes: `date`, `title`, `url`, `pageNumber`, `totalPages`.
  * `height` (string) — Header height, e.g., `"40mm"`.
</ParamField>

<ParamField body="footer" type="object">
  Page footer. Same structure as `header`.
</ParamField>

<ParamField body="wait_until" type="string" default="networkidle">
  When to consider the page "loaded" before capturing.

  * `load` — Wait for the `load` event.
  * `domcontentloaded` — Wait for `DOMContentLoaded`.
  * `networkidle` — Wait until no network requests for 500ms (recommended).
</ParamField>

<ParamField body="wait_for_selector" type="string">
  CSS selector to wait for before capturing. Useful when content loads dynamically.
</ParamField>

<ParamField body="wait_for_timeout" type="integer">
  Additional milliseconds to wait after `wait_until` fires. Max: 10000.
</ParamField>

<ParamField body="javascript" type="string">
  JavaScript to execute on the page before capturing. Runs after `wait_until` resolves.
</ParamField>

<ParamField body="resource_timeout" type="integer" default="10000">
  Max milliseconds to wait for each external resource (fonts, images, stylesheets). Resources that exceed this are skipped.
</ParamField>

<ParamField body="skip_failed_resources" type="boolean" default="true">
  Continue rendering even if some resources fail to load. When `false`, any failed resource causes the request to return an error.
</ParamField>

<ParamField body="compress" type="string" default="none">
  Compression level for the output PDF. One of: `none`, `low`, `medium`, `high`. Higher compression = smaller file, slightly slower.
</ParamField>

<ParamField body="watermark" type="object">
  Stamp a text watermark on the generated PDF. For watermarking existing PDFs, see [Add watermark](/docs/api-reference/edit/watermark) (Phase 2).

  * `text` (string, required) — The watermark text, e.g., "DRAFT", "CONFIDENTIAL".
  * `color` (string, default: "#00000020") — Color with alpha, hex format.
  * `rotation` (number, default: -45) — Rotation in degrees.
  * `position` (string, default: "center") — One of: `center`, `top-left`, `top-right`, `bottom-left`, `bottom-right`.
</ParamField>

<ParamField body="debug" type="boolean" default="false">
  Include a screenshot, console output, and failed resource list in the response. See [Debug Mode](/docs/guides/debug-mode).
</ParamField>

<ParamField body="timeout" type="integer" default="30000">
  Max milliseconds for the entire rendering operation. Range: `5000` to `120000`.
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value pairs stored with the PDF. Useful for linking PDFs to your internal records.

  ```json theme={null}
  { "order_id": "42", "customer": "acme-corp" }
  ```
</ParamField>

## Response

```json theme={null}
{
  "id": "pdf_x7Kf9m",
  "object": "pdf",
  "status": "completed",
  "url": "https://files.pdfbase.dev/pdf_x7Kf9m.pdf?token=sig_abc123",
  "pages": 3,
  "bytes": 142000,
  "format": "a4",
  "landscape": false,
  "compress": "none",
  "watermark": null,
  "metadata": {
    "order_id": "42",
    "customer": "acme-corp"
  },
  "created_at": "2026-05-19T10:30:00Z",
  "expires_at": "2026-05-20T10:30:00Z",
  "render_time_ms": 1240
}
```

<ResponseField name="id" type="string">
  Unique identifier, prefixed with `pdf_`.
</ResponseField>

<ResponseField name="object" type="string">
  Always `"pdf"`.
</ResponseField>

<ResponseField name="status" type="string">
  One of: `completed`, `completed_with_warnings`, `failed`.
</ResponseField>

<ResponseField name="url" type="string">
  Signed download URL. Expires at `expires_at`. Only present when `output: "url"`.
</ResponseField>

<ResponseField name="base64" type="string">
  Base64-encoded PDF content. Only present when `output: "base64"`.
</ResponseField>

<ResponseField name="pages" type="integer">
  Number of pages in the generated PDF.
</ResponseField>

<ResponseField name="bytes" type="integer">
  File size in bytes.
</ResponseField>

<ResponseField name="render_time_ms" type="integer">
  Time spent rendering, in milliseconds. Does not include queue wait time.
</ResponseField>

<ResponseField name="warnings" type="array">
  Present when `status` is `completed_with_warnings`. Each warning has `code`, `message`, and optionally `resource`.
</ResponseField>

<ResponseField name="debug" type="object">
  Present when `debug: true`. Contains `screenshot_url`, `console` array, and `failed_resources` array.
</ResponseField>

## Examples

### Minimal

```bash theme={null}
curl -X POST https://api.pdfbase.dev/v1/pdfs \
  -H "Authorization: Bearer pk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Hello</h1>"}'
```

### Full options

```bash theme={null}
curl -X POST https://api.pdfbase.dev/v1/pdfs \
  -H "Authorization: Bearer pk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-42-invoice" \
  -d '{
    "html": "<!DOCTYPE html><html>...</html>",
    "format": "a4",
    "margin": { "top": "25mm", "bottom": "25mm", "left": "15mm", "right": "15mm" },
    "header": {
      "html": "<div style=\"font-size:10px;text-align:right;\">Page <span class=\"pageNumber\"></span> of <span class=\"totalPages\"></span></div>",
      "height": "20mm"
    },
    "footer": {
      "html": "<div style=\"font-size:9px;text-align:center;color:#888;\">Generated by Acme Corp</div>",
      "height": "15mm"
    },
    "wait_until": "networkidle",
    "compress": "medium",
    "debug": true,
    "metadata": { "order_id": "42" },
    "output": "url"
  }'
```

### From URL

```bash theme={null}
curl -X POST https://api.pdfbase.dev/v1/pdfs \
  -H "Authorization: Bearer pk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/reports/monthly?token=abc",
    "wait_for_selector": "#report-ready",
    "format": "letter",
    "output": "url"
  }'
```