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

# Render a template

> Generate a PDF by merging a stored template with data.

## Phase

**Phase 1 (Launch)**

## Path parameters

<ParamField path="id" type="string" required>
  Template ID, e.g., `tpl_abc123`.
</ParamField>

## Request

<ParamField body="data" type="object" required>
  Data to merge into the template. Validated against the template's schema. Returns `422` if the data doesn't match.
</ParamField>

<ParamField body="output" type="string" default="url">
  `url` or `base64`. Same behavior as `POST /v1/pdfs`.
</ParamField>

<ParamField body="format" type="string">
  Override the template's default page format.
</ParamField>

<ParamField body="margin" type="string | object">
  Override the template's default margins.
</ParamField>

<ParamField body="landscape" type="boolean">
  Override the template's default orientation.
</ParamField>

<ParamField body="header" type="object">
  Override the template's default header.
</ParamField>

<ParamField body="footer" type="object">
  Override the template's default footer.
</ParamField>

<ParamField body="compress" type="string">
  Override the template's default compression.
</ParamField>

<ParamField body="debug" type="boolean" default="false">
  Include debug info in the response.
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary metadata attached to the generated PDF.
</ParamField>

<ParamField body="timeout" type="integer" default="30000">
  Max render time in milliseconds.
</ParamField>

## Response

Same shape as `POST /v1/pdfs` response, with an additional `template` field:

```json theme={null}
{
  "id": "pdf_rendered1",
  "object": "pdf",
  "status": "completed",
  "url": "https://files.pdfbase.dev/pdf_rendered1.pdf?token=sig_abc",
  "pages": 2,
  "bytes": 89000,
  "format": "a4",
  "template": {
    "id": "tpl_abc123",
    "name": "invoice",
    "version": 3
  },
  "metadata": {
    "order_id": "42"
  },
  "created_at": "2026-05-19T10:35:00Z",
  "expires_at": "2026-05-20T10:35:00Z",
  "render_time_ms": 890
}
```

<ResponseField name="template" type="object">
  Reference to the template used, including the exact `version` that was rendered. Useful for debugging when templates change.
</ResponseField>

## Schema validation errors

If the data doesn't match the template's schema:

```json theme={null}
{
  "error": {
    "type": "invalid_request",
    "code": "schema_validation_failed",
    "message": "Data does not match template schema.",
    "param": "data",
    "details": [
      { "field": "due_date", "error": "Expected type 'date', got 'number'." },
      { "field": "items", "error": "Required field missing." }
    ]
  }
}
```

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.pdfbase.dev/v1/templates/tpl_abc123/render \
    -H "Authorization: Bearer pk_live_xxx" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: order-42-invoice" \
    -d '{
      "data": {
        "number": "INV-042",
        "customer": "Acme Corp",
        "items": [
          { "name": "Widget Pro", "qty": 10, "price": "$50.00" },
          { "name": "Gadget Ultra", "qty": 5, "price": "$75.00" }
        ],
        "due_date": "2026-06-19",
        "total": "$875.00"
      },
      "compress": "high",
      "metadata": { "order_id": "42" },
      "output": "url"
    }'
  ```

  ```typescript TypeScript theme={null}
  const pdf = await pdfbase.templates.render('tpl_abc123', {
    data: {
      number: 'INV-042',
      customer: 'Acme Corp',
      items: [
        { name: 'Widget Pro', qty: 10, price: '$50.00' },
        { name: 'Gadget Ultra', qty: 5, price: '$75.00' },
      ],
      due_date: '2026-06-19',
      total: '$875.00',
    },
    compress: 'high',
    metadata: { order_id: '42' },
    output: 'url',
  })
  ```
</CodeGroup>