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

# POST /v1/generate/batch

> Submit multiple PDF generation jobs for async processing.

# Batch Generation

`POST https://api.getdeckle.dev/v1/generate/batch`

Submit up to 100 PDF generation jobs at once. Jobs are processed asynchronously via a background queue. Returns `202 Accepted` with a batch ID and individual generation IDs that you can poll for status.

## Request Headers

| Header | Required | Description |
| - | - | - |
| `Authorization` | Yes | `Bearer dk_live_sk_...` |
| `Content-Type` | Yes | `application/json` |
| `Idempotency-Key` | No | Unique key to prevent duplicate batch submissions. Cached for 24 hours. |

## Request Body

| Parameter | Type | Required | Description |
| - | - | - | - |
| `items` | object\[] | Yes | Array of generation jobs (1-100 items) |
| `webhook` | string | No | URL to POST when the final job in the batch completes |

### Item Object

Each item accepts the same parameters as a single `/v1/generate` call:

| Parameter | Type | Required | Description |
| - | - | - | - |
| `html` | string | \* | Raw HTML to convert to PDF |
| `react` | string | \* | JSX/TSX source code |
| `template` | string | \* | Template ID (`tmpl_xxx`) |
| `data` | object | No | Data to merge into template variables |
| `styles` | string | No | Additional CSS styles |
| `options` | object | No | PDF rendering options (format, margin, orientation, header, footer, printBackground) |
| `output` | string | No | `"url"` (default) or `"base64"` |

\* Each item must include at least one of `html`, `react`, or `template`.

### Options Object

| Parameter | Type | Default | Description |
| - | - | - | - |
| `format` | string or object | `"A4"` | `"A4"`, `"Letter"`, `"Legal"`, or `{ width, height }` |
| `margin` | string or object | — | Uniform margin string or `{ top, right, bottom, left }` |
| `orientation` | string | `"portrait"` | `"portrait"` or `"landscape"` |
| `header` | string | — | HTML for page header |
| `footer` | string | — | HTML for page footer |
| `printBackground` | boolean | — | Include background colors/images |

## Example

```bash theme={null}
curl -X POST https://api.getdeckle.dev/v1/generate/batch \
  -H "Authorization: Bearer dk_live_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: batch-invoice-run-2026-03" \
  -d '{
    "items": [
      {
        "template": "tmpl_abc123",
        "data": { "company": "Acme Corp", "total": 1500 }
      },
      {
        "template": "tmpl_abc123",
        "data": { "company": "Globex Inc", "total": 2300 }
      },
      {
        "html": "<h1>Custom Report</h1><p>Summary data here.</p>",
        "options": { "format": "Letter", "orientation": "landscape" }
      }
    ],
    "webhook": "https://example.com/webhooks/batch-complete"
  }'
```

## Response — `202 Accepted`

```json theme={null}
{
  "batch_id": "batch_a1b2c3d4e5f6g7h8",
  "total": 3,
  "generations": [
    { "id": "gen_abc123", "index": 0 },
    { "id": "gen_def456", "index": 1 },
    { "id": "gen_ghi789", "index": 2 }
  ],
  "status": "queued"
}
```

Use the individual generation IDs with `GET /v1/generations/:id` to check the status of each job.

## Idempotency

Pass an `Idempotency-Key` header with a unique string to safely retry failed requests. If a batch with the same key was already submitted within 24 hours, the original response is returned without creating duplicate jobs.

## Errors

| Status | Code | Description |
| - | - | - |
| 400 | `VALIDATION_ERROR` | Invalid items array (empty, over 100, or missing input) |
| 401 | `UNAUTHORIZED` | Invalid or missing API key |
| 403 | `USAGE_LIMIT_EXCEEDED` | Monthly PDF limit reached |
| 429 | `RATE_LIMITED` | Too many requests |
| 500 | `INTERNAL_ERROR` | Server error creating batch |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.