# Overview
> How the API turns templates, HTML, URLs and Markdown into PDFs and images, with the core concepts and conventions to know first.
Dynamic Document API is a REST API for generating PDFs and images. You send JSON data together with a stored template, raw HTML, a web page URL or Markdown, and the API returns the finished file, either directly in the response or through a signed webhook when the render is complete.
Typical documents are invoices, quotes, receipts, statements, certificates, tickets, shipping labels and reports. You can also convert existing web pages to PDF or take screenshots of them.
## How it works [#how-it-works]
1. **Build a template.** Write HTML and CSS with Jinja placeholders in the dashboard code editor at [https://app.dynamicdocumentapi.com](https://app.dynamicdocumentapi.com), or start from a template in the [gallery](/templates).
2. **Publish a version.** Publishing validates the template and creates an immutable version.
3. **Create a render.** Call `POST /v1/renders` with the template ID and your data.
4. **Receive the file.** Get a signed download URL, the raw file or base64 content. Long renders can run asynchronously and notify your server with a webhook.
```bash
curl https://api-eu.dynamicdocumentapi.com/v1/renders \
-H "Authorization: Bearer $DYNAMIC_DOCUMENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": { "type": "template", "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C" },
"data": { "number": "2026-0042", "customer": { "name": "Example GmbH" } },
"output": { "format": "pdf" }
}'
```
## Core concepts [#core-concepts]
### Templates and versions [#templates-and-versions]
A template stores a document's HTML, the contents of `` (usually CSS), header and footer, sample data and default output options. Templates use a Jinja-compatible [template language](/docs/template-language) with extra filters for currencies, dates, QR codes and barcodes.
Every template has one editable draft and a series of immutable published versions (`1`, `2`, `3`, …). Publishing checks the syntax, validates the sample data and runs a test render before it moves the `live` pointer to the new version. Renders use the `live` version unless you pin a version number, and a rollback moves the pointer back to an earlier version. Test keys can also render the draft.
Each template is pinned to an engine channel such as `2026.4`, which fixes the Chromium version and the bundled fonts. The same template version, data and engine channel produce visually identical output.
PDF templates are HTML, CSS and Jinja, edited visually or as code, or Markdown; image templates are designed in the canvas editor.
### Renders [#renders]
A render is one generation job. `POST /v1/renders` accepts four input types (`template`, `html`, `url` and `markdown`) and produces PDF, PNG, JPEG, WebP or HTML output. PDFs can be accessible as [PDF/UA](/docs/pdf-options#pdfua), archived as [PDF/A](/docs/pdf-options#pdfa) or carry an embedded [e-invoice](/docs/e-invoicing) (Factur-X, ZUGFeRD, XRechnung). [Batches](/docs/batches) render many documents in one request, and [PDF tools](/docs/pdf-tools) merge, split, protect and convert existing PDFs.
Each render has an ID (`rnd_…`), a status and a list of output files. Renders are synchronous by default: the response contains the result. With `mode: "async"` the API responds immediately and you poll the render or wait for a webhook. See [Renders](/docs/renders).
### Usage [#usage]
Usage is measured in renders. A PDF of up to 50 pages is 1 render, with 1 more for each additional 50 pages, and an image is 1 render. Test renders and failed renders are free. Plans include a monthly number of renders, and paid plans top up automatically with 1,000 renders when they run low, up to a monthly top-up limit that you control. See [Plans and limits](/docs/plans-and-limits).
### Test and live keys [#test-and-live-keys]
A workspace can have several API keys, each in test or live mode. Test keys (`dda_test_…`) render for free with a "TEST" watermark, keep files for 24 hours and still deliver webhooks. Live keys (`dda_live_…`) produce clean output and count as billed renders. See [Authentication and test mode](/docs/authentication).
### Data residency [#data-residency]
Render payloads and generated files are processed and stored in the EU (`https://api-eu.dynamicdocumentapi.com`).
### Files and retention [#files-and-retention]
Generated files are private. Download URLs are signed and expire after one hour by default, and files are deleted when your workspace's retention period ends. For sensitive documents, zero-retention delivery returns the file in the response without keeping a copy.
## API conventions [#api-conventions]
| Topic | Convention |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Base URL | `https://api-eu.dynamicdocumentapi.com/v1` (`https://api.dynamicdocumentapi.com/v1` is an alias) |
| Authentication | `Authorization: Bearer dda_live_…` |
| Request bodies | JSON with `Content-Type: application/json` |
| Errors | `application/problem+json` (RFC 9457) with a stable `code` field |
| IDs | Prefixed opaque strings such as `rnd_…`, `tpl_…` and `file_…` |
| Timestamps | RFC 3339 in UTC, for example `2026-09-17T15:06:33Z` |
| Booleans and enums | JSON booleans and lowercase strings |
| Lengths | CSS length strings with a unit, such as `"20mm"` or `"1in"` |
| Pagination | Cursor-based, with `limit` and `cursor` query parameters |
| Idempotency | `Idempotency-Key` header on POST requests; responses are replayed for 24 hours |
| Request IDs | `X-Request-Id` response header, also included in error bodies |
| Versioning | The major version is part of the path. Additive changes don't change it, and deprecations are announced at least 12 months ahead with `Deprecation` and `Sunset` headers |
## Next steps [#next-steps]
- [Quickstart](/docs/quickstart): Create a test key and render your first PDF in a few minutes.
- [Authentication and test mode](/docs/authentication): API keys, scopes, test mode, key rotation and API hosts.
- [Renders](/docs/renders): The render request, sync and async modes, delivery and idempotency.
- [Template language](/docs/template-language): Jinja syntax plus filters for money, dates, QR codes and barcodes.
- [PDF options](/docs/pdf-options): Paper sizes, margins, headers, metadata, PDF/UA, PDF/A, attachments, protection and wait strategies.
- [E-invoicing](/docs/e-invoicing): Factur-X, ZUGFeRD and XRechnung from one invoice model, with validation reports.
- [Batches](/docs/batches): Many documents from one template in a single request, as files, a ZIP or a merged PDF.
- [Your own storage](/docs/storage): Deliver rendered files to your own S3, Azure, Google Cloud or SFTP storage, with path templates and upload results.
- [PDF tools](/docs/pdf-tools): Merge, split, rotate, protect, unlock and read or set the metadata of existing PDFs.
- [Email delivery](/docs/email-delivery): Send rendered documents through your own email provider when a render succeeds.
- [Webhooks](/docs/webhooks): Signed event delivery, retries, replays and signature verification.
- [Errors](/docs/errors): Problem details and every error code with suggested fixes.
- [API reference](/docs/api-reference): Every endpoint, parameter and response schema.