# Typefold

> Typefold renders PDF and Excel (XLSX) documents from HTML or from templates filled with JSON data, through an HTTP API with an API key, hosted or self-hosted. Studio is its web app for writing and previewing templates.

---

# AI coding agents

Source: https://docs.typefold.dev/start/ai-agents/

The Typefold Agent Skill gives a coding agent what it needs from these docs: which API to
call, the request fields, the client libraries, how to write templates, and the errors and
limits. The agent reads it when a task involves typefold.

To have an assistant render documents for you instead of writing code, connect it to the
[MCP server](/clients/ai-assistants/).

## 1. Download the skill

<a href="/downloads/typefold-skill.zip" download>Download typefold-skill.zip</a>. It holds
a `typefold` folder with `SKILL.md` and a `references` folder.

## 2. Add it to your agent

Unzip it where your agent loads skills from:

- **Claude Code:** into `.claude/skills/` in your project, so everyone working on it gets the
  skill, or into `~/.claude/skills/` for all your projects. See
  [Claude Code skills](https://code.claude.com/docs/en/skills).
- **Other agents** that support [Agent Skills](https://agentskills.io/): see where that agent
  loads skills from.

## 3. Give the agent your address and key

The skill's examples read the address and key from the `PDF_URL` and `API_KEY` environment
variables, as in the [quickstart](/start/quickstart/). Set them where the agent runs its
commands. The skill holds no keys or workspace data.

Then ask for what you need, such as "render our invoice template from the order service" or
"add a page footer with page numbers to the Invoice template".

## Keep it current

The skill matches these docs at the time you download it. Download it again after a new
Typefold release.

---

# How it works

Source: https://docs.typefold.dev/start/concepts/

## The parts

<figure class="diagram"><svg viewBox="0 0 720 200" role="img" aria-label="Your application calls the API with an API key, and Studio calls it when you are signed in. The API renders your documents and returns the PDF or XLSX file, or a download link to it."><defs><marker id="d-arch" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path class="head" d="M0 0L10 5L0 10z"/></marker></defs><rect class="box" x="20" y="20" width="180" height="56" rx="8"/><text class="title" x="110.0" y="53.0" text-anchor="middle">Your application</text><rect class="box" x="20" y="124" width="180" height="56" rx="8"/><text class="title" x="110.0" y="148.0" text-anchor="middle">Studio</text><text class="sub" x="110.0" y="166.0" text-anchor="middle">in the browser</text><rect class="box accent" x="300" y="50" width="200" height="100" rx="8"/><text class="title" x="400.0" y="94.0" text-anchor="middle">Typefold API</text><text class="sub" x="400.0" y="114.0" text-anchor="middle">templates, renders, keys</text><rect class="box" x="580" y="72" width="120" height="56" rx="8"/><text class="title" x="640.0" y="105.0" text-anchor="middle">PDF / XLSX</text><path class="line" d="M200 48H250V84H296" marker-end="url(#d-arch)"/><text class="label" x="225" y="40" text-anchor="middle">x-api-key</text><path class="line" d="M200 152H250V116H296" marker-end="url(#d-arch)"/><text class="label" x="225" y="172" text-anchor="middle">signed in</text><path class="line" d="M500 100H576" marker-end="url(#d-arch)"/><text class="label" x="538" y="90" text-anchor="middle">file or link</text></svg></figure>

- **API.** What your application and Studio talk to. It checks every request, stores your
  templates and renders your documents.
- **Studio.** The web app for writing templates and managing the workspace. It uses the same
  API as your application.

## Workspaces

A **workspace** owns everything you create: templates, files, renders, API keys and webhooks.
Nothing is shared between workspaces. An API key works only in the workspace it was created in,
and Studio shows the workspace you have selected.

People join a workspace as an `owner`, `admin` or `member`. Owners and admins manage keys,
webhooks and teammates; see [roles](/clients/http/#roles).

## API keys and scopes

Applications prove who they are with an **API key**, a secret sent in the `x-api-key` header
of every request. Owners and admins create keys in Studio under **Manage → API keys**. Each key
has **scopes**, such as `render:create` or `template:publish`, that decide what it may do. Give
each key only the scopes its application needs. The full list, expiry and rotation are in
[API keys, scopes and roles](/clients/http/#api-keys).

## Templates, drafts and versions

A **template** is a reusable document: HTML with [Handlebars](https://handlebarsjs.com/guide/)
placeholders, page settings, and the files it uses. You edit its **draft** and preview it in
Studio. Publishing freezes the draft, and every file it uses, into a numbered **version**. Later
edits never change a published version. See [how templates work](/templates/overview/).

## Two ways to render

- **[Reports API](/guides/reports/).** Send a template's name and your data. The response is the
  PDF or XLSX file, rendered from the newest published version.
- **[Renders API](/guides/rendering/).** Create a render job from one specific template version
  or from your own HTML, and get a PDF. Each render has an ID and moves from `queued` to
  `processing`, then ends `succeeded`, `failed` or `cancelled`. Wait for it in the request, poll
  it, or receive a [webhook](/guides/webhooks/). [Batches](/guides/batch-rendering/) and
  cancelling are only here. See [render states](/guides/rendering/#render-states).

## Next steps

- [Quickstart](/start/quickstart/): render your first PDF.
- [Limits](/clients/limits/): every size, time and rate limit in one place.

---

# Introduction

Source: https://docs.typefold.dev/start/introduction/

Typefold turns HTML, or a template plus JSON data, into PDF and Excel files. Your
application calls its HTTP API with an API key and gets the finished file in the response or
from a background render. Your team writes and previews templates in **Studio**, a web app that
also manages API keys, teammates and webhooks.

## What it is good for

Documents your application produces again and again from data:

- Invoices, receipts and e-invoices with an embedded XML file.
- Statements and reports, as a PDF or as a real `.xlsx` workbook.
- Tickets, certificates, labels and letters.
- Archival and accessible PDFs (PDF/A and PDF/UA).
- Short email and SMS texts, written in the same template language.

It is a poor fit for turning arbitrary web pages into PDFs: it is not a browser, so it does not
run the page's JavaScript and supports its own set of CSS. See
[supported CSS](/templates/css-support/) and [what is not supported](/start/not-supported/).

## Hosted or self-hosted

The API, Studio and templates work the same in both.

- **Hosted.** Sign in to Studio, create a workspace and an API key. Nothing to install.
- **Self-hosted.** Run Typefold on your own server, so documents and templates never leave
  your network. It needs a [license key](/self-hosting/licensing/) to render. See
  [install](/self-hosting/install/).

## Where to go next

- **Trying it out?** The [quickstart](/start/quickstart/) takes you from an API key to a
  downloaded PDF.
- **Want the big picture?** [How it works](/start/concepts/) explains workspaces, API keys,
  templates and renders.
- **Integrating an application?** Render a template by name with the
  [Reports API](/guides/reports/), or run background render jobs and
  [batches](/guides/batch-rendering/) with the [Renders API](/guides/rendering/). Call the [HTTP API](/clients/http/) directly, or use the
  [.NET](/clients/dotnet/), [Python](/clients/python/) or [TypeScript](/clients/typescript/)
  client.
- **Writing templates?** [Build your first template](/guides/first-template/) in Studio.
- **Running your own server?** Start with [install](/self-hosting/install/).

---

# What's not supported

Source: https://docs.typefold.dev/start/not-supported/

Each item below says what to use instead. CSS that is ignored or fails is listed on
[Supported CSS](/templates/css-support/).

## Filling in an uploaded PDF's form fields

A template can add the pages of a PDF file you upload, or draw onto them, but it cannot type
into the file's own fillable fields.

**Instead:** draw your template onto the form page by page, placing each value where its box
is; see [fill in a supplier's form](/features/combine-templates/#fill-in-a-suppliers-form).

## Uploaded PDF files in PDF/A or PDF/UA documents

A PDF/A or PDF/UA document cannot add an uploaded PDF file, because nothing checks that the file
meets the standard.

**Instead:** rebuild that part as a template and
[combine templates](/features/combine-templates/), or turn the standard off for that template.

## JavaScript in the document

The renderer does not run JavaScript in the HTML. `<script>` elements and event handlers do
nothing, so a chart or table drawn by a JavaScript library does not appear.

**Instead:** produce the final markup before rendering. Reshape data in a `beforeRender` script
and format values with helpers; see [Handlebars templates](/templates/handlebars/). Draw charts
as PNG or SVG images in your application and send or upload them as
[images](/templates/css-support/#images). For Excel output, use [Excel charts](/features/charts/).

## `afterRender` scripts

Only `beforeRender` runs. A script that defines `afterRender` is refused with
`400 UNSUPPORTED_FEATURE`.

**Instead:** move the work into `beforeRender`, or process the downloaded file in your
application.

## Network access from templates

Helpers and scripts cannot reach the network or a file system, so a template cannot fetch data
from an API. Fonts, images and stylesheets at `http://` or `https://` URLs are not loaded.

**Instead:** send all data in the render request. Upload fonts, images and stylesheets to the
workspace (see [templates](/templates/overview/)), or send images in your data as `data:` URLs.

## Your own JavaScript or JSX components

The API does not run JavaScript or JSX that you upload to build a document.

**Instead:** build the layout in your own code and send it to the
[Renders API](/guides/rendering/) as HTML or as a node document, or describe it as a
[component template](/templates/components/).

## Partials, translations and scripts in string renders

A [string render](/guides/string-rendering/) with the `handlebars` engine runs the `helpers` you
send, but has no partials, translation files or scripts.

**Instead:** put the text in a [Handlebars template](/templates/handlebars/), which has all
three.

## Calling the API from a browser on another site

The API sends no CORS headers, so browser code on another origin cannot call it.

**Instead:** call the API from your server. To hand a finished
[Renders API](/guides/rendering/) PDF to a browser, pass it the render's short-lived
`downloadUrl`.

---

# Quickstart

Source: https://docs.typefold.dev/start/quickstart/

Create an API key, render a PDF from a line of HTML, then render a template by its name.

## Before you start

You need two things:

1. **A Studio sign-in as a workspace owner or admin.** Studio is on the hosted service or on an
   installation your company runs. Only owners and admins can create API keys; if you are a
   member, ask one for a key with the permissions in step 1.
2. **[curl](https://curl.se/) or a client library.** The curl examples are for bash or zsh. To
   use the [.NET](/clients/dotnet/), [TypeScript and JavaScript](/clients/typescript/) or
   [Python](/clients/python/) client instead, install it as its page shows and pick its tab.

Save the address you open Studio at in `PDF_URL`. The API answers at the same address:

```sh
export PDF_URL='https://pdf.example.com'
```

## 1. Create an API key

1. Sign in to Studio and open your workspace.
2. Go to **Manage → API keys** and select **Create API key**.
3. Enter a **Key name**, such as `Quickstart`. Under **Permissions**, keep `render:create` and
   `render:read` ticked and also tick `template:read`.
4. Select **Create API key** and copy the secret. It is shown only once.

Keep the secret in an environment variable for the next steps:

```sh
export API_KEY='paste-the-secret-here'
```

What each permission allows is listed in [API keys, scopes and roles](/clients/http/#api-keys).

## 2. Render some HTML

Send a line of HTML with A4 paper size and 15 mm margins, and save the PDF as `invoice.pdf`:

<Tabs syncKey="api-client">
<TabItem label="curl">

`waitMs` asks the API to wait up to 10 seconds for the PDF:

```sh
curl $PDF_URL/v1/renders \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "document": {
      "kind": "html",
      "html": "<h1>Invoice 42</h1><p>Thank you for your order.</p>"
    },
    "settings": {
      "pageSize": { "widthMm": 210, "heightMm": 297 },
      "margins": { "topMm": 15, "rightMm": 15, "bottomMm": 15, "leftMm": 15 }
    },
    "waitMs": 10000
  }'
```

The response is the render. When its `state` is `succeeded`, download the PDF from
`result.downloadUrl`, which works without the API key for five minutes. If it is still `queued`
or `processing`, see [get the finished file](/guides/rendering/#3-get-the-finished-file).

```sh
curl -o invoice.pdf "PASTE-THE-downloadUrl-HERE"
```

</TabItem>
<TabItem label=".NET">

```csharp
using Typefold.Client;

var client = new TypefoldClient(
    new Uri(Environment.GetEnvironmentVariable("PDF_URL")!),
    Environment.GetEnvironmentVariable("API_KEY")!);

byte[] pdf = await client.RenderAsync(new DirectRenderRequest
{
    Document = new HtmlDocument { Html = "<h1>Invoice 42</h1><p>Thank you for your order.</p>" },
    Settings = new RenderSettings
    {
        PageSize = PageSize.A4,
        Margins = new Margins { TopMm = 15, RightMm = 15, BottomMm = 15, LeftMm = 15 },
    },
});

await File.WriteAllBytesAsync("invoice.pdf", pdf);
```

</TabItem>
<TabItem label="TypeScript">

```ts
import { writeFile } from "node:fs/promises";
import { PageSize, TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL!,
  apiKey: process.env.API_KEY!,
});

const pdf = await client.render({
  document: { html: "<h1>Invoice 42</h1><p>Thank you for your order.</p>" },
  settings: {
    pageSize: PageSize.A4,
    margins: { topMm: 15, rightMm: 15, bottomMm: 15, leftMm: 15 },
  },
});

await writeFile("invoice.pdf", pdf);
```

</TabItem>
<TabItem label="JavaScript">

```js
import { writeFile } from "node:fs/promises";
import { PageSize, TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL,
  apiKey: process.env.API_KEY,
});

const pdf = await client.render({
  document: { html: "<h1>Invoice 42</h1><p>Thank you for your order.</p>" },
  settings: {
    pageSize: PageSize.A4,
    margins: { topMm: 15, rightMm: 15, bottomMm: 15, leftMm: 15 },
  },
});

await writeFile("invoice.pdf", pdf);
```

</TabItem>
<TabItem label="Python">

```python
import os
from pathlib import Path

from typefold import (
    DirectRenderRequest,
    HtmlDocument,
    Margins,
    PageSize,
    TypefoldClient,
    RenderSettings,
)

client = TypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"])

pdf = client.render(
    DirectRenderRequest(
        document=HtmlDocument(html="<h1>Invoice 42</h1><p>Thank you for your order.</p>"),
        settings=RenderSettings(
            page_size=PageSize.A4,
            margins=Margins(top_mm=15, right_mm=15, bottom_mm=15, left_mm=15),
        ),
    )
)

Path("invoice.pdf").write_bytes(pdf)
```

</TabItem>
</Tabs>

Open `invoice.pdf`: you should see a one-page A4 document with the heading "Invoice 42".

## 3. Render a template by name

Most applications keep the layout in a **template**, a reusable document stored in Studio, and
send only data. First create and publish the template:

1. In the sidebar, open **Workspace → Editor**. The editor opens in a new browser tab. Click
   **+**, then **New entity → Template**.
2. Enter the **Template name** `Quickstart invoice`, leave **Start with** on **Blank template**
   and click **Create template**. The editor opens the template's `template.html`.
3. Replace its contents with:

   ```handlebars
   <h1>Invoice {{number}}</h1>
   <p>Bill to {{customer}}</p>
   <table>
     {{#each lines}}
       <tr><td>{{item}}</td><td>{{amount}}</td></tr>
     {{/each}}
   </table>
   ```

   The placeholders use [Handlebars](https://handlebarsjs.com/guide/) syntax.

4. Click **Save**, then **Publish**. Publishing makes the template available to the API.

Now render it by name with the Reports API. It returns the PDF itself, saved here as
`quickstart-invoice.pdf`:

<Tabs syncKey="api-client">
<TabItem label="curl">

```sh
curl $PDF_URL/v1/reports/render \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "format": "pdf",
    "template": { "name": "Quickstart invoice" },
    "data": {
      "number": "2026-0042",
      "customer": "Acme Ltd",
      "lines": [
        { "item": "Consulting", "amount": "1,200.00" },
        { "item": "Travel", "amount": "180.00" }
      ]
    }
  }' \
  -o quickstart-invoice.pdf
```

</TabItem>
<TabItem label=".NET">

```csharp
using Typefold.Client;

var client = new TypefoldClient(
    new Uri(Environment.GetEnvironmentVariable("PDF_URL")!),
    Environment.GetEnvironmentVariable("API_KEY")!);

byte[] pdf = await client.RenderReportAsync(new RenderReportRequest
{
    Template = TemplateRef.ByName("Quickstart invoice"),
    Data = new
    {
        number = "2026-0042",
        customer = "Acme Ltd",
        lines = new[]
        {
            new { item = "Consulting", amount = "1,200.00" },
            new { item = "Travel", amount = "180.00" },
        },
    },
});

await File.WriteAllBytesAsync("quickstart-invoice.pdf", pdf);
```

</TabItem>
<TabItem label="TypeScript">

```ts
import { writeFile } from "node:fs/promises";
import { TypefoldClient, TemplateRef } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL!,
  apiKey: process.env.API_KEY!,
});

const pdf = await client.renderReport({
  template: TemplateRef.byName("Quickstart invoice"),
  data: {
    number: "2026-0042",
    customer: "Acme Ltd",
    lines: [
      { item: "Consulting", amount: "1,200.00" },
      { item: "Travel", amount: "180.00" },
    ],
  },
});

await writeFile("quickstart-invoice.pdf", pdf);
```

</TabItem>
<TabItem label="JavaScript">

```js
import { writeFile } from "node:fs/promises";
import { TypefoldClient, TemplateRef } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL,
  apiKey: process.env.API_KEY,
});

const pdf = await client.renderReport({
  template: TemplateRef.byName("Quickstart invoice"),
  data: {
    number: "2026-0042",
    customer: "Acme Ltd",
    lines: [
      { item: "Consulting", amount: "1,200.00" },
      { item: "Travel", amount: "180.00" },
    ],
  },
});

await writeFile("quickstart-invoice.pdf", pdf);
```

</TabItem>
<TabItem label="Python">

```python
import os
from pathlib import Path

from typefold import TypefoldClient, RenderReportRequest, TemplateRef

client = TypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"])

pdf = client.render_report(
    RenderReportRequest(
        template=TemplateRef.by_name("Quickstart invoice"),
        data={
            "number": "2026-0042",
            "customer": "Acme Ltd",
            "lines": [
                {"item": "Consulting", "amount": "1,200.00"},
                {"item": "Travel", "amount": "180.00"},
            ],
        },
    )
)

Path("quickstart-invoice.pdf").write_bytes(pdf)
```

</TabItem>
</Tabs>

Open `quickstart-invoice.pdf`. You should see "Invoice 2026-0042", "Bill to Acme Ltd" and a
two-row table.

:::tip[Something went wrong?]
`401` means the key is missing or wrong. `403` means the key lacks a permission (the message
says what it cannot do) or, on a self-hosted installation, that its license is missing or not
valid.
`404` on the last step means no template with that name is published yet. Every code is
explained in [errors](/clients/http/#errors).
:::

## Next steps

- [How it works](/start/concepts/): workspaces, API keys, templates and renders.
- [Build your first template](/guides/first-template/): sample data and live preview in Studio.
- [Reports API](/guides/reports/) and [Renders API](/guides/rendering/): the two ways to render
  from your app, and when to use each.

---

# Render many documents at once

Source: https://docs.typefold.dev/guides/batch-rendering/

A batch creates up to 100 PDFs with one request, such as a month's invoices or every ticket of a
booking. You can download each document on its own, or all of them as one combined PDF.

Each item is an ordinary [Renders API](/guides/rendering/) render with its own ID, state, PDF,
webhook events and retention. The batch is created whole or not at all: if any item is invalid,
nothing is created. The [Reports API](/guides/reports/) has no batches.

## Before you start

- An API key with `render:create` and `render:read`, and curl or a client library set up as in
  the [quickstart](/start/quickstart/).
- The version ID of a published template; see
  [render a specific template version](/guides/rendering/#1-render-a-specific-template-version).

## 1. Create the batch

Send the renders as `items` to `POST /v1/renders/batch`. An item can be anything a single
[`POST /v1/renders`](/guides/rendering/) request takes (a template version, your own HTML or a
preview), except `waitMs`, and one batch can mix them. Each item can name its own
[storage destination](/guides/storage-destinations/):

<Tabs syncKey="api-client">
<TabItem label="curl">

```sh
curl -X POST "$PDF_URL/v1/renders/batch" \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: invoices-2026-09" \
  -d '{
    "items": [
      { "templateVersionId": "c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d", "data": { "invoice": { "number": "INV-2041" } } },
      { "templateVersionId": "c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d", "data": { "invoice": { "number": "INV-2042" } } }
    ]
  }'
```

</TabItem>
<TabItem label=".NET">

```csharp
using Typefold.Client;

var client = new TypefoldClient(
    new Uri(Environment.GetEnvironmentVariable("PDF_URL")!),
    Environment.GetEnvironmentVariable("API_KEY")!);

RenderBatch batch = await client.CreateBatchAsync(
    new[]
    {
        new TemplateVersionRenderRequest
        {
            TemplateVersionId = "c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
            Data = new { invoice = new { number = "INV-2041" } },
        },
        new TemplateVersionRenderRequest
        {
            TemplateVersionId = "c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
            Data = new { invoice = new { number = "INV-2042" } },
        },
    },
    idempotencyKey: "invoices-2026-09");

Console.WriteLine(batch.Id);
```

</TabItem>
<TabItem label="TypeScript">

```ts
import { TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL!,
  apiKey: process.env.API_KEY!,
});

const batch = await client.createBatch(
  [
    {
      templateVersionId: "c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
      data: { invoice: { number: "INV-2041" } },
    },
    {
      templateVersionId: "c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
      data: { invoice: { number: "INV-2042" } },
    },
  ],
  { idempotencyKey: "invoices-2026-09" },
);

console.log(batch.id);
```

</TabItem>
<TabItem label="JavaScript">

```js
import { TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL,
  apiKey: process.env.API_KEY,
});

const batch = await client.createBatch(
  [
    {
      templateVersionId: "c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
      data: { invoice: { number: "INV-2041" } },
    },
    {
      templateVersionId: "c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
      data: { invoice: { number: "INV-2042" } },
    },
  ],
  { idempotencyKey: "invoices-2026-09" },
);

console.log(batch.id);
```

</TabItem>
<TabItem label="Python">

```python
import os

from typefold import TypefoldClient, TemplateVersionRenderRequest

client = TypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"])

batch = client.create_batch(
    [
        TemplateVersionRenderRequest(
            template_version_id="c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
            data={"invoice": {"number": "INV-2041"}},
        ),
        TemplateVersionRenderRequest(
            template_version_id="c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
            data={"invoice": {"number": "INV-2042"}},
        ),
    ],
    idempotency_key="invoices-2026-09",
)

print(batch.id)
```

</TabItem>
</Tabs>

The request answers `202` at once with the batch summary; it never waits for the PDFs. Keep its
`id`:

```json
{
  "id": "4d3c2b1a-0f9e-4d8c-b7a6-5f4e3d2c1b0a",
  "createdAt": "2026-10-08T09:30:00.120Z",
  "total": 2,
  "counts": {
    "queued": 2,
    "processing": 0,
    "succeeded": 0,
    "failed": 0,
    "cancelled": 0
  },
  "items": [
    {
      "index": 0,
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "state": "queued",
      "templateVersionId": "c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
      "test": false,
      "createdAt": "2026-10-08T09:30:00.120Z",
      "updatedAt": "2026-10-08T09:30:00.120Z"
    },
    {
      "index": 1,
      "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
      "state": "queued",
      "templateVersionId": "c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
      "test": false,
      "createdAt": "2026-10-08T09:30:00.120Z",
      "updatedAt": "2026-10-08T09:30:00.120Z"
    }
  ]
}
```

- `items` are in the order you sent them. `index` is the position in your request, from 0, and
  `id` is that item's render ID. `templateVersionId` appears only on template version items.
- The summary has no download links or error details. Read the item's render for those.
- `total` counts the items still kept. Items deleted by
  [retention](/guides/rendering/#retention) leave the batch.
- All fields: `createRenderBatch` in the [API reference](/reference/api/).

The `Idempotency-Key` makes it safe to send the batch again after a network error: the same key
and body return the first batch's current summary instead of a second batch. Batch keys are
separate from single-render keys; the rest of the rules are under
[idempotency keys](/guides/rendering/#idempotency-keys).

## 2. Wait for the items to finish

If you use [webhooks](/guides/webhooks/), each item sends its own event when it ends; there is no
event for the batch as a whole. Match the event's render ID to the item IDs from step 1.

Otherwise, read the summary every few seconds until `counts.queued` and `counts.processing` are
both 0. The clients' wait method does this for you. It gives up with `RENDER_TIMEOUT` after 10
minutes unless you pass a longer timeout:

<Tabs syncKey="api-client">
<TabItem label="curl">

```sh
curl "$PDF_URL/v1/renders/batch/4d3c2b1a-0f9e-4d8c-b7a6-5f4e3d2c1b0a" \
  -H "x-api-key: $API_KEY"
```

</TabItem>
<TabItem label=".NET">

```csharp
using Typefold.Client;

var client = new TypefoldClient(
    new Uri(Environment.GetEnvironmentVariable("PDF_URL")!),
    Environment.GetEnvironmentVariable("API_KEY")!);

RenderBatch batch = await client.GetBatchAsync("4d3c2b1a-0f9e-4d8c-b7a6-5f4e3d2c1b0a");
batch = await client.WaitForBatchAsync(batch);

Console.WriteLine($"{batch.Counts.Succeeded} succeeded, {batch.Counts.Failed} failed");
```

</TabItem>
<TabItem label="TypeScript">

```ts
import { TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL!,
  apiKey: process.env.API_KEY!,
});

let batch = await client.getBatch("4d3c2b1a-0f9e-4d8c-b7a6-5f4e3d2c1b0a");
batch = await client.waitForBatch(batch);

console.log(`${batch.counts.succeeded} succeeded, ${batch.counts.failed} failed`);
```

</TabItem>
<TabItem label="JavaScript">

```js
import { TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL,
  apiKey: process.env.API_KEY,
});

let batch = await client.getBatch("4d3c2b1a-0f9e-4d8c-b7a6-5f4e3d2c1b0a");
batch = await client.waitForBatch(batch);

console.log(`${batch.counts.succeeded} succeeded, ${batch.counts.failed} failed`);
```

</TabItem>
<TabItem label="Python">

```python
import os

from typefold import TypefoldClient

client = TypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"])

batch = client.get_batch("4d3c2b1a-0f9e-4d8c-b7a6-5f4e3d2c1b0a")
batch = client.wait_for_batch(batch)

print(f"{batch.counts.succeeded} succeeded, {batch.counts.failed} failed")
```

</TabItem>
</Tabs>

One failed item does not stop the others. A limit hit while rendering, such as the page count,
fails only that item.

## 3. Download each document

Each item is a single render, so download the ones that succeeded by their render ID. To see why
an item failed, read its render the same way:

<Tabs syncKey="api-client">
<TabItem label="curl">

Read each item by its render `id` and download it as a single render; see
[download the PDF](/guides/rendering/#download-the-pdf).

</TabItem>
<TabItem label=".NET">

```csharp
using Typefold.Client;

var client = new TypefoldClient(
    new Uri(Environment.GetEnvironmentVariable("PDF_URL")!),
    Environment.GetEnvironmentVariable("API_KEY")!);

RenderBatch batch = await client.GetBatchAsync("4d3c2b1a-0f9e-4d8c-b7a6-5f4e3d2c1b0a");

foreach (var item in batch.Items.Where(item => item.State == RenderState.Succeeded))
{
    Render render = await client.GetRenderAsync(item.Id);
    await File.WriteAllBytesAsync($"invoice-{item.Index}.pdf", await client.DownloadAsync(render));
}
```

</TabItem>
<TabItem label="TypeScript">

```ts
import { writeFile } from "node:fs/promises";
import { TypefoldClient, RenderState } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL!,
  apiKey: process.env.API_KEY!,
});

const batch = await client.getBatch("4d3c2b1a-0f9e-4d8c-b7a6-5f4e3d2c1b0a");

for (const item of batch.items) {
  if (item.state === RenderState.Succeeded) {
    const render = await client.getRender(item.id);
    await writeFile(`invoice-${item.index}.pdf`, await client.download(render));
  }
}
```

</TabItem>
<TabItem label="JavaScript">

```js
import { writeFile } from "node:fs/promises";
import { TypefoldClient, RenderState } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL,
  apiKey: process.env.API_KEY,
});

const batch = await client.getBatch("4d3c2b1a-0f9e-4d8c-b7a6-5f4e3d2c1b0a");

for (const item of batch.items) {
  if (item.state === RenderState.Succeeded) {
    const render = await client.getRender(item.id);
    await writeFile(`invoice-${item.index}.pdf`, await client.download(render));
  }
}
```

</TabItem>
<TabItem label="Python">

```python
import os
from pathlib import Path

from typefold import TypefoldClient, RenderState

client = TypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"])

batch = client.get_batch("4d3c2b1a-0f9e-4d8c-b7a6-5f4e3d2c1b0a")

for item in batch.items:
    if item.state == RenderState.SUCCEEDED:
        render = client.get_render(item.id)
        Path(f"invoice-{item.index}.pdf").write_bytes(client.download(render))
```

</TabItem>
</Tabs>

A batch has no cancel call of its own. To cancel an item, cancel its render by ID; see
[cancel a render](/guides/rendering/#cancel-a-render).

## Download one combined PDF

To give someone every document in one file, for example all the tickets of a booking, download
the combined PDF once every item has succeeded:

<Tabs syncKey="api-client">
<TabItem label="curl">

```sh
curl "$PDF_URL/v1/renders/batch/4d3c2b1a-0f9e-4d8c-b7a6-5f4e3d2c1b0a/pdf" \
  -H "x-api-key: $API_KEY" \
  -o booking.pdf
```

</TabItem>
<TabItem label=".NET">

```csharp
using Typefold.Client;

var client = new TypefoldClient(
    new Uri(Environment.GetEnvironmentVariable("PDF_URL")!),
    Environment.GetEnvironmentVariable("API_KEY")!);

byte[] pdf = await client.DownloadBatchAsync("4d3c2b1a-0f9e-4d8c-b7a6-5f4e3d2c1b0a");

await File.WriteAllBytesAsync("booking.pdf", pdf);
```

</TabItem>
<TabItem label="TypeScript">

```ts
import { writeFile } from "node:fs/promises";
import { TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL!,
  apiKey: process.env.API_KEY!,
});

const pdf = await client.downloadBatch("4d3c2b1a-0f9e-4d8c-b7a6-5f4e3d2c1b0a");

await writeFile("booking.pdf", pdf);
```

</TabItem>
<TabItem label="JavaScript">

```js
import { writeFile } from "node:fs/promises";
import { TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL,
  apiKey: process.env.API_KEY,
});

const pdf = await client.downloadBatch("4d3c2b1a-0f9e-4d8c-b7a6-5f4e3d2c1b0a");

await writeFile("booking.pdf", pdf);
```

</TabItem>
<TabItem label="Python">

```python
import os
from pathlib import Path

from typefold import TypefoldClient

client = TypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"])

pdf = client.download_batch("4d3c2b1a-0f9e-4d8c-b7a6-5f4e3d2c1b0a")

Path("booking.pdf").write_bytes(pdf)
```

</TabItem>
</Tabs>

Pages come in item order, and each page keeps its own paper size, fonts, images and links. The
file's title, author, subject, keywords and creator come from the first item. Bookmarks and files
attached to items are left out.

The file is put together on each request and not stored, so download it while the items are
still kept (see [retention](/guides/rendering/#retention)). When it can't be made, the error says
why:

| Situation                              | Answer                                                                                                              |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| An item is still queued or processing  | `409 CONFLICT`, `retryable: true`. Ask again later.                                                                 |
| An item failed or was cancelled        | `409 CONFLICT`, `retryable: false`, naming the first one.                                                           |
| An item is an image                    | `400 BAD_REQUEST`, naming the first one.                                                                            |
| An item is PDF/A or PDF/UA             | `400 UNSUPPORTED_FEATURE`. Only plain PDFs can be joined.                                                           |
| An item has a password or is signed    | `400 UNSUPPORTED_FEATURE`. Only plain PDFs can be joined.                                                           |
| An item kept no copy                   | `409 CONFLICT`, naming the first one. Its PDF is only in your [bucket](/guides/storage-destinations/#keep-no-copy). |
| The items' PDFs are too large together | `400 LIMIT_EXCEEDED`. Split into smaller batches.                                                                   |

## If the batch is refused

Nothing was created. Fix the cause, then send the batch again:

- **The message starts with `Batch item 7:`**: item 7 (counting from 0) can't be used, for
  example because its template version doesn't exist. Fix that item.
- **`429 RATE_LIMITED`**: the batch doesn't fit your workspace's render allowances right now.
  Wait the seconds in `Retry-After`.
- **`400 LIMIT_EXCEEDED`**: the batch can never fit. Either it has more items than your
  workspace's **Outstanding renders** or **Renders per minute** (Studio: **Manage → Render
  limits**; 10 outstanding by default), or its items' input is too large together. Split it into
  smaller batches.
- Items with `"test": true` are [test renders](/guides/rendering/#test-renders): they are admitted
  against the test allowance of 10, apart from the batch's other items.
- **`413 LIMIT_EXCEEDED`**: the request body is too large. Split it into smaller batches.

Items that render a published template version use far less of a batch's input limit than items
with your own HTML, because their fonts and images are not copied into each item. Prefer them for
large runs. Every size and count is in [limits](/clients/limits/).

## Next steps

- [Get notified with webhooks](/guides/webhooks/): one event per item.
- [HTTP API](/clients/http/): error codes and what to do about them.
- [API reference](/reference/api/): every batch field.

---

# Deploy across environments

Source: https://docs.typefold.dev/guides/environments/

If you keep separate installations or workspaces for test, staging and production, each has its
own templates. Copy tested templates from one to another by hand in Studio, or in your release
pipeline.

An export holds each template's current draft and the current workspace files, not the published
versions. Export when the drafts in the source environment are the ones you tested.

## By hand in Studio

1. In the source environment, open **Workspace → Editor** in Studio and choose
   **+ → Export workspace** next to the **Files** heading. You get a zip file. To copy one folder,
   choose **Export folder** in that folder's **…** menu instead. Files at the workspace root are
   only in a workspace export.
2. In the target environment, choose **+ → Import…** in the editor, drop the zip in, and click
   **Import workspace** (or **Import folder**). New templates and files are added; existing ones
   are updated.
3. Check the imported templates, then publish them. Until you do, documents still render with the
   previous versions.

## In your release pipeline

Your build exports the templates once, and each deployment imports them, so every environment
gets the templates that were tested with the release.

### 1. Give the pipeline an API key per environment

In Studio, open **Manage → API keys** in each environment, click **Create API key**, and give it
the permissions `template:read`, `template:write`, `template:publish` and `asset:manage`. Store
each key in your pipeline's secret store.

On a self-hosted installation you can instead set a deploy key in `.env` with `DEPLOY_API_KEY`
and `DEPLOY_WORKSPACE`, so no one has to open Studio; see
[the deploy key](/self-hosting/users/#the-deploy-key).

### 2. Export in the build

Run this in your build, with `PDF_URL` and `API_KEY` set to the test environment's address and
key:

```sh
curl -fo templates.zip "$PDF_URL/v1/workspace/export" \
  -H "x-api-key: $API_KEY"
```

Keep `templates.zip` with the release's build output, so every deployment of that release imports
the same file.

### 3. Import in each deployment

Run this in each deployment, with `PDF_URL` and `API_KEY` set to that environment's address and
key, and `RELEASE_NUMBER` set by your pipeline:

```sh
printf '{"archiveBase64":"%s","parentId":null,"publish":true,"label":"Release %s"}' \
  "$(base64 < templates.zip | tr -d '\n')" "$RELEASE_NUMBER" > import.json

curl -f "$PDF_URL/v1/workspace-folders/import" \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  --data @import.json -o result.json

cat result.json
jq -e '.unpublished == null' result.json > /dev/null  # fails the step if a template stayed a draft
```

`"publish": true` publishes the imported templates straight away. The response counts what was
created, updated and published; see [import and export](/templates/overview/#import-files-and-templates).
If a template could not be published, it is listed in `unpublished` with the reason, and the step
fails. The other templates are already live.

`label` is saved on the import's entries under **Manage → Audit log** (in each entry's
**Event details**), so you can see which release changed what.

Redeploying the same release is safe: unchanged templates are left alone. To roll back, deploy
the earlier release; its templates are published as new versions.

## What an import changes

- **Copied:** templates and workspace files (partials, stylesheets, data, scripts, translations,
  fonts, images and workbooks). API keys, webhooks, signing certificates, users, render limits and
  past renders stay in each environment.
- **Nothing is deleted:** a template you removed in the source stays in the target until you
  delete it there.

## Different settings per environment

**Self-hosted installations only.** To make a template behave differently per environment, for
example a "TEST" watermark everywhere except production, keep one set of templates and give each
environment its own value.

1. **Set the value on each server.** Add a `SCRIPT_ENV` line to each installation's `.env` file,
   then run `docker compose up -d`:

   ```sh title=".env on the test and staging servers"
   SCRIPT_ENV=ADD_WATERMARK=true
   ```

   ```sh title=".env on the production server"
   SCRIPT_ENV=ADD_WATERMARK=false
   ```

2. **Read it in a script.** In the Studio editor of your test environment, choose
   **+ → New entity → Script** next to the **Files** heading and name it `watermark.js`. In the script's header, change
   **Runs where included** to **Runs before every render**. The script
   [reads the value from `process.env`](/templates/handlebars/#environment-values) and
   passes it to every template:

   ```js title="watermark.js (in Studio)"
   function beforeRender(req, res) {
     req.data.AddWatermark = process.env.ADD_WATERMARK === "true";
   }
   ```

3. **Use it in the template.** Show the watermark only when the value is set:

   ```handlebars
   {{#if @root.AddWatermark}}
     <div class="watermark">TEST</div>
   {{/if}}
   ```

4. **Publish the template** so its new version includes the script. The script and template then
   move to the other environments with the rest of your templates; only the `.env` value differs.

## Troubleshooting

| Error                              | What to do                                                                                                                                                                           |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `403 FORBIDDEN`                    | The key is missing a permission; see [step 1](#1-give-the-pipeline-an-api-key-per-environment).                                                                                      |
| `429 RATE_LIMITED`                 | Another import or export is running. Retry the step.                                                                                                                                 |
| `LIMIT_EXCEEDED` (`400` or `413`)  | The workspace is too large for one zip. Export the folders one at a time with `GET /v1/workspace-folders/{id}/export` and import each zip. Copy files at the workspace root by hand. |
| `404 NOT_FOUND` on a folder export | The folder ID is wrong or belongs to another workspace.                                                                                                                              |
| A template in `unpublished`        | Read its `message`. Usually the template uses a file outside the exported folder that the target lacks; export the whole workspace instead.                                          |

---

# Build a template

Source: https://docs.typefold.dev/guides/first-template/

Build an invoice template in Studio: A4 paper with margins, a header and a "Page 1 of 2" footer
on every page, page breaks where you want them, your own font and a logo. Then preview it with
sample data and publish it so your application can render it.

**Before you start:** you need a Studio sign-in to a workspace.

## 1. Create the template

1. In the Studio sidebar, click **Workspace → Editor**. The editor opens in a new browser tab.
2. In the explorer on the left, click **+** and choose **New folder**. Enter `Invoices` as the
   **Folder name** and click **Create folder**.
3. Click **⋯** on the **Invoices** folder (or right-click it) and choose
   **New entity → Template**.
4. Enter `Invoice` as the **Template name**, leave **Start with** on **Blank template**, and click
   **Create template**.

The editor opens the template's `template.html`.

## 2. Write the HTML

Replace everything in `template.html` with this:

```handlebars title="template.html"
<html>
  <head>
    <style>
      body {
        font-family: sans-serif;
      }
      table {
        width: 100%;
        border-collapse: collapse;
      }
      th,
      td {
        border-bottom: 1px solid #ccc;
        padding: 4px;
        text-align: left;
      }
    </style>
  </head>
  <body>
    <h1>Invoice {{invoice.number}}</h1>
    <p>Bill to: {{customer.name}}</p>

    <table>
      <thead>
        <tr><th>Item</th><th>Qty</th><th>Price</th></tr>
      </thead>
      <tbody>
        {{#each lines}}
          <tr>
            <td>{{description}}</td>
            <td>{{quantity}}</td>
            <td>{{price}}</td>
          </tr>
        {{/each}}
      </tbody>
    </table>
  </body>
</html>
```

The placeholders, such as `{{customer.name}}` and `{{#each lines}}`, use
[Handlebars](https://handlebarsjs.com/guide/) syntax and are filled from your data. Press
**Ctrl+S** (**Cmd+S** on macOS) or click **Save**.

## 3. Add sample data

Sample data is the JSON Studio uses for previews.

1. Click **⋯** on the **Invoices** folder and choose **New entity → Sample data**.
2. Enter `sample.json` as the **Name** and click **Create entity**.
3. Click `sample.json` in the explorer to open it, replace `{}` with this, and save:

   ```json title="sample.json"
   {
     "invoice": { "number": "INV-1001" },
     "customer": { "name": "Marta Tamm" },
     "lines": [
       { "description": "Consulting", "quantity": 3, "price": 120 },
       { "description": "Travel", "quantity": 1, "price": 80 }
     ]
   }
   ```

4. Click the **Invoice** template in the explorer to go back to it.

## 4. Set the paper size and margins

Click the **page.json** tab under the HTML and set the paper and margins in millimetres. Leave
room at the top and bottom for the header and footer:

```json title="page.json"
{
  "pageSize": { "widthMm": 210, "heightMm": 297 },
  "orientation": "portrait",
  "margins": { "topMm": 32, "rightMm": 18, "bottomMm": 22, "leftMm": 18 }
}
```

You can also pick **Paper** and **Margins** under **PDF properties** in the preview toolbar,
which writes the same `page.json`. For landscape, keep the portrait size and set
`"orientation": "landscape"`. Every setting is in [page.json](/templates/overview/#pagejson).

## 5. Add a header and footer with page numbers

The header is drawn in the top margin of every page, and the footer in the bottom margin.

1. Click **+** at the end of the tabs under the HTML and choose **Add page header**. In the
   **Page header** tab (`header.html`), add:

   ```handlebars title="header.html"
   <div style="flex: 1; padding: 10mm 18mm 0; font-size: 9pt;">
     Invoice
     {{invoice.number}}
   </div>
   ```

2. Click **+** again and choose **Add page footer**. In the **Page footer** tab (`footer.html`),
   add elements with the classes `pageNumber` and `totalPages`. They are filled with the current
   page and the page count:

   ```html title="footer.html"
   <div style="flex: 1; padding: 0 18mm 8mm; font-size: 8pt; text-align: right;">
     Page <span class="pageNumber"></span> of <span class="totalPages"></span>
   </div>
   ```

The header and footer use the same data and helpers as the HTML. They span the full page width,
so the side padding above lines them up with the 18 mm margins. They must fit inside the margin,
which does not grow: if the header is cut off, raise `topMm`. Style them with inline `style`
attributes, because a `<style>` element in them applies to the whole document. The other rules
are in [Supported CSS](/templates/css-support/).

## 6. Control where pages break

Content flows onto the next page on its own. To keep an element in one piece, or to start it on
a new page, add CSS to the `<style>` element in `template.html`:

```css
/* Never split a table row across two pages. */
tr {
  break-inside: avoid;
}

/* Start the terms on a new page. */
.terms {
  break-before: page;
}
```

For every supported break property, see [Supported CSS](/templates/css-support/).

## 7. Use your own font

Text is set in fonts bundled with Typefold until you upload and declare your own. Fonts
installed on the server or loaded from a URL are never used.

1. Click **⋯** on the **Invoices** folder, choose **New folder** and create a `fonts` folder.
2. Click **⋯** on the `fonts` folder and choose **New entity → Asset**. Choose the font files
   (TTF, OTF or WOFF2) and click **Upload assets**.
3. In the `<style>` element of `template.html`, declare each file with `@font-face`, one rule
   per weight, and use the family on `body` in place of `sans-serif`:

   ```css
   @font-face {
     font-family: "Inter";
     src: url("fonts/Inter-Regular.ttf");
     font-weight: 400;
   }

   @font-face {
     font-family: "Inter";
     src: url("fonts/Inter-Bold.ttf");
     font-weight: 700;
   }

   body {
     font-family: "Inter", Arial;
   }
   ```

`url()` paths start from the folder of the file they are written in. From a stylesheet in a
`styles` folder, the same font is `url("../fonts/Inter-Regular.ttf")`.

If no font covers a character, such as Chinese text, the render fails with `ASSET_INVALID`.
Upload a font that covers it.

## 8. Add a logo

1. Create an `images` folder in **Invoices** and upload the logo (PNG, JPEG or SVG) the same way.
2. Point to it by path, in `template.html` or in the header:

   ```html
   <img src="./images/logo.svg" alt="Logo" style="height: 12mm" />
   ```

Images at an `https://` address are not loaded, so always upload them.

## 9. Preview the document

1. In the preview toolbar, set **Data** to `sample.json`.
2. Click **Update preview**.

The PDF appears beside the source: A4 pages in Inter, with the logo, "Invoice INV-1001" in the
header, a two-row table and "Page 1 of 1" in the footer. Click **Update preview** again after
each change. Save the template to keep `sample.json` as its preview data.

:::tip
If a value is missing from the PDF, open the **Bindings** tab to see which placeholders the
sample data fills. If the layout looks different from the same HTML in Chrome, see
[Supported CSS](/templates/css-support/).
:::

## 10. Publish

Click **Save**, then **Publish** in the header. The status changes to **Published v1**. Your
application can now render the template by its name, `Invoice`, with the
[Reports API](/guides/reports/).

A published version keeps its own copy of every file, so later edits to the template, its fonts
or its images reach your application only when you publish again. See
[Templates](/templates/overview/).

## Next steps

- [Render a report by name](/guides/reports/): send your own data to `Invoice` from your app.
- [Handlebars templates](/templates/handlebars/): helpers, scripts and shared files.
- [Translations and formatting](/features/translations/): money, dates and languages.
- [Combine templates](/features/combine-templates/): add a cover, terms or a letterhead.
- [Supported CSS](/templates/css-support/): every layout rule, including CSS `@page`.

---

# Migrating from jsreport

Source: https://docs.typefold.dev/guides/jsreport-import/

This guide moves your jsreport templates into a Typefold workspace without rewriting them, so
your application can render them by name or shortid as before.

## Before you start

- Your templates use the **Handlebars** engine with the `chrome-pdf` or `xlsx` recipe. See
  [which templates import](#which-templates-import).
- You can open the workspace in Studio (any workspace role can import and publish), or you have
  an API key with the [import scopes](#scopes) if you import from a script.

## 1. Export from jsreport

In jsreport Studio, export the folders and templates you want to move, together with the
scripts, assets, components and data they use. You get a `.jsrexport` file. It may be up to
20 MB.

## 2. Import in Studio

1. In Studio, open **Workspace → Editor**. Click **+** above the explorer and choose
   **Import…**, or choose **Import into folder…** in the **…** menu of a folder.
2. Drop the `.jsrexport` file, or click **Choose files** and select it. The **Import jsreport
   export** dialog lists:
   - each template it will import, with its format and the folder it lands in;
   - **notes** on what the import changed so the template runs here, such as a removed
     `afterRender` step, and on referenced files the export does not contain, with the path to
     add them at;
   - templates it **cannot import**, with the reason.
3. Check **Import into folder**. It defaults to a folder named after the file, such as
   `invoices` for `invoices.jsrexport`. Use `/` for nested folders, or clear it to import at the
   workspace root.
4. Click **Import file**.

The import publishes each template it writes. If one cannot be published, you see a warning with
the reason, and it stays a draft until you fix it and click **Publish**.

## 3. Check the imported templates

1. Read every note from step 2, and add any missing files at the paths they name.
2. If a template signs its PDFs, a workspace owner or administrator uploads the certificate under
   **Manage → Signing certificates** with **Upload certificate**, using the name the note gives.
3. Open each imported template in Studio and click **Update preview** with its sample data.
4. Compare the output with jsreport's.
   [Chrome compatibility](/templates/css-support/#chrome-compatibility) lists where the renderer
   follows Chrome's print layout, and [CSS support](/templates/css-support/#what-is-not-supported) what
   it does not support.
5. Publish any template that stayed a draft.

## 4. Render the imported reports

Your application renders imported templates by name through the Reports API. Recipe names are not
needed:

<Tabs syncKey="api-client">
<TabItem label="curl">

```sh
curl $PDF_URL/v1/reports/render \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  --fail-with-body -o invoice.pdf \
  -d '{
    "format": "pdf",
    "template": { "name": "Invoice" },
    "data": { "number": "INV-1001" }
  }'
```

</TabItem>
<TabItem label=".NET">

```csharp
using Typefold.Client;

var client = new TypefoldClient(
    new Uri(Environment.GetEnvironmentVariable("PDF_URL")!),
    Environment.GetEnvironmentVariable("API_KEY")!);

byte[] pdf = await client.RenderReportAsync(new RenderReportRequest
{
    Template = TemplateRef.ByName("Invoice"),
    Data = new { number = "INV-1001" },
});

await File.WriteAllBytesAsync("invoice.pdf", pdf);
```

</TabItem>
<TabItem label="TypeScript">

```ts
import { writeFile } from "node:fs/promises";
import { TypefoldClient, TemplateRef } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL!,
  apiKey: process.env.API_KEY!,
});

const pdf = await client.renderReport({
  template: TemplateRef.byName("Invoice"),
  data: { number: "INV-1001" },
});

await writeFile("invoice.pdf", pdf);
```

</TabItem>
<TabItem label="JavaScript">

```js
import { writeFile } from "node:fs/promises";
import { TypefoldClient, TemplateRef } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL,
  apiKey: process.env.API_KEY,
});

const pdf = await client.renderReport({
  template: TemplateRef.byName("Invoice"),
  data: { number: "INV-1001" },
});

await writeFile("invoice.pdf", pdf);
```

</TabItem>
<TabItem label="Python">

```python
import os
from pathlib import Path

from typefold import TypefoldClient, RenderReportRequest, TemplateRef

client = TypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"])

pdf = client.render_report(
    RenderReportRequest(
        template=TemplateRef.by_name("Invoice"),
        data={"number": "INV-1001"},
    )
)

Path("invoice.pdf").write_bytes(pdf)
```

</TabItem>
</Tabs>

`PDF_URL` and `API_KEY` are set as in the [quickstart](/start/quickstart/#before-you-start). The
[Reports API](/guides/reports/) guide lists the scopes the key needs and the other request
options.

- **Shortids.** To render by the shortid your application stored in jsreport, send
  `"template": { "shortid": "rkJTnK2ce" }`, or use `TemplateRef.ByShortid` in .NET, `byShortid`
  in TypeScript and JavaScript, or `by_shortid` in Python.
- **Listing templates.** If your application listed templates with `odata/templates`, call
  `GET /v1/reports` instead (`ListReportsAsync`, `listReports` or `list_reports`). It returns
  each template's `shortid` too.
- **Clients.** The [.NET](/clients/dotnet/), [TypeScript and JavaScript](/clients/typescript/)
  and [Python](/clients/python/) clients replace jsreport's own clients.

Once the output matches, switch your application over.

## Import with the API

Two endpoints do what the Studio dialog does: one inspects the archive, one imports it. Both take
the archive as base64 in JSON, with an optional `folderPath` to import into, such as
`Projects/Invoices`. Missing folders are created. Without `folderPath`, the archive lands at the
workspace root. Every field is in the [API reference](/reference/api/).

1. Build the request body:

   ```sh
   # On macOS, use: base64 -i invoices.jsrexport
   printf '{"archiveBase64":"%s","folderPath":"Invoices"}' \
     "$(base64 -w0 invoices.jsrexport)" > import.json
   ```

2. Inspect the archive. This changes nothing:

   ```sh
   curl $PDF_URL/v1/reports/import/inspect \
     -H "x-api-key: $API_KEY" \
     -H "content-type: application/json" \
     --data @import.json
   ```

   ```json
   {
     "items": [
       {
         "name": "Invoice",
         "format": "pdf",
         "assets": 4,
         "folderPath": "Invoices",
         "changes": [
           "Script \"format-rows\": its afterRender step was removed; only beforeRender runs.",
           "File \"logo.png\" is not in the export; the template renders once the workspace has it at /Invoices/shared/logo.png."
         ]
       }
     ],
     "unsupported": [
       {
         "name": "Shipping labels",
         "recipe": "html-to-xlsx",
         "engine": "handlebars"
       }
     ]
   }
   ```

   `changes` holds the notes for each template, and `unsupported` the templates that will be
   skipped, with a `reason` when the recipe is supported but something the template uses is not.

3. Import it:

   ```sh
   curl $PDF_URL/v1/reports/import \
     -H "x-api-key: $API_KEY" \
     -H "content-type: application/json" \
     --data @import.json
   ```

   ```json
   {
     "imported": 1,
     "updated": 0,
     "skipped": 0,
     "unpublished": [
       {
         "name": "Invoice",
         "message": "Missing workspace files: Invoices/shared/logo.png (referenced by template.html)."
       }
     ]
   }
   ```

   `imported` counts new templates, `updated` those that got a new draft, and `skipped` those
   left as they were (see [import again](#import-again)). `unpublished` lists the templates that
   stayed drafts, with why. Fix what each message names and publish them, then carry on with
   [step 3](#3-check-the-imported-templates).

The import writes every template or none. One template that cannot be published does not stop
the others.

### Scopes

| Action             | Endpoint                          | Scopes                                                                                                                       |
| ------------------ | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Inspect an archive | `POST /v1/reports/import/inspect` | `template:read`                                                                                                              |
| Import an archive  | `POST /v1/reports/import`         | `template:write`; `asset:manage` to upload fonts, images and workbooks; `template:publish` to publish the imported templates |

Without `asset:manage`, the import leaves out fonts, images and workbooks, and templates that use
them report the files as missing. Without `template:publish`, every template stays a draft and is
listed in `unpublished`. See [API keys and scopes](/clients/http/#api-keys).

## Import again

You can import the same or an updated export again. IDs stay stable, so applications that render
by name, ID or shortid keep working.

- A template nobody has edited since its import gets a new draft and is published again. One
  imported from the identical archive is skipped.
- A template someone has edited in Typefold since its import is skipped, so your changes are
  never overwritten.
- A template you deleted comes back.
- A workspace file whose content changed is saved as a new revision. A global or folder script
  that is already in the workspace stays as it is.

:::tip
Published versions keep their own copies of workspace files. After a re-import changes a
workspace file, templates that were skipped keep rendering the old copy until you publish them
again.
:::

## Which templates import

| jsreport recipe | Becomes                                                              |
| --------------- | -------------------------------------------------------------------- |
| `chrome-pdf`    | A PDF template, with its Chrome print settings in `page.json`.       |
| `xlsx`          | An XLSX template that fills the workbook the jsreport template used. |

Both need the Handlebars engine. Templates with other recipes or engines are listed as
unsupported and skipped; the rest of the archive still imports. A Handlebars `chrome-pdf` or
`xlsx` template is also skipped when:

- a script it uses does not parse, or is larger than 100 KB;
- it would run more than 10 scripts, counting global and folder scripts;
- its page size or margins cannot be mapped, such as format `A6` or a margin in `pt`;
- its name is longer than 120 characters.

The whole archive is refused when it is larger than 20 MB, is not a valid zip, has an entry that
is missing required fields, or has two templates with the same name and format. The other import
limits are in [limits](/clients/limits/#imports-and-exports).

## What maps to what

jsreport folders become workspace folders under the folder you import into, and every file keeps
its folder.

| In jsreport                                                                  | In Typefold                                                 |
| ---------------------------------------------------------------------------- | ----------------------------------------------------------- |
| Folder                                                                       | Workspace folder                                            |
| Handlebars `chrome-pdf` or `xlsx` template                                   | Template, with a stable ID, that keeps its jsreport shortid |
| Template content                                                             | The template's HTML source                                  |
| Template helpers                                                             | `helpers.js`                                                |
| Chrome `headerTemplate` and `footerTemplate`, with `displayHeaderFooter`     | `header.html` and `footer.html`                             |
| Chrome print settings, PDF settings, language                                | `page.json` (see [page settings](#page-settings))           |
| Component                                                                    | Partial, rendered by `{{component "..."}}` as before        |
| HTML, `.xml` and `.txt` assets                                               | Partials                                                    |
| `.js` assets                                                                 | Scripts                                                     |
| `.css` assets                                                                | Stylesheets                                                 |
| `.json` assets                                                               | Localizations (translations)                                |
| `.ttf`, `.otf`, `.woff2`, `.png`, `.jpg`, `.jpeg`, `.svg` and `.xlsx` assets | Uploaded fonts, images and workbooks (needs `asset:manage`) |
| Data item                                                                    | Sample data file, used for previews                         |
| Global script                                                                | Script that runs before every render                        |
| Folder script                                                                | Script that runs before renders in that folder and below    |
| Script assigned to a template                                                | Script beside the template, which the template runs by name |

Blank header and footer templates are left out, and Chrome's default date, title and URL bands
are not drawn. Assets of other types are not imported. Data items become sample data for
previews only; your application still sends the live data with every render request.

Paths keep working:

- Root paths such as `{#asset /shared/logo.png @encoding=dataURI}` and
  `{{component "/shared/address"}}` are rewritten to start at the folder you imported into.
- jsreport finds a file named without a folder anywhere in the export. When exactly one file has
  that name, the import rewrites the reference to that file's path from the template's folder.

PDF templates also get `body { font-family: Arial, sans-serif; }` ahead of their own styles,
because jsreport's Chrome prints in Arial unless told otherwise. Your own CSS still wins.

### Page settings

A `chrome-pdf` template's settings become its `page.json`:

| jsreport setting                                                        | `page.json`                                                                                                                                                                                   |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `format` (A3, A4, A5, Letter, Legal)                                    | Page size. Any other format makes the template unsupported.                                                                                                                                   |
| `width` and `height`                                                    | Custom page size, when no `format` is set.                                                                                                                                                    |
| Neither                                                                 | Letter, as in jsreport.                                                                                                                                                                       |
| `landscape`                                                             | Orientation.                                                                                                                                                                                  |
| `marginTop`, `marginRight`, `marginBottom`, `marginLeft`                | Margins in millimetres. Lengths in `px`, `mm`, `cm` or `in`; a bare number is pixels. An unset side is 0.                                                                                     |
| `pageRanges`                                                            | Page ranges, when they are valid.                                                                                                                                                             |
| `preferCSSPageSize`                                                     | `preferCssPageSize`, so an `@page` size prints on its own paper as in jsreport.                                                                                                               |
| `pdfMeta` title, author, subject, creator, producer, language, keywords | PDF document properties. Keywords are split at commas.                                                                                                                                        |
| `pdfPassword` with a password or owner password                         | [Passwords and permissions](/guides/pdf-standards/#passwords-and-permissions). As in jsreport, permissions it does not name are not granted.                                                  |
| `pdfSign`                                                               | A [signature](/guides/pdf-standards/#digital-signatures) with its reason. The certificate is named after the jsreport asset without its extension: `Company seal.p12` becomes `Company seal`. |
| pdf-utils operations                                                    | `operations`, naming the other template. Disabled operations are skipped (see [what changes](#what-changes-on-import)).                                                                       |
| `pdfAccessibility` with PDF/UA on                                       | PDF/UA-1, if the template has a heading (see [what changes](#what-changes-on-import)).                                                                                                        |
| Template `localization.language`                                        | Locale. Without one, `en-US`.                                                                                                                                                                 |

## What works the same

Templates that rely on these need no changes:

- **Paths.** Partials, `{#asset}` paths and `{{component}}` calls resolve as in jsreport. See
  [how paths resolve](/templates/overview/#how-paths-resolve).
- **Components.** `{{component "path"}}` renders a partial the way jsreport components do. See
  [reuse a block with component](/templates/handlebars/#reuse-a-block-with-component).
- **Helpers and scripts.** Helper files and `beforeRender` scripts take the same forms as in
  jsreport. `require("moment")` offers a
  [subset of Moment](/features/translations/#moment) for formatting dates.
  `require("bwip-js")` offers only the synchronous `toSVG`, so a barcode helper that used
  `toBuffer` must switch to `toSVG` or to the built-in `qrCode` and `barcode` helpers.
- **Localization.** In scripts, `require("jsreport-proxy")` offers `localization.localize(key)`,
  which returns the label for the request's language, or the key when the translation file has
  none.
- **pdf-utils.** `pdfCreatePagesGroup`, `pdfAddPageItem`, `pdfDest` and `pdfFormField` work as
  in jsreport. Other templates read `$pdf`, also once per page with `renderForEveryPage`. See
  [page data and form fields](/features/form-fields/).
- **`@page` rules.** Margins and orientation from a template's `@page` rule apply as Chrome
  printed them, and its size too when the template had `preferCSSPageSize`.
- **Header and footer classes.** The `pageNumber` and `totalPages` classes from Chrome's print
  templates work unchanged in `header.html` and `footer.html`. See
  [Lay out pages](/guides/first-template/).
- **Fonts.** The name in `font-family` need not match the name inside the font file, so
  `font-family: Regular` keeps working, and fonts embedded as data URLs work too. `Arial` has the
  same metrics as in jsreport's Chrome on Linux, so lines and pages break in the same places.
- **Layout.** Full-page sections built with `html, body { height: 100% }` keep one section per
  page, as in Chrome.
- **Workbooks.** Imported `xlsx` templates become
  [workbook templates](/guides/spreadsheets/#workbook-templates), and the row commands of
  jsreport's `xlsx` recipe work the same.
- **Inline Handlebars.** Text that jsreport rendered with the `html` recipe can go through
  [string rendering](/guides/string-rendering/) with `"engine": "handlebars"`.

## What changes on import

The import adjusts these so templates run here. Each appears as a note in the import dialog and
in the inspect response.

- **`afterRender` steps are removed.** A script with only `afterRender` is left out; one with
  both keeps its `beforeRender`. Do any post-processing in your application after rendering.
- **pdf-utils `append`, `prepend` and `merge` operations become
  [pages from other templates](/features/combine-templates/)**, naming
  the other template. An operation is left out, with a note, when its template is not a
  `chrome-pdf` template in the same archive, or beyond the tenth.
- **Signing certificates are not imported.** A template with `pdfSign` fails to render until its
  `.p12` or `.pfx` file is uploaded with the name the note gives (see
  [step 3](#3-check-the-imported-templates)).
- **PDF/UA needs a heading.** PDF/UA output here fails without an `h1` to `h6` heading, which
  jsreport never required. If neither the template nor the partials it includes has one, PDF/UA
  is turned off with a note. Add a heading and import again, or ask for PDF/UA per request with
  `pdf.pdfua`.

## What does not carry over

| jsreport feature                                                                        | What to do instead                                                     |
| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Recipes other than `chrome-pdf` and `xlsx`, engines other than Handlebars               | Rebuild the template in Studio.                                        |
| Other `jsreport-proxy` calls, such as `render`, `documentStore`, `folders` and `assets` | Send all the data the template needs with the render request.          |
| Chrome scale, viewport size, print background and wait-for-JS                           | No equivalent. Check the layout in a preview.                          |
| pdf-utils PDF/A setting                                                                 | Turn on [PDF/A](/guides/pdf-standards/#make-it-pdfa) for the template. |
| `pdfFormField` in a PDF/A template                                                      | Turn PDF/A off for that template, or leave the fields out.             |
| `$pdf` read in a script                                                                 | Read `$pdf` in the template or its helpers.                            |

A script that makes any other `jsreport-proxy` call fails with an error naming the call. Scripts
have no network, file system or Node.js APIs; see
[template language](/templates/handlebars/#prepare-data-with-a-script).
[Not supported](/start/not-supported/) lists the general gaps and their workarounds.

---

# PDF standards, passwords and signatures

Source: https://docs.typefold.dev/guides/pdf-standards/

Give your PDFs a title, make them PDF/A or PDF/UA with bookmarks, embed e-invoice XML, and
protect them with a password or a digital signature.

## Before you start

- An editable template in Studio. See [build a template](/guides/first-template/).
- curl or a client library for the API examples, set up as in the [quickstart](/start/quickstart/).

For what the standards require, see [PDF/A](https://pdfa.org/resource/iso-19005-pdfa/),
[PDF/UA](https://pdfa.org/resource/iso-14289-pdfua/) and [Factur-X](https://fnfe-mpe.org/factur-x/).

## Set the title and other properties

In Studio, open the template and click **PDF properties** (the sliders button) in the preview
toolbar. Fill in **Title**, **Author** and the other fields under **Document**. Without a
**Title**, the PDF takes the template's name. Studio writes the fields into the template's
`page.json`:

```json
{
  "metadata": {
    "title": "Invoice {{invoice.number}}",
    "author": "Example Ltd"
  }
}
```

`{{invoice.number}}` is filled from each render's data. To change a property for one render,
send `metadata` with the request:

<Tabs syncKey="api-client">
<TabItem label="curl">

```sh
curl -X POST "$PDF_URL/v1/renders" \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "templateVersionId": "0b7d5c1e-8f3a-4d2b-9e61-5a4c3b2a1f00",
    "data": { "invoice": { "number": "2026-0042" } },
    "metadata": { "author": "Example Billing" }
  }'
```

</TabItem>
<TabItem label=".NET">

```csharp
using Typefold.Client;

var client = new TypefoldClient(
    new Uri(Environment.GetEnvironmentVariable("PDF_URL")!),
    Environment.GetEnvironmentVariable("API_KEY")!);

byte[] pdf = await client.RenderAsync(new TemplateVersionRenderRequest
{
    TemplateVersionId = "0b7d5c1e-8f3a-4d2b-9e61-5a4c3b2a1f00",
    Data = new { invoice = new { number = "2026-0042" } },
    Metadata = new PdfMetadata { Author = "Example Billing" },
});

await File.WriteAllBytesAsync("invoice.pdf", pdf);
```

</TabItem>
<TabItem label="TypeScript">

```ts
import { writeFile } from "node:fs/promises";
import { TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL!,
  apiKey: process.env.API_KEY!,
});

const pdf = await client.render({
  templateVersionId: "0b7d5c1e-8f3a-4d2b-9e61-5a4c3b2a1f00",
  data: { invoice: { number: "2026-0042" } },
  metadata: { author: "Example Billing" },
});

await writeFile("invoice.pdf", pdf);
```

</TabItem>
<TabItem label="JavaScript">

```js
import { writeFile } from "node:fs/promises";
import { TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL,
  apiKey: process.env.API_KEY,
});

const pdf = await client.render({
  templateVersionId: "0b7d5c1e-8f3a-4d2b-9e61-5a4c3b2a1f00",
  data: { invoice: { number: "2026-0042" } },
  metadata: { author: "Example Billing" },
});

await writeFile("invoice.pdf", pdf);
```

</TabItem>
<TabItem label="Python">

```python
import os
from pathlib import Path

from typefold import PdfMetadata, TypefoldClient, TemplateVersionRenderRequest

client = TypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"])

pdf = client.render(
    TemplateVersionRenderRequest(
        template_version_id="0b7d5c1e-8f3a-4d2b-9e61-5a4c3b2a1f00",
        data={"invoice": {"number": "2026-0042"}},
        metadata=PdfMetadata(author="Example Billing"),
    )
)

Path("invoice.pdf").write_bytes(pdf)
```

</TabItem>
</Tabs>

The curl call creates a render. Once it has `succeeded`,
[download the PDF](/guides/rendering/) from its `result.downloadUrl`. The clients
wait and return the file.

The properties are `title`, `author`, `subject`, `creator`, `producer` (default `typefold`),
`language` (default: the render's language) and `keywords`. A value sent with a request replaces
the template's value for that property. An empty string removes a property (`producer` and
`language` go back to their defaults), and `"keywords": []` removes the keywords. Only the
template's values fill `{{path}}` placeholders; request values are used as written.

## Check which standards a document meets

In the preview toolbar, click the shield button (**Check accessibility and conformance**). Studio
lists which PDF/A levels and PDF/UA parts the document meets and what to change for the others.
It also lists accessibility problems in the HTML and the order a screen reader reads the PDF.

With the API, add `"checkConformance": true` to a template preview
(`POST /v1/templates/{id}/preview`). The `pdf-conformance` response header lists each standard
with `conforms` and, when it does not, the `issues` to fix. A preview render on `POST /v1/renders`
returns the same list in `result.conformance`. See the [API reference](/reference/api/).

## Make it PDF/A

In **PDF properties**, under **Standards**, pick a level for **PDF/A**: **PDF/A-2b** for
archiving, **PDF/A-3b** for e-invoices. Studio writes it into `page.json`:

```json
{ "pdfa": "2b" }
```

Save the template and click **Publish**. Every render of the new version is now a PDF/A file at
the level you picked.

The levels are `2b`, `2u`, `2a`, `3b`, `3u`, `3a`, `4` and `4f`. To pick a level for one render,
set `pdf.pdfa` in a [Reports API](/guides/reports/) request. A request cannot turn off the
template's level.

## Make it PDF/UA

A PDF/UA document needs three things in the template:

- a title (the template's name, unless you set **Title**),
- at least one heading (`h1` to `h6`),
- alternative text on every image: `<img src="logo.png" alt="Example Ltd logo">`.

Then, in **PDF properties** under **Standards**, set **PDF/UA** to **PDF/UA-1**. `page.json` now
has both settings:

```json
{ "pdfa": "2b", "pdfua": "1" }
```

Save the template and publish it. PDF/UA-1 pairs with the PDF/A-2 and PDF/A-3 levels, and PDF/UA-2
(`"pdfua": "2"`) with `4` and `4f`.

## Bookmarks

A PDF/UA document gets bookmarks (the PDF outline) from its headings: one per visible `h1` to
`h6`, titled with the heading's text and nested by level. PDF/UA is the only way to get them: a
plain or PDF/A-only document has none. Pages that [other templates](/features/combine-templates/)
add before or after bring bookmarks for their own headings. A PDF/A or PDF/UA document cannot add
an uploaded PDF file.

## Embed e-invoice XML

Set the invoice template to **PDF/A-3b**, save it and publish it. Then send the XML file
`factur-x.xml` with each render as an attachment:

<Tabs syncKey="api-client">
<TabItem label="curl">

This example uses [jq](https://jqlang.org/) to put the file into the JSON body:

```sh
jq -n --rawfile xml factur-x.xml '{
  templateVersionId: "0b7d5c1e-8f3a-4d2b-9e61-5a4c3b2a1f00",
  data: { invoice: { number: "2026-0042", total: 1190.00 } },
  waitMs: 10000,
  attachments: [
    {
      name: "factur-x.xml",
      content: $xml,
      mimeType: "text/xml",
      description: "Factur-X invoice",
      relationship: "alternative"
    }
  ]
}' | curl -X POST "$PDF_URL/v1/renders" \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  --data-binary @-
```

</TabItem>
<TabItem label=".NET">

```csharp
using Typefold.Client;

var client = new TypefoldClient(
    new Uri(Environment.GetEnvironmentVariable("PDF_URL")!),
    Environment.GetEnvironmentVariable("API_KEY")!);

byte[] pdf = await client.RenderAsync(new TemplateVersionRenderRequest
{
    TemplateVersionId = "0b7d5c1e-8f3a-4d2b-9e61-5a4c3b2a1f00",
    Data = new { invoice = new { number = "2026-0042", total = 1190.00 } },
    Attachments = new[]
    {
        new PdfAttachment
        {
            Name = "factur-x.xml",
            Content = await File.ReadAllTextAsync("factur-x.xml"),
            MimeType = "text/xml",
            Description = "Factur-X invoice",
            Relationship = "alternative",
        },
    },
});

await File.WriteAllBytesAsync("invoice.pdf", pdf);
```

</TabItem>
<TabItem label="TypeScript">

```ts
import { readFile, writeFile } from "node:fs/promises";
import { TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL!,
  apiKey: process.env.API_KEY!,
});

const pdf = await client.render({
  templateVersionId: "0b7d5c1e-8f3a-4d2b-9e61-5a4c3b2a1f00",
  data: { invoice: { number: "2026-0042", total: 1190.0 } },
  attachments: [
    {
      name: "factur-x.xml",
      content: await readFile("factur-x.xml", "utf8"),
      mimeType: "text/xml",
      description: "Factur-X invoice",
      relationship: "alternative",
    },
  ],
});

await writeFile("invoice.pdf", pdf);
```

</TabItem>
<TabItem label="JavaScript">

```js
import { readFile, writeFile } from "node:fs/promises";
import { TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL,
  apiKey: process.env.API_KEY,
});

const pdf = await client.render({
  templateVersionId: "0b7d5c1e-8f3a-4d2b-9e61-5a4c3b2a1f00",
  data: { invoice: { number: "2026-0042", total: 1190.0 } },
  attachments: [
    {
      name: "factur-x.xml",
      content: await readFile("factur-x.xml", "utf8"),
      mimeType: "text/xml",
      description: "Factur-X invoice",
      relationship: "alternative",
    },
  ],
});

await writeFile("invoice.pdf", pdf);
```

</TabItem>
<TabItem label="Python">

```python
import os
from pathlib import Path

from typefold import PdfAttachment, TypefoldClient, TemplateVersionRenderRequest

client = TypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"])

pdf = client.render(
    TemplateVersionRenderRequest(
        template_version_id="0b7d5c1e-8f3a-4d2b-9e61-5a4c3b2a1f00",
        data={"invoice": {"number": "2026-0042", "total": 1190.00}},
        attachments=[
            PdfAttachment(
                name="factur-x.xml",
                content=Path("factur-x.xml").read_text(encoding="utf-8"),
                mime_type="text/xml",
                description="Factur-X invoice",
                relationship="alternative",
            )
        ],
    )
)

Path("invoice.pdf").write_bytes(pdf)
```

</TabItem>
</Tabs>

- A render can embed up to 10 files, 5 MiB in total. Send text as `content` or bytes as
  `contentBase64`.
- In a PDF/A file, every attachment needs `mimeType` and `description`. Only the levels `3b`,
  `3u`, `3a` and `4f` can embed files.

Factur-X also expects its XMP extension schema. Add it to the template's `page.json`, with the
`Version` and `ConformanceLevel` of your XML's profile:

```json
{
  "metadata": {
    "xmp": [
      {
        "name": "Factur-X PDF/A Extension Schema",
        "prefix": "fx",
        "namespace": "urn:factur-x:pdfa:CrossIndustryDocument:invoice:1p0#",
        "properties": [
          { "name": "DocumentType", "value": "INVOICE", "description": "Document type" },
          {
            "name": "DocumentFileName",
            "value": "factur-x.xml",
            "description": "Attached XML file"
          },
          { "name": "Version", "value": "1.0", "description": "Factur-X version" },
          { "name": "ConformanceLevel", "value": "EN 16931", "description": "Factur-X profile" }
        ]
      }
    ]
  }
}
```

:::caution
The XML is embedded exactly as you send it. It is not checked against EN 16931, XRechnung or a
Factur-X profile, so validate it before you render.
:::

## Passwords and permissions

To make readers ask for a password before they open a PDF, or to stop them printing or copying
it:

1. Open the template in Studio, click **PDF properties** and find **Security**.
2. Enter an **Open password**. `{{customer.number}}` uses each customer's number from the
   render's data.
3. Optionally enter an **Owner password**, which lifts the restrictions, and choose what readers
   may do under **Printing** and **Readers may**.

   Studio writes the settings into `page.json`:

   ```json
   {
     "encryption": {
       "openPassword": "{{customer.number}}",
       "permissions": { "copying": false }
     }
   }
   ```

4. Save the template and click **Publish**. A rendered PDF now asks for the password.

- The permissions are `printing` (`highResolution`, `lowResolution` or `none`), `copying`,
  `modifying`, `annotating`, `fillingForms`, `documentAssembly` and `contentAccessibility`.
  Each one you leave out is allowed.
- Without an owner password, nobody can lift the restrictions.
- A password holds at most 127 bytes.
- PDF/A does not allow passwords or restrictions, and PDF/UA needs
  **Screen readers (PDF/UA requires it)** ticked under **Readers may**.
- A request's `encryption` changes the template's settings for one render.

## Digital signatures

Upload a signing certificate once, then pick it in each template that signs.

1. In Studio, open **Manage → Signing certificates** and click **Upload certificate**. Enter a
   **Name**, such as `Company seal`, choose the **Certificate file** (`.p12` or `.pfx`) and enter
   its **File password**.
2. Open the template, click **PDF properties** and, under **Signature**, choose the certificate
   as **Certificate**. Optionally fill in **Reason**, **Location** and **Contact**. Studio writes
   them into `page.json`:

   ```json
   {
     "signature": {
       "certificate": "Company seal",
       "reason": "Invoice {{invoice.number}}"
     }
   }
   ```

   The PDF is signed invisibly. To show the signature on a page, turn on
   **Visible signature field** and set its **Area**, then draw the signature block (a stamp or a
   name) in that area of the template.

3. Save the template and click **Publish**. PDF readers now show the signature and the signer's
   name.

- A signed PDF cannot have a password or be PDF/UA.
- A request's `signature` changes the template's settings for one render. Its `field` places a
  visible signature: `page`, then `xMm`, `yMm`, `widthMm` and `heightMm` from the page's top-left
  corner.

### Manage signing certificates

Everyone in the workspace sees the list under **Manage → Signing certificates**, with each
certificate's **Signer**, **Issued by** and **Valid until**. Only owners and admins can upload or
delete one; see [roles](/clients/http/).

- **Templates find a certificate by its name**, ignoring case, and names are unique in a
  workspace. A render that names a certificate the workspace does not have fails.
- **The file** holds one RSA or EC private key with its certificate chain, at most 64 KiB. An
  expired certificate is refused at upload, and the key can never be read back.
- **Expiry:** once **Valid until** has passed, the list marks the certificate **Expired** and
  renders that sign with it fail.
- **Renewal:** upload the new file under a new name, choose it under **Signature** and publish.
  Or delete the old certificate and upload the new file under the same name: templates keep
  working without a new version, but renders that sign fail in between.
- **Deleting** a certificate cannot be undone. Templates that sign with it fail to render until a
  certificate with the same name is uploaded.
- **Environments:** certificates are not copied by an
  [environment import](/guides/environments/). Upload one with the same name in each
  environment.
- A workspace holds up to 50 certificates. To manage them with the API, use
  `/v1/signing-certificates` with a key that has the `certificate:manage` scope (listing needs
  only `template:read`); see the [API reference](/reference/api/).

## Test renders

A [test render](/guides/rendering/#test-renders) keeps every setting on this page. Its "TEST"
watermark is marked as decoration, not content, and passwords and signatures work as usual. Don't
archive test PDFs.

## If a render fails

A document that cannot meet the standard fails, and the error message lists what to change. Fix
the template, or turn the standard off, and render again. A setting that cannot work together,
such as a password on a PDF/A file, answers `400 BAD_REQUEST` at once. See
[errors](/clients/http/).

## Next steps

- [API reference](/reference/api/): every field of these settings.
- [Reports API](/guides/reports/) and [Renders API](/guides/rendering/): the request forms.
- [Combine templates](/features/combine-templates/): a cover, terms or a letterhead.

---

# Render with the Renders API

Source: https://docs.typefold.dev/guides/rendering/

The Renders API turns a published template version, or HTML your application builds, into a PDF.
Each request creates a render with its own ID that you can wait for, download or cancel, and that
can notify you through [webhooks](/guides/webhooks/). To create many at once, see
[batches](/guides/batch-rendering/). To render a template by name and get the file straight back,
or to get an Excel file, use the [Reports API](/guides/reports/) instead.

## Before you start

- **An API key** with `render:create` and `render:read`, plus `template:read` to look up template
  versions; see the [HTTP API](/clients/http/).
- **A published template**, unless you render your own HTML; see
  [Build a template](/guides/first-template/).
- **curl or a client library**, set up as in the [quickstart](/start/quickstart/).

## 1. Render a specific template version

A version ID keeps your PDFs on that version until you change the ID, even after the template is
published again. Look the ID up once and put it in your configuration. The clients don't look up
versions, so use curl; the current version's ID is `publishedVersionId`:

```sh
curl "$PDF_URL/v1/templates?search=Invoice" -H "x-api-key: $API_KEY"
```

Then render that version with your data:

<Tabs syncKey="api-client">
<TabItem label="curl">

```sh
curl "$PDF_URL/v1/renders" \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "templateVersionId": "c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
    "data": { "invoice": { "number": "INV-2041" }, "customer": { "name": "Marta Tamm" } },
    "waitMs": 10000
  }'
```

</TabItem>
<TabItem label=".NET">

```csharp
using Typefold.Client;

var client = new TypefoldClient(
    new Uri(Environment.GetEnvironmentVariable("PDF_URL")!),
    Environment.GetEnvironmentVariable("API_KEY")!);

byte[] pdf = await client.RenderAsync(new TemplateVersionRenderRequest
{
    TemplateVersionId = "c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
    Data = new
    {
        invoice = new { number = "INV-2041" },
        customer = new { name = "Marta Tamm" },
    },
});

await File.WriteAllBytesAsync("invoice.pdf", pdf);
```

</TabItem>
<TabItem label="TypeScript">

```ts
import { writeFile } from "node:fs/promises";
import { TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL!,
  apiKey: process.env.API_KEY!,
});

const pdf = await client.render({
  templateVersionId: "c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
  data: { invoice: { number: "INV-2041" }, customer: { name: "Marta Tamm" } },
});

await writeFile("invoice.pdf", pdf);
```

</TabItem>
<TabItem label="JavaScript">

```js
import { writeFile } from "node:fs/promises";
import { TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL,
  apiKey: process.env.API_KEY,
});

const pdf = await client.render({
  templateVersionId: "c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
  data: { invoice: { number: "INV-2041" }, customer: { name: "Marta Tamm" } },
});

await writeFile("invoice.pdf", pdf);
```

</TabItem>
<TabItem label="Python">

```python
import os
from pathlib import Path

from typefold import TypefoldClient, TemplateVersionRenderRequest

client = TypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"])

pdf = client.render(
    TemplateVersionRenderRequest(
        template_version_id="c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
        data={"invoice": {"number": "INV-2041"}, "customer": {"name": "Marta Tamm"}},
    )
)

Path("invoice.pdf").write_bytes(pdf)
```

</TabItem>
</Tabs>

With curl, `waitMs` keeps the request open; see [wait in the request](#wait-in-the-request). The
clients wait, download the PDF and throw if the render fails.

- `data` is required. Send `{}` if the template needs none.
- Paper, fonts, images and translations come from the version, so there is no `settings` field.
- `locale`, such as `de-DE`, picks which of the template's
  [translations](/features/translations/#choose-the-language) to use. Without it, the template's own language is used.
- Any version can be rendered, not only the latest. Once the template is deleted, renders of any
  of its versions answer `404 NOT_FOUND`.
- `metadata`, `encryption`, `signature` and `attachments` change the PDF's properties, passwords,
  signature and embedded files for this render only; see
  [PDF standards and security](/guides/pdf-standards/).
- `destination` also uploads the PDF to a bucket of yours; see
  [storage destinations](/guides/storage-destinations/).

## 2. Or render your own HTML

Send HTML your code builds as a `document`, with the paper and margins in `settings`:

<Tabs syncKey="api-client">
<TabItem label="curl">

```sh
curl "$PDF_URL/v1/renders" \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "document": {
      "kind": "html",
      "html": "<h1>Invoice INV-2041</h1><p>Total due: 360.00 EUR</p>",
      "css": ["h1 { color: #1d3557; }"]
    },
    "settings": {
      "pageSize": { "widthMm": 210, "heightMm": 297 },
      "margins": { "topMm": 20, "rightMm": 15, "bottomMm": 20, "leftMm": 15 }
    },
    "waitMs": 10000
  }'
```

</TabItem>
<TabItem label=".NET">

```csharp
using Typefold.Client;

var client = new TypefoldClient(
    new Uri(Environment.GetEnvironmentVariable("PDF_URL")!),
    Environment.GetEnvironmentVariable("API_KEY")!);

byte[] pdf = await client.RenderAsync(new DirectRenderRequest
{
    Document = new HtmlDocument
    {
        Html = "<h1>Invoice INV-2041</h1><p>Total due: 360.00 EUR</p>",
        Css = new[] { "h1 { color: #1d3557; }" },
    },
    Settings = new RenderSettings
    {
        PageSize = PageSize.A4,
        Margins = new Margins { TopMm = 20, RightMm = 15, BottomMm = 20, LeftMm = 15 },
    },
});

await File.WriteAllBytesAsync("invoice.pdf", pdf);
```

</TabItem>
<TabItem label="TypeScript">

```ts
import { writeFile } from "node:fs/promises";
import { PageSize, TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL!,
  apiKey: process.env.API_KEY!,
});

const pdf = await client.render({
  document: {
    html: "<h1>Invoice INV-2041</h1><p>Total due: 360.00 EUR</p>",
    css: ["h1 { color: #1d3557; }"],
  },
  settings: {
    pageSize: PageSize.A4,
    margins: { topMm: 20, rightMm: 15, bottomMm: 20, leftMm: 15 },
  },
});

await writeFile("invoice.pdf", pdf);
```

</TabItem>
<TabItem label="JavaScript">

```js
import { writeFile } from "node:fs/promises";
import { PageSize, TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL,
  apiKey: process.env.API_KEY,
});

const pdf = await client.render({
  document: {
    html: "<h1>Invoice INV-2041</h1><p>Total due: 360.00 EUR</p>",
    css: ["h1 { color: #1d3557; }"],
  },
  settings: {
    pageSize: PageSize.A4,
    margins: { topMm: 20, rightMm: 15, bottomMm: 20, leftMm: 15 },
  },
});

await writeFile("invoice.pdf", pdf);
```

</TabItem>
<TabItem label="Python">

```python
import os
from pathlib import Path

from typefold import (
    DirectRenderRequest,
    HtmlDocument,
    Margins,
    PageSize,
    TypefoldClient,
    RenderSettings,
)

client = TypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"])

pdf = client.render(
    DirectRenderRequest(
        document=HtmlDocument(
            html="<h1>Invoice INV-2041</h1><p>Total due: 360.00 EUR</p>",
            css=["h1 { color: #1d3557; }"],
        ),
        settings=RenderSettings(
            page_size=PageSize.A4,
            margins=Margins(top_mm=20, right_mm=15, bottom_mm=20, left_mm=15),
        ),
    )
)

Path("invoice.pdf").write_bytes(pdf)
```

</TabItem>
</Tabs>

- Your HTML is used as sent: it is not a Handlebars template, so `{{name}}` stays text, and
  JavaScript in it never runs.
- `html` is up to 5,000,000 characters. `css` holds up to 20 stylesheets, applied in order;
  `<style>` elements in the HTML work too. See [supported CSS](/templates/css-support/).
- `settings` takes the same fields as a template's [`page.json`](/templates/overview/).
  `pageSize` and `margins` are required. `operations` is refused with `400 BAD_REQUEST`, because
  only templates add pages from other templates. `metadata`, `encryption` and `signature` are
  used as written, since there is no data to fill `{{path}}` placeholders.
- The request also takes `metadata`, `encryption`, `signature`, `attachments` and `destination`, as in
  [step 1](#1-render-a-specific-template-version).
- Instead of HTML, `"kind": "node"` with a `node` field takes a tree of `container`, `text` and
  `image` objects. Its fields are in the [API reference](/reference/api/).

### Use fonts and images in your HTML

The renderer doesn't load files from the web. Upload each font, image or stylesheet once (scope
`asset:manage`; see the [HTTP API](/clients/http/)), list its ID in `assetIds` (up to 100), and use
the ID where HTML or CSS takes a URL:

```json
{
  "document": {
    "kind": "html",
    "html": "<img src=\"3f2b6c1d-logo\" width=\"120\"><h1>Invoice INV-2041</h1>",
    "css": [
      "@font-face { font-family: 'Brand'; src: url('9a7e5d3c-brand'); } body { font-family: 'Brand'; }"
    ],
    "assetIds": ["3f2b6c1d-logo", "9a7e5d3c-brand"]
  },
  "settings": {
    "pageSize": { "widthMm": 210, "heightMm": 297 },
    "margins": { "topMm": 20, "rightMm": 15, "bottomMm": 20, "leftMm": 15 }
  }
}
```

| Asset      | File types      | Use it as                                       |
| ---------- | --------------- | ----------------------------------------------- |
| Image      | PNG, JPEG, SVG  | `<img src="ASSET_ID">` or CSS `url("ASSET_ID")` |
| Font       | TTF, OTF, WOFF2 | `@font-face { src: url("ASSET_ID"); }`          |
| Stylesheet | CSS             | Applied automatically, before `css`             |

- An unknown, deleted or duplicate asset ID answers `400 ASSET_INVALID`, and no render is
  created.
- Changing or deleting an asset later does not change renders that already exist.
- Small images can be inlined as `data:` URLs instead.

## 3. Get the finished file

A render ends `succeeded`, `failed` or `cancelled`; see [render states](#render-states). The
clients' render method does this step for you. Use the calls below to create a render now and
collect the PDF later.

### Wait in the request

`waitMs` (0 to 10,000, default `0`) keeps `POST /v1/renders` open until the render ends or the
time runs out:

| Response | When                               | Body                                              |
| -------- | ---------------------------------- | ------------------------------------------------- |
| `200`    | The render ended in time.          | The render: `succeeded`, `failed` or `cancelled`. |
| `202`    | Time ran out, or `waitMs` was `0`. | The render, still `queued` or `processing`.       |

`200` means ended, not succeeded: check `state`. Set your HTTP client's timeout above `waitMs`.

### Poll or get a webhook

Read the render every few seconds until it has ended, or let a [webhook](/guides/webhooks/) tell
you:

<Tabs syncKey="api-client">
<TabItem label="curl">

```sh
curl "$PDF_URL/v1/renders/0b6f0f8e-3c55-4c1e-a3a7-8d1a6f2c9e41" \
  -H "x-api-key: $API_KEY"
```

</TabItem>
<TabItem label=".NET">

```csharp
using Typefold.Client;

var client = new TypefoldClient(
    new Uri(Environment.GetEnvironmentVariable("PDF_URL")!),
    Environment.GetEnvironmentVariable("API_KEY")!);

Render render = await client.GetRenderAsync("0b6f0f8e-3c55-4c1e-a3a7-8d1a6f2c9e41");

Console.WriteLine(render.State);
```

</TabItem>
<TabItem label="TypeScript">

```ts
import { TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL!,
  apiKey: process.env.API_KEY!,
});

const render = await client.getRender("0b6f0f8e-3c55-4c1e-a3a7-8d1a6f2c9e41");

console.log(render.state);
```

</TabItem>
<TabItem label="JavaScript">

```js
import { TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL,
  apiKey: process.env.API_KEY,
});

const render = await client.getRender("0b6f0f8e-3c55-4c1e-a3a7-8d1a6f2c9e41");

console.log(render.state);
```

</TabItem>
<TabItem label="Python">

```python
import os

from typefold import TypefoldClient

client = TypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"])

render = client.get_render("0b6f0f8e-3c55-4c1e-a3a7-8d1a6f2c9e41")

print(render.state)
```

</TabItem>
</Tabs>

### Download the PDF

A `succeeded` render has a `result` with `downloadUrl`, `pageCount`, `outputBytes` and
`durationMs`, and `destination` when it was [uploaded to your bucket](/guides/storage-destinations/). `downloadUrl` works without the API key, so you can hand it to a browser, for five
minutes (`expiresAt`):

<Tabs syncKey="api-client">
<TabItem label="curl">

```sh
curl -o invoice.pdf "PASTE-THE-downloadUrl-HERE"
```

</TabItem>
<TabItem label=".NET">

```csharp
using Typefold.Client;

var client = new TypefoldClient(
    new Uri(Environment.GetEnvironmentVariable("PDF_URL")!),
    Environment.GetEnvironmentVariable("API_KEY")!);

Render render = await client.GetRenderAsync("0b6f0f8e-3c55-4c1e-a3a7-8d1a6f2c9e41");
byte[] pdf = await client.DownloadAsync(render);

await File.WriteAllBytesAsync("invoice.pdf", pdf);
```

</TabItem>
<TabItem label="TypeScript">

```ts
import { writeFile } from "node:fs/promises";
import { TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL!,
  apiKey: process.env.API_KEY!,
});

const render = await client.getRender("0b6f0f8e-3c55-4c1e-a3a7-8d1a6f2c9e41");
const pdf = await client.download(render);

await writeFile("invoice.pdf", pdf);
```

</TabItem>
<TabItem label="JavaScript">

```js
import { writeFile } from "node:fs/promises";
import { TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL,
  apiKey: process.env.API_KEY,
});

const render = await client.getRender("0b6f0f8e-3c55-4c1e-a3a7-8d1a6f2c9e41");
const pdf = await client.download(render);

await writeFile("invoice.pdf", pdf);
```

</TabItem>
<TabItem label="Python">

```python
import os
from pathlib import Path

from typefold import TypefoldClient

client = TypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"])

render = client.get_render("0b6f0f8e-3c55-4c1e-a3a7-8d1a6f2c9e41")
pdf = client.download(render)

Path("invoice.pdf").write_bytes(pdf)
```

</TabItem>
</Tabs>

Don't store `downloadUrl`: every read of the render gives a fresh one, and the clients fetch it
for you when it has expired. Keep your own copy of PDFs you need, because renders are
[deleted after 30 days](#retention). The other `result` fields are in the
[API reference](/reference/api/).

### Cancel a render

A render that hasn't ended can be cancelled (scope `render:cancel`):

<Tabs syncKey="api-client">
<TabItem label="curl">

```sh
curl -X POST "$PDF_URL/v1/renders/0b6f0f8e-3c55-4c1e-a3a7-8d1a6f2c9e41/cancel" \
  -H "x-api-key: $API_KEY"
```

</TabItem>
<TabItem label=".NET">

```csharp
using Typefold.Client;

var client = new TypefoldClient(
    new Uri(Environment.GetEnvironmentVariable("PDF_URL")!),
    Environment.GetEnvironmentVariable("API_KEY")!);

await client.CancelRenderAsync("0b6f0f8e-3c55-4c1e-a3a7-8d1a6f2c9e41");
```

</TabItem>
<TabItem label="TypeScript">

```ts
import { TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL!,
  apiKey: process.env.API_KEY!,
});

await client.cancelRender("0b6f0f8e-3c55-4c1e-a3a7-8d1a6f2c9e41");
```

</TabItem>
<TabItem label="JavaScript">

```js
import { TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL,
  apiKey: process.env.API_KEY,
});

await client.cancelRender("0b6f0f8e-3c55-4c1e-a3a7-8d1a6f2c9e41");
```

</TabItem>
<TabItem label="Python">

```python
import os

from typefold import TypefoldClient

client = TypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"])

client.cancel_render("0b6f0f8e-3c55-4c1e-a3a7-8d1a6f2c9e41")
```

</TabItem>
</Tabs>

- A `queued` render never starts. A `processing` render becomes `cancelled` at once, and no PDF
  is kept.
- A render that has already ended answers `409 CONFLICT`; an unknown ID answers `404 NOT_FOUND`.

### Find earlier renders

In Studio, **Render jobs** lists the workspace's renders, newest first, with a **Status** filter.
Open one to see its PDF and **Diagnostics**, then **Download PDF** or **Cancel render**.

Through the API, `GET /v1/renders` (scope `render:read`) lists them the same way, paged with
`limit` and `cursor`. Add `?state=failed`, or any other state, to see only those:

```sh
curl "$PDF_URL/v1/renders?state=failed" -H "x-api-key: $API_KEY"
```

List items have no `result`, `error` or download link; read the single render for those.

## Render states

<figure class="diagram">
  <svg
    viewBox="0 0 720 245"
    role="img"
    aria-label="A render starts queued, moves to processing, and ends as succeeded, failed or cancelled. A queued render can also be cancelled directly."
  >
    <defs>
      <marker
        id="d-states2"
        viewBox="0 0 10 10"
        refX="9"
        refY="5"
        markerWidth="7"
        markerHeight="7"
        orient="auto-start-reverse"
      >
        <path class="head" d="M0 0L10 5L0 10z" />
      </marker>
    </defs>
    <rect class="box" x="20" y="90" width="130" height="48" rx="8" />
    <text class="title mono" x="85.0" y="119.0" text-anchor="middle">
      queued
    </text>
    <rect class="box" x="230" y="90" width="150" height="48" rx="8" />
    <text class="title mono" x="305.0" y="119.0" text-anchor="middle">
      processing
    </text>
    <rect class="box accent" x="480" y="14" width="160" height="48" rx="8" />
    <text class="title mono" x="560.0" y="43.0" text-anchor="middle">
      succeeded
    </text>
    <rect class="box" x="480" y="90" width="160" height="48" rx="8" />
    <text class="title mono" x="560.0" y="119.0" text-anchor="middle">
      failed
    </text>
    <rect class="box" x="480" y="166" width="160" height="48" rx="8" />
    <text class="title mono" x="560.0" y="195.0" text-anchor="middle">
      cancelled
    </text>
    <path class="line" d="M150 114H226" marker-end="url(#d-states2)" />
    <path class="line" d="M380 104L476 42" marker-end="url(#d-states2)" />
    <path class="line" d="M380 114H476" marker-end="url(#d-states2)" />
    <path class="line" d="M380 124L476 182" marker-end="url(#d-states2)" />
    <path class="line" d="M85 138V198H476" marker-end="url(#d-states2)" />
    <text class="label" x="300" y="218" text-anchor="middle">
      cancel while queued or processing
    </text>
    <text class="label" x="560" y="236" text-anchor="middle">
      final states
    </text>
  </svg>
</figure>

| State        | Ended | Meaning                                                                |
| ------------ | ----- | ---------------------------------------------------------------------- |
| `queued`     | No    | Accepted and waiting to start.                                         |
| `processing` | No    | Rendering, or waiting to try again after a temporary problem.          |
| `succeeded`  | Yes   | The PDF is stored. The render has a `result`.                          |
| `failed`     | Yes   | No PDF could be made. The render has an `error`.                       |
| `cancelled`  | Yes   | You cancelled it before it ended. It has neither `result` nor `error`. |

A render that has ended never changes state again.

## Handle failures

A render that fails is not an HTTP error: the request succeeded, and the render's `state` becomes
`failed` with an `error` that says why. A `render.failed` [webhook event](/guides/webhooks/)
carries only its `code`.

### The error object

```json
{
  "id": "5e2a7c1b-9d0f-4b8e-a6c3-2f1e0d9c8b7a",
  "state": "failed",
  "createdAt": "2026-10-08T09:20:11.002Z",
  "updatedAt": "2026-10-08T09:20:13.480Z",
  "error": {
    "code": "LIMIT_EXCEEDED",
    "message": "Reduce the document length to fit the page limit.",
    "retryable": false,
    "diagnostics": [
      { "code": "max_pages", "message": "Reduce the document length to fit the page limit." }
    ]
  }
}
```

| Field         | Description                                                                       |
| ------------- | --------------------------------------------------------------------------------- |
| `code`        | `ASSET_INVALID`, `UNSUPPORTED_FEATURE`, `LIMIT_EXCEEDED` or `RENDER_FAILED`.      |
| `message`     | What to change.                                                                   |
| `retryable`   | Whether creating the same render again later might work. See [retries](#retries). |
| `diagnostics` | Optional. Each problem, with a `code`, a `message` and sometimes a `path`.        |
| `details`     | Optional. The same problems as `{ path?, message }`, as in other API errors.      |

What each code and diagnostic means, and what to do about it, is under render failures in the
[HTTP API](/clients/http/). Other optional fields are for support requests; don't branch on them.

### Retries

Temporary problems are retried for you while the render stays `processing`. So when you see
`failed`:

- **`retryable: false`**: the problem is in the request (the document, its files or settings),
  and the same request will fail again. Fix it first.
- **`retryable: true`**: the service had a temporary problem on every attempt. Creating the render
  again later may work. If it keeps happening, tell whoever runs your installation.

To render again, create a new render with a **new** `Idempotency-Key`: the old key returns the
same failed render.

## Idempotency keys

If creating a render times out or the connection drops, send it again with the same
`Idempotency-Key` header (`idempotencyKey` in the .NET and TypeScript clients, `idempotency_key` in
Python). You get the render the first request created instead of a second one. Use a value that
names the document, such as `invoice-2026-0042`.

- A key is 1 to 255 characters, per workspace.
- A repeat returns the first render in its current state, and waits for it if it has `waitMs`.
  Repeats don't count against your [render allowances](/clients/limits/).
- The key belongs to the method, path and body. Field order in the JSON doesn't matter, but any
  other change does, including a different `waitMs`: reusing a key for a different request
  answers `409 CONFLICT`.
- Two identical requests sent at the same moment still create only one render.
- A key is remembered as long as its render exists. After [retention](#retention) deletes the
  render, the key can be used again.
- `POST /v1/renders` and the Reports API's PDF requests share one set of keys.
  [Batches](/guides/batch-rendering/) have their own.

## Render an image

Set `format` to `png`, `jpeg` or `webp` to get one page of the document as an image instead of
the PDF, for a thumbnail, a preview or a social card.

<Tabs syncKey="api-client">
<TabItem label="curl">

```sh
curl "$PDF_URL/v1/renders" \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "templateVersionId": "c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
    "data": { "invoice": { "number": "INV-2041" }, "customer": { "name": "Marta Tamm" } },
    "format": "png",
    "image": { "page": 1, "width": 400 },
    "waitMs": 10000
  }'
```

</TabItem>
<TabItem label=".NET">

```csharp
using Typefold.Client;

var client = new TypefoldClient(
    new Uri(Environment.GetEnvironmentVariable("PDF_URL")!),
    Environment.GetEnvironmentVariable("API_KEY")!);

byte[] png = await client.RenderAsync(new TemplateVersionRenderRequest
{
    TemplateVersionId = "c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
    Data = new
    {
        invoice = new { number = "INV-2041" },
        customer = new { name = "Marta Tamm" },
    },
    Format = RenderFormat.Png,
    Image = new ImageOptions { Page = 1, Width = 400 },
});

await File.WriteAllBytesAsync("invoice-thumbnail.png", png);
```

</TabItem>
<TabItem label="TypeScript">

```ts
import { writeFile } from "node:fs/promises";
import { TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL!,
  apiKey: process.env.API_KEY!,
});

const png = await client.render({
  templateVersionId: "c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
  data: { invoice: { number: "INV-2041" }, customer: { name: "Marta Tamm" } },
  format: "png",
  image: { page: 1, width: 400 },
});

await writeFile("invoice-thumbnail.png", png);
```

</TabItem>
<TabItem label="JavaScript">

```js
import { writeFile } from "node:fs/promises";
import { TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL,
  apiKey: process.env.API_KEY,
});

const png = await client.render({
  templateVersionId: "c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
  data: { invoice: { number: "INV-2041" }, customer: { name: "Marta Tamm" } },
  format: "png",
  image: { page: 1, width: 400 },
});

await writeFile("invoice-thumbnail.png", png);
```

</TabItem>
<TabItem label="Python">

```python
import os
from pathlib import Path

from typefold import ImageOptions, RenderFormat, TypefoldClient, TemplateVersionRenderRequest

client = TypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"])

png = client.render(
    TemplateVersionRenderRequest(
        template_version_id="c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
        data={"invoice": {"number": "INV-2041"}, "customer": {"name": "Marta Tamm"}},
        format=RenderFormat.PNG,
        image=ImageOptions(page=1, width=400),
    )
)

Path("invoice-thumbnail.png").write_bytes(png)
```

</TabItem>
</Tabs>

| `image` field | Default                                                                                           |
| ------------- | ------------------------------------------------------------------------------------------------- |
| `page`        | `1`. The page to draw, counted from 1 in the finished PDF, after `pageRanges`.                    |
| `width`       | The page's width in CSS pixels, at most 4096. From 16 to 4096; the height keeps the page's shape. |
| `quality`     | `90`. JPEG only, from 1 to 100.                                                                   |

- The image shows the page as the PDF does, with its header and footer, page numbers and
  [watermarks](#watermarks). A [test render](#test-renders) draws "TEST" on it too.
- For a social card (an Open Graph image), make the template's page 1200 × 630 px
  (317.5 × 166.7 mm) with no margins. The image is then 1200 × 630 pixels.
- `webp` images are lossless. `jpeg` is smallest for photos.
- An image counts as one document, like a PDF. The render's `result.mediaType` is the image's
  type, `pageCount` is `1`, and the download link serves the image.
- `encryption`, `signature`, `attachments` and `checkConformance` are for PDFs, so with an image
  they answer `400 BAD_REQUEST`, and so do `settings.encryption`, `signature`, `pdfa` and `pdfua`
  on your own HTML. A template's own passwords, signature, attachments, PDF/A and PDF/UA are left
  out.
- A page the document doesn't have fails the render with the diagnostic `image_page_missing`.
  An image taller than 8192 pixels fails with `LIMIT_EXCEEDED` and `image_too_large`; ask for a
  smaller `width`.
- [Batch](/guides/batch-rendering/) items take `format` and `image` too, but a batch with images
  can't be downloaded as one PDF. The [Reports API](/guides/reports/#render-an-image) returns the
  image in the response.

## Watermarks

Add `watermark` to a render request to draw text such as `DRAFT`, `COPY` or `PAID` across every
page, in front of the content.

<Tabs syncKey="api-client">
<TabItem label="curl">

```sh
curl "$PDF_URL/v1/renders" \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "templateVersionId": "c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
    "data": { "invoice": { "number": "INV-2041" }, "customer": { "name": "Marta Tamm" } },
    "watermark": { "text": "DRAFT", "color": "#c00000", "opacity": 0.2 },
    "waitMs": 10000
  }'
```

</TabItem>
<TabItem label=".NET">

```csharp
using Typefold.Client;

var client = new TypefoldClient(
    new Uri(Environment.GetEnvironmentVariable("PDF_URL")!),
    Environment.GetEnvironmentVariable("API_KEY")!);

byte[] pdf = await client.RenderAsync(new TemplateVersionRenderRequest
{
    TemplateVersionId = "c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
    Data = new
    {
        invoice = new { number = "INV-2041" },
        customer = new { name = "Marta Tamm" },
    },
    Watermark = new PdfWatermark { Text = "DRAFT", Color = "#c00000", Opacity = 0.2 },
});

await File.WriteAllBytesAsync("invoice-draft.pdf", pdf);
```

</TabItem>
<TabItem label="TypeScript">

```ts
import { writeFile } from "node:fs/promises";
import { TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL!,
  apiKey: process.env.API_KEY!,
});

const pdf = await client.render({
  templateVersionId: "c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
  data: { invoice: { number: "INV-2041" }, customer: { name: "Marta Tamm" } },
  watermark: { text: "DRAFT", color: "#c00000", opacity: 0.2 },
});

await writeFile("invoice-draft.pdf", pdf);
```

</TabItem>
<TabItem label="JavaScript">

```js
import { writeFile } from "node:fs/promises";
import { TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL,
  apiKey: process.env.API_KEY,
});

const pdf = await client.render({
  templateVersionId: "c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
  data: { invoice: { number: "INV-2041" }, customer: { name: "Marta Tamm" } },
  watermark: { text: "DRAFT", color: "#c00000", opacity: 0.2 },
});

await writeFile("invoice-draft.pdf", pdf);
```

</TabItem>
<TabItem label="Python">

```python
import os
from pathlib import Path

from typefold import PdfWatermark, TypefoldClient, TemplateVersionRenderRequest

client = TypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"])

pdf = client.render(
    TemplateVersionRenderRequest(
        template_version_id="c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
        data={"invoice": {"number": "INV-2041"}, "customer": {"name": "Marta Tamm"}},
        watermark=PdfWatermark(text="DRAFT", color="#c00000", opacity=0.2),
    )
)

Path("invoice-draft.pdf").write_bytes(pdf)
```

</TabItem>
</Tabs>

| Field      | Default                                                                  |
| ---------- | ------------------------------------------------------------------------ |
| `text`     | Required. One line, up to 200 characters.                                |
| `opacity`  | `0.3`. From `0` (invisible) to `1` (solid).                              |
| `rotation` | Along the page's diagonal. Degrees counter-clockwise; `0` is horizontal. |
| `fontSize` | Fills 60% of the page along the text's angle, at most 144 pt. In points. |
| `color`    | `#808080` (gray). A hex colour such as `#c00000`.                        |

- The text is centred on each page in a bold sans-serif font. It covers Latin, Greek and
  Cyrillic letters; other characters fail the render with `UNSUPPORTED_FEATURE` and the
  diagnostic `watermark_text_unsupported`.
- The watermark is not part of the document's text: it can't be selected or searched, and screen
  readers skip it. PDF/A and PDF/UA files stay valid.
- Every request shape takes `watermark`, and so does the [Reports API](/guides/reports/#add-a-watermark)
  in `pdf`. With `test`, both watermarks are drawn.
- For a logo or styled text, draw another template over every page instead; see
  [Combine templates](/features/combine-templates/).

## Test renders

Add `"test": true` to a render request to get a free test PDF or image. It is the same document
with a large, translucent "TEST" drawn diagonally across every page. Use it while you build and check your
integration.

<Tabs syncKey="api-client">
<TabItem label="curl">

```sh
curl "$PDF_URL/v1/renders" \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "templateVersionId": "c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
    "data": { "invoice": { "number": "INV-2041" }, "customer": { "name": "Marta Tamm" } },
    "test": true,
    "waitMs": 10000
  }'
```

</TabItem>
<TabItem label=".NET">

```csharp
using Typefold.Client;

var client = new TypefoldClient(
    new Uri(Environment.GetEnvironmentVariable("PDF_URL")!),
    Environment.GetEnvironmentVariable("API_KEY")!);

byte[] pdf = await client.RenderAsync(new TemplateVersionRenderRequest
{
    TemplateVersionId = "c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
    Data = new
    {
        invoice = new { number = "INV-2041" },
        customer = new { name = "Marta Tamm" },
    },
    Test = true,
});

await File.WriteAllBytesAsync("invoice-test.pdf", pdf);
```

</TabItem>
<TabItem label="TypeScript">

```ts
import { writeFile } from "node:fs/promises";
import { TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL!,
  apiKey: process.env.API_KEY!,
});

const pdf = await client.render({
  templateVersionId: "c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
  data: { invoice: { number: "INV-2041" }, customer: { name: "Marta Tamm" } },
  test: true,
});

await writeFile("invoice-test.pdf", pdf);
```

</TabItem>
<TabItem label="JavaScript">

```js
import { writeFile } from "node:fs/promises";
import { TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL,
  apiKey: process.env.API_KEY,
});

const pdf = await client.render({
  templateVersionId: "c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
  data: { invoice: { number: "INV-2041" }, customer: { name: "Marta Tamm" } },
  test: true,
});

await writeFile("invoice-test.pdf", pdf);
```

</TabItem>
<TabItem label="Python">

```python
import os
from pathlib import Path

from typefold import TypefoldClient, TemplateVersionRenderRequest

client = TypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"])

pdf = client.render(
    TemplateVersionRenderRequest(
        template_version_id="c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
        data={"invoice": {"number": "INV-2041"}, "customer": {"name": "Marta Tamm"}},
        test=True,
    )
)

Path("invoice-test.pdf").write_bytes(pdf)
```

</TabItem>
</Tabs>

- Test renders don't count against your workspace's
  [render allowances](/clients/limits/#render-allowances). They have their own: 10 queued or
  processing and 10 created per minute, per workspace, or your own allowance if lower. Over
  either, the request answers `429 RATE_LIMITED` with `Retry-After`.
- Every request shape takes `test`: published versions, your own HTML, previews and
  [batch](/guides/batch-rendering/) items. So does the [Reports API](/guides/reports/) for PDFs.
- On a workspace with a [monthly document allowance](/clients/limits/#monthly-documents-and-storage),
  every PDF preview is a test render, with or without `test`, and test renders have the
  workspace's own allowances.
- Otherwise a test render is an ordinary render: it has an ID, appears in lists, sends
  [webhooks](/guides/webhooks/) and counts in usage.
- A render's `test` field, and `data.test` in its [webhook events](/guides/webhooks/#event-payload),
  is `true` for a test render and `false` otherwise.

## Retention

Renders that have ended, and their PDFs, are deleted 30 days after they were created. After that,
reading the render answers `404 NOT_FOUND`, and it is gone from lists and batches. Renders still
`queued` or `processing` are never deleted. On a self-hosted installation, set the period with
`RENDER_RETENTION_DAYS` in `.env`; see [configuration](/self-hosting/configuration/#rendering).

## Render unpublished template content

A `preview` request renders template content you send, without saving or publishing anything,
and needs `template:read` as well. The result is an ordinary render you wait for and download.
The clients don't send previews, so use curl:

```sh
curl "$PDF_URL/v1/renders" \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "preview": {
      "composition": { "root": { "type": "html", "html": "<h1>Invoice {{invoice.number}}</h1>" } },
      "settings": {
        "pageSize": { "widthMm": 210, "heightMm": 297 },
        "margins": { "topMm": 20, "rightMm": 15, "bottomMm": 20, "leftMm": 15 }
      }
    },
    "data": { "invoice": { "number": "INV-2041" } },
    "waitMs": 10000
  }'
```

- `preview` takes the same object as the `content` of a template's draft
  (`GET /v1/templates/{id}/draft`).
- `templateId` names a template whose folder the draft's workspace files are found from. Without
  it, paths start at the workspace root.
- `data` replaces the draft's sample data.
- `"checkConformance": true` renders a plain PDF and lists in `result.conformance` which PDF/A
  levels and PDF/UA parts it meets; see [PDF standards and security](/guides/pdf-standards/).

To get the file straight back instead, use `POST /v1/templates/{id}/preview`; see
[templates](/templates/overview/). Every field is in the [API reference](/reference/api/).

## Next steps

- [Get notified with webhooks](/guides/webhooks/) instead of polling.
- [Save PDFs to your own bucket](/guides/storage-destinations/).
- [Render many documents at once](/guides/batch-rendering/).
- [Build a template](/guides/first-template/): paper, header and footer, page numbers and page
  breaks.
- [API reference](/reference/api/): every field of `POST /v1/renders` and its limits.

---

# Render a report by name

Source: https://docs.typefold.dev/guides/reports/

The Reports API is the simplest way to get a document: send a template's name and your data,
and the response is the finished PDF or XLSX file. To render one specific template version or
your own HTML, use the [Renders API](/guides/rendering/).

## Before you start

- **An [API key](/clients/http/)** with `render:create`, `render:read` and `template:read`.
- **A published template**, such as one called `Invoice`; see
  [Build a template](/guides/first-template/).
- **curl or a client library**, set up as in the [quickstart](/start/quickstart/).

## 1. Render a template by name

Send the template's name and your data. The response is the file:

<Tabs syncKey="api-client">
<TabItem label="curl">

```sh
curl "$PDF_URL/v1/reports/render" \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  --fail-with-body -o invoice.pdf \
  -d '{
    "format": "pdf",
    "template": { "name": "Invoice" },
    "data": {
      "invoice": { "number": "INV-2041" },
      "customer": { "name": "Marta Tamm" }
    }
  }'
```

</TabItem>
<TabItem label=".NET">

```csharp
using Typefold.Client;

var client = new TypefoldClient(
    new Uri(Environment.GetEnvironmentVariable("PDF_URL")!),
    Environment.GetEnvironmentVariable("API_KEY")!);

byte[] pdf = await client.RenderReportAsync(new RenderReportRequest
{
    Template = TemplateRef.ByName("Invoice"),
    Data = new
    {
        invoice = new { number = "INV-2041" },
        customer = new { name = "Marta Tamm" },
    },
});

await File.WriteAllBytesAsync("invoice.pdf", pdf);
```

</TabItem>
<TabItem label="TypeScript">

```ts
import { writeFile } from "node:fs/promises";
import { TypefoldClient, TemplateRef } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL!,
  apiKey: process.env.API_KEY!,
});

const pdf = await client.renderReport({
  template: TemplateRef.byName("Invoice"),
  data: { invoice: { number: "INV-2041" }, customer: { name: "Marta Tamm" } },
});

await writeFile("invoice.pdf", pdf);
```

</TabItem>
<TabItem label="JavaScript">

```js
import { writeFile } from "node:fs/promises";
import { TypefoldClient, TemplateRef } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL,
  apiKey: process.env.API_KEY,
});

const pdf = await client.renderReport({
  template: TemplateRef.byName("Invoice"),
  data: { invoice: { number: "INV-2041" }, customer: { name: "Marta Tamm" } },
});

await writeFile("invoice.pdf", pdf);
```

</TabItem>
<TabItem label="Python">

```python
import os
from pathlib import Path

from typefold import TypefoldClient, RenderReportRequest, TemplateRef

client = TypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"])

pdf = client.render_report(
    RenderReportRequest(
        template=TemplateRef.by_name("Invoice"),
        data={"invoice": {"number": "INV-2041"}, "customer": {"name": "Marta Tamm"}},
    )
)

Path("invoice.pdf").write_bytes(pdf)
```

</TabItem>
</Tabs>

`data` holds the fields your template uses. The template's current published version is always
used, so clicking **Publish** in Studio changes your next document without a code change.

### How the template is chosen

`template` takes exactly one of these:

| `template`              | Matches                                                                                    |
| ----------------------- | ------------------------------------------------------------------------------------------ |
| `{ "name": "Invoice" }` | Templates with that name, ignoring case.                                                   |
| `{ "id": "..." }`       | The template with that ID.                                                                 |
| `{ "shortid": "..." }`  | Templates with that shortid. Only [imported](/guides/jsreport-import/) templates have one. |

- Only templates that render the requested `format` count. If several match, a published one
  wins, then the most recently updated.
- Two templates in different folders can share a name; a request by that name then gets the one
  edited last. Give templates distinct names, or render by `id`.
- No match, or a match that was never published, answers `404 NOT_FOUND`.

### Choose the language

`locale` is a language tag such as `de-CH`. It picks the template's translation file, a
spreadsheet's number and date formats, and the language recorded in the PDF. Without it,
`en-US` is used, not the locale in the template's `page.json`. See
[Translations](/features/translations/).

## 2. Check the response

Success is `200` with the file as the body: `application/pdf`, the image's type for an
[image](#render-an-image), or `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
for XLSX. Any other status
returns a JSON error whose `message` says what to fix (curl's `--fail-with-body` saves it in
place of the file; the clients throw it). The error format is in the
[HTTP API](/clients/http/).

| Status | Code             | When                                                                                                          | What to do                                                                                |
| ------ | ---------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| 400    | `BAD_REQUEST`    | A field is wrong or unknown, or `pdf` or `test` is sent with `"format": "xlsx"`.                              | Fix the request as `message` says.                                                        |
| 404    | `NOT_FOUND`      | No published template with that name, ID or shortid renders this format.                                      | Check the name, the format, and that the template is published.                           |
| 422    | `RENDER_FAILED`  | The PDF render failed or was cancelled. `error.renderId` names it.                                            | [Read the render](/guides/rendering/#handle-failures) to see why. Do not retry unchanged. |
| 429    | `RATE_LIMITED`   | The workspace is at its render allowances, or is preparing too many reports at once.                          | Send it again later, after `Retry-After` when it is sent.                                 |
| 504    | `RENDER_TIMEOUT` | The PDF was still rendering when the [Reports API wait](/clients/limits/) ran out. `error.renderId` names it. | Follow it with `GET /v1/renders/{renderId}`; do not start another.                        |

Keep your HTTP client's timeout above the Reports API wait. The clients' defaults already are.

A PDF is an ordinary render: it counts against your [render allowances](/clients/limits/),
appears in the render list and sends [webhooks](/guides/webhooks/). An XLSX file creates no
render and sends no webhooks, but is still refused while the workspace is at its allowances.

Add `"test": true` (`Test = true` in .NET, `test=True` in Python) for a free test PDF with a
diagonal "TEST" watermark on every page. It doesn't count against your render allowances; see
[test renders](/guides/rendering/#test-renders). PDF and images only.

To retry a PDF request safely, send an `Idempotency-Key` header (`idempotencyKey` in the .NET
and TypeScript clients, `idempotency_key` in Python). A repeat with the same key returns the
first render instead of making a second one; see
[idempotency keys](/guides/rendering/#idempotency-keys). It has no effect on XLSX.

## Change page settings for one request

`pdf` overrides the template's page and PDF settings for this request only. Leave a field out
to keep the template's value.

<Tabs syncKey="api-client">
<TabItem label="curl">

```sh
curl "$PDF_URL/v1/reports/render" \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  --fail-with-body -o invoice.pdf \
  -d '{
    "format": "pdf",
    "template": { "name": "Invoice" },
    "data": { "invoice": { "number": "INV-2041" } },
    "pdf": {
      "orientation": "landscape",
      "margins": { "topMm": 10, "bottomMm": 10 }
    }
  }'
```

</TabItem>
<TabItem label=".NET">

```csharp
using Typefold.Client;

var client = new TypefoldClient(
    new Uri(Environment.GetEnvironmentVariable("PDF_URL")!),
    Environment.GetEnvironmentVariable("API_KEY")!);

byte[] pdf = await client.RenderReportAsync(new RenderReportRequest
{
    Template = TemplateRef.ByName("Invoice"),
    Data = new { invoice = new { number = "INV-2041" } },
    Pdf = new ReportPdfOptions
    {
        Orientation = Orientation.Landscape,
        Margins = new Margins { TopMm = 10, BottomMm = 10 },
    },
});

await File.WriteAllBytesAsync("invoice.pdf", pdf);
```

</TabItem>
<TabItem label="TypeScript">

```ts
import { writeFile } from "node:fs/promises";
import { Orientation, TypefoldClient, TemplateRef } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL!,
  apiKey: process.env.API_KEY!,
});

const pdf = await client.renderReport({
  template: TemplateRef.byName("Invoice"),
  data: { invoice: { number: "INV-2041" } },
  pdf: { orientation: Orientation.Landscape, margins: { topMm: 10, bottomMm: 10 } },
});

await writeFile("invoice.pdf", pdf);
```

</TabItem>
<TabItem label="JavaScript">

```js
import { writeFile } from "node:fs/promises";
import { Orientation, TypefoldClient, TemplateRef } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL,
  apiKey: process.env.API_KEY,
});

const pdf = await client.renderReport({
  template: TemplateRef.byName("Invoice"),
  data: { invoice: { number: "INV-2041" } },
  pdf: { orientation: Orientation.Landscape, margins: { topMm: 10, bottomMm: 10 } },
});

await writeFile("invoice.pdf", pdf);
```

</TabItem>
<TabItem label="Python">

```python
import os
from pathlib import Path

from typefold import (
    Margins,
    Orientation,
    TypefoldClient,
    RenderReportRequest,
    ReportPdfOptions,
    TemplateRef,
)

client = TypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"])

pdf = client.render_report(
    RenderReportRequest(
        template=TemplateRef.by_name("Invoice"),
        data={"invoice": {"number": "INV-2041"}},
        pdf=ReportPdfOptions(
            orientation=Orientation.LANDSCAPE,
            margins=Margins(top_mm=10, bottom_mm=10),
        ),
    )
)

Path("invoice.pdf").write_bytes(pdf)
```

</TabItem>
</Tabs>

What `pdf` can change:

- **Paper:** `pageSize` (`A3`, `A4`, `A5`, `Letter`, `Legal` or a size in millimetres),
  `orientation`, `margins` (sides you leave out keep their value) and `preferCssPageSize`. See
  [Build a template](/guides/first-template/).
- **Pages:** `pageRanges` keeps only some pages, such as `1-5, 8, 11-`; page numbers still count
  the whole document. `operations` replaces the template's pages from other templates and PDF
  files, and `[]` adds none; see [Combine templates](/features/combine-templates/).
- **See-through content:** `opaqueFills` draws CSS opacity and translucent colours at full
  strength.
- **Watermark:** `watermark` draws text such as `DRAFT` across every page; see
  [Add a watermark](#add-a-watermark).
- **PDF standards and security:** `metadata`, `pdfa`, `pdfua`, `attachments`, `encryption` and
  `signature`. `metadata`, `encryption` and `signature` apply over the template's values one
  field at a time. See [PDF standards and security](/guides/pdf-standards/).

Values in `pdf` are used as written: only the template's own values fill `{{path}}`
placeholders. Every field and its limits are in the [API reference](/reference/api/).

## Add a watermark

`pdf.watermark` draws text such as `DRAFT`, `COPY` or `PAID` across every page, in front of the
content. Only `text` is required.

<Tabs syncKey="api-client">
<TabItem label="curl">

```sh
curl "$PDF_URL/v1/reports/render" \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  --fail-with-body -o invoice.pdf \
  -d '{
    "format": "pdf",
    "template": { "name": "Invoice" },
    "data": { "invoice": { "number": "INV-2041" } },
    "pdf": { "watermark": { "text": "COPY" } }
  }'
```

</TabItem>
<TabItem label=".NET">

```csharp
using Typefold.Client;

var client = new TypefoldClient(
    new Uri(Environment.GetEnvironmentVariable("PDF_URL")!),
    Environment.GetEnvironmentVariable("API_KEY")!);

byte[] pdf = await client.RenderReportAsync(new RenderReportRequest
{
    Template = TemplateRef.ByName("Invoice"),
    Data = new { invoice = new { number = "INV-2041" } },
    Pdf = new ReportPdfOptions { Watermark = new PdfWatermark { Text = "COPY" } },
});

await File.WriteAllBytesAsync("invoice.pdf", pdf);
```

</TabItem>
<TabItem label="TypeScript">

```ts
import { writeFile } from "node:fs/promises";
import { TypefoldClient, TemplateRef } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL!,
  apiKey: process.env.API_KEY!,
});

const pdf = await client.renderReport({
  template: TemplateRef.byName("Invoice"),
  data: { invoice: { number: "INV-2041" } },
  pdf: { watermark: { text: "COPY" } },
});

await writeFile("invoice.pdf", pdf);
```

</TabItem>
<TabItem label="JavaScript">

```js
import { writeFile } from "node:fs/promises";
import { TypefoldClient, TemplateRef } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL,
  apiKey: process.env.API_KEY,
});

const pdf = await client.renderReport({
  template: TemplateRef.byName("Invoice"),
  data: { invoice: { number: "INV-2041" } },
  pdf: { watermark: { text: "COPY" } },
});

await writeFile("invoice.pdf", pdf);
```

</TabItem>
<TabItem label="Python">

```python
import os
from pathlib import Path

from typefold import (
    PdfWatermark,
    RenderReportRequest,
    ReportPdfOptions,
    TemplateRef,
    TypefoldClient,
)

client = TypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"])

pdf = client.render_report(
    RenderReportRequest(
        template=TemplateRef.by_name("Invoice"),
        data={"invoice": {"number": "INV-2041"}},
        pdf=ReportPdfOptions(watermark=PdfWatermark(text="COPY")),
    )
)

Path("invoice.pdf").write_bytes(pdf)
```

</TabItem>
</Tabs>

Its colour, opacity, angle and size can be changed too; the fields and their defaults are under
[Watermarks](/guides/rendering/#watermarks). Like every `pdf` option, it is for PDFs and images
only: an Excel request with `pdf` answers `400 BAD_REQUEST`.

## Render an image

Set `"format"` to `"png"`, `"jpeg"` or `"webp"` to get one page of a PDF template as an image.
`image` picks the page and the width:

<Tabs syncKey="api-client">
<TabItem label="curl">

```sh
curl "$PDF_URL/v1/reports/render" \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  --fail-with-body -o invoice.png \
  -d '{
    "format": "png",
    "template": { "name": "Invoice" },
    "data": { "invoice": { "number": "INV-2041" } },
    "image": { "page": 1, "width": 400 }
  }'
```

</TabItem>
<TabItem label=".NET">

```csharp
using Typefold.Client;

var client = new TypefoldClient(
    new Uri(Environment.GetEnvironmentVariable("PDF_URL")!),
    Environment.GetEnvironmentVariable("API_KEY")!);

byte[] png = await client.RenderReportAsync(new RenderReportRequest
{
    Format = RenderFormat.Png,
    Template = TemplateRef.ByName("Invoice"),
    Data = new { invoice = new { number = "INV-2041" } },
    Image = new ImageOptions { Page = 1, Width = 400 },
});

await File.WriteAllBytesAsync("invoice.png", png);
```

</TabItem>
<TabItem label="TypeScript">

```ts
import { writeFile } from "node:fs/promises";
import { RenderFormat, TypefoldClient, TemplateRef } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL!,
  apiKey: process.env.API_KEY!,
});

const png = await client.renderReport({
  format: RenderFormat.Png,
  template: TemplateRef.byName("Invoice"),
  data: { invoice: { number: "INV-2041" } },
  image: { page: 1, width: 400 },
});

await writeFile("invoice.png", png);
```

</TabItem>
<TabItem label="JavaScript">

```js
import { writeFile } from "node:fs/promises";
import { RenderFormat, TypefoldClient, TemplateRef } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL,
  apiKey: process.env.API_KEY,
});

const png = await client.renderReport({
  format: RenderFormat.Png,
  template: TemplateRef.byName("Invoice"),
  data: { invoice: { number: "INV-2041" } },
  image: { page: 1, width: 400 },
});

await writeFile("invoice.png", png);
```

</TabItem>
<TabItem label="Python">

```python
import os
from pathlib import Path

from typefold import ImageOptions, RenderFormat, RenderReportRequest, TemplateRef, TypefoldClient

client = TypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"])

png = client.render_report(
    RenderReportRequest(
        template=TemplateRef.by_name("Invoice"),
        data={"invoice": {"number": "INV-2041"}},
        format=RenderFormat.PNG,
        image=ImageOptions(page=1, width=400),
    )
)

Path("invoice.png").write_bytes(png)
```

</TabItem>
</Tabs>

The response is the image, as `image/png`, `image/jpeg` or `image/webp`. The `image` fields, the
size of a social card and the limits are under
[Render an image](/guides/rendering/#render-an-image). `pdf` options, such as a watermark, and
`test` work as for a PDF; `encryption`, `signature`, `attachments`, `pdfa` and `pdfua` answer
`400 BAD_REQUEST`. An image is an ordinary render and counts as one document.

## Get an Excel file

Set `"format": "xlsx"` (`ReportFormat.Xlsx` in the .NET and TypeScript clients,
`ReportFormat.XLSX` in Python). The response is the `.xlsx` file. Which templates render which
format:

| Template                                                                    | Renders     |
| --------------------------------------------------------------------------- | ----------- |
| [Spreadsheet template](/guides/spreadsheets/) (`sheets.json`)               | XLSX or PDF |
| [Workbook template](/guides/spreadsheets/) (uses an `.xlsx` workspace file) | XLSX only   |
| HTML or component template                                                  | PDF only    |

A template that renders PDF also renders [images](#render-an-image). Asking for a format the
template does not render answers `404 NOT_FOUND`. `pdf` options and
`test` are for PDFs and images only.

## Find your reports

`GET /v1/reports` lists every template in the workspace, sorted by name, with the formats it
renders.

<Tabs syncKey="api-client">
<TabItem label="curl">

```sh
curl "$PDF_URL/v1/reports" -H "x-api-key: $API_KEY" --fail-with-body
```

</TabItem>
<TabItem label=".NET">

```csharp
using Typefold.Client;

var client = new TypefoldClient(
    new Uri(Environment.GetEnvironmentVariable("PDF_URL")!),
    Environment.GetEnvironmentVariable("API_KEY")!);

foreach (var report in await client.ListReportsAsync())
{
    Console.WriteLine($"{report.Name}: {string.Join(", ", report.Formats)}");
}
```

</TabItem>
<TabItem label="TypeScript">

```ts
import { TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL!,
  apiKey: process.env.API_KEY!,
});

for (const report of await client.listReports()) {
  console.log(`${report.name}: ${report.formats.join(", ")}`);
}
```

</TabItem>
<TabItem label="JavaScript">

```js
import { TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL,
  apiKey: process.env.API_KEY,
});

for (const report of await client.listReports()) {
  console.log(`${report.name}: ${report.formats.join(", ")}`);
}
```

</TabItem>
<TabItem label="Python">

```python
import os

from typefold import TypefoldClient

client = TypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"])

for report in client.list_reports():
    print(f"{report.name}: {', '.join(report.formats)}")
```

</TabItem>
</Tabs>

```json
{
  "items": [
    {
      "id": "0f5b7c1e-6a43-4f7e-9d1b-1c2a3b4c5d6e",
      "name": "Invoice",
      "formats": ["pdf"],
      "published": true,
      "folderPath": "Invoices"
    }
  ]
}
```

Use `id` or `name` in `template`. `published` says whether the template has a published version;
only published templates render. `formats` comes from the published version, or from the draft
if it was never published. Imported templates also have a `shortid`.

## Get the data schema

`GET /v1/reports/data-schema` returns the `data` a published template expects, as
[JSON Schema](https://json-schema.org/), so you can generate types or check your data. Pass
`format` and one of `name`, `id` or `shortid`; the template is
[chosen the same way](#how-the-template-is-chosen) as for a render.

<Tabs syncKey="api-client">
<TabItem label="curl">

```sh
curl -G "$PDF_URL/v1/reports/data-schema" \
  -H "x-api-key: $API_KEY" \
  --fail-with-body \
  --data-urlencode "format=pdf" \
  --data-urlencode "name=Invoice"
```

</TabItem>
<TabItem label=".NET">

```csharp
using Typefold.Client;

var client = new TypefoldClient(
    new Uri(Environment.GetEnvironmentVariable("PDF_URL")!),
    Environment.GetEnvironmentVariable("API_KEY")!);

var schema = await client.GetReportDataSchemaAsync(ReportFormat.Pdf, TemplateRef.ByName("Invoice"));

Console.WriteLine(schema);
```

</TabItem>
<TabItem label="TypeScript">

```ts
import { TypefoldClient, ReportFormat, TemplateRef } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL!,
  apiKey: process.env.API_KEY!,
});

const schema = await client.getReportDataSchema(ReportFormat.Pdf, TemplateRef.byName("Invoice"));

console.log(JSON.stringify(schema, null, 2));
```

</TabItem>
<TabItem label="JavaScript">

```js
import { TypefoldClient, ReportFormat, TemplateRef } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL,
  apiKey: process.env.API_KEY,
});

const schema = await client.getReportDataSchema(ReportFormat.Pdf, TemplateRef.byName("Invoice"));

console.log(JSON.stringify(schema, null, 2));
```

</TabItem>
<TabItem label="Python">

```python
import json
import os

from typefold import TypefoldClient, ReportFormat, TemplateRef

client = TypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"])

schema = client.get_report_data_schema(ReportFormat.PDF, TemplateRef.by_name("Invoice"))

print(json.dumps(schema, indent=2))
```

</TabItem>
</Tabs>

How the schema is built:

- **Spreadsheet templates:** from the sections and columns. Each section's data is a required
  array; each column is an optional value typed by its format.
- **Other templates:** from the sample data published with the version. A property is
  `required` only when every sample object has it. Without sample data the schema is `{}`.

Renders are not checked against the schema, and values a template script adds do not appear in
it.

## Make many reports

Send one request per document; they can run in parallel. A request answered with
`429 RATE_LIMITED` can be sent again later, and the clients do this for you (3 times by
default).

The Reports API has no batches. To create many PDFs with one request, use a
[batch](/guides/batch-rendering/) in the Renders API. Each batch item names a template version or
sends its own document, not a template name.

## Next steps

- [Build a template](/guides/first-template/): paper, headers, footers, page numbers and page
  breaks.
- [Spreadsheet templates](/guides/spreadsheets/): Excel output.
- [API reference](/reference/api/): every Reports API field and its limits.

---

# Spreadsheet templates

Source: https://docs.typefold.dev/guides/spreadsheets/

Two kinds of template turn your data into an Excel (XLSX) file. Pick one:

- **[Spreadsheet template](#spreadsheet-templates)**: you list the columns in `sheets.json` and
  get a plain table, as XLSX or as a PDF. Start here if a plain table is enough.
- **[Workbook template](#workbook-templates)**: you design the `.xlsx` in Excel, with your own
  styles, merged cells, formulas and charts, and type Handlebars into its cells. It renders XLSX
  only.

:::note
XLSX comes from the [Reports API](/guides/reports/) (render a template by name) and from
template previews. The Renders API and batches produce PDFs only.
:::

## Before you start

- Access to Studio.
- An [API key](/clients/http/) with `render:create` and `template:read` (plus `render:read` for
  PDFs).
- curl or a client library, set up as in the [quickstart](/start/quickstart/).

## Spreadsheet templates

### 1. Create the template

In Studio, open **Workspace → Editor** and choose **+ → New entity → Template**. Enter the
**Template name** `SalesReport`, set **Start with** to **Spreadsheet (XLSX and PDF tables)** and
click **Create template**. Studio creates a **SalesReport** folder with the template and a
`sample.json` for previews, and opens `sheets.json`, which describes the table.

### 2. Describe the columns

Each sheet has sections. A section reads an array from your data (`source`) and writes one row
per item, with one column per value. Replace `sheets.json` with:

```json title="sheets.json"
{
  "type": "sheets",
  "sheets": [
    {
      "name": "Sales",
      "sections": [
        {
          "title": "Sold goods",
          "source": "Data.reportRows",
          "columns": [
            { "header": "Service", "value": "serviceCode", "format": "text" },
            { "header": "Sold on", "value": "soldOn", "format": "date" },
            { "header": "Amount", "value": "sum", "format": "decimal", "width": 16 }
          ]
        }
      ]
    }
  ]
}
```

Then open `sample.json` in the **SalesReport** folder and replace it with matching data:

```json title="sample.json"
{
  "Data": {
    "reportRows": [
      { "serviceCode": "SRV-01", "soldOn": "2026-09-28", "sum": 480.5 },
      { "serviceCode": "SRV-02", "soldOn": "2026-09-29", "sum": 99 }
    ]
  }
}
```

### 3. Preview and publish

Save both files (**Ctrl+S**, or **Cmd+S** on macOS), go back to the **SalesReport** template and
click **Update preview**. You should see a bold title row, a header row on a light blue fill,
then one row per item. **Download XLSX** above the preview saves the file. Click **Publish** to
make this version the one your app renders.

### 4. Render it from your app

<Tabs syncKey="api-client">
<TabItem label="curl">

```sh
curl "$PDF_URL/v1/reports/render" \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  -o sales.xlsx \
  -d '{
    "format": "xlsx",
    "template": { "name": "SalesReport" },
    "data": { "Data": { "reportRows": [{ "serviceCode": "SRV-01", "soldOn": "2026-09-28", "sum": 480.5 }] } }
  }'
```

</TabItem>
<TabItem label=".NET">

```csharp
using Typefold.Client;

var client = new TypefoldClient(
    new Uri(Environment.GetEnvironmentVariable("PDF_URL")!),
    Environment.GetEnvironmentVariable("API_KEY")!);

byte[] xlsx = await client.RenderReportAsync(new RenderReportRequest
{
    Format = ReportFormat.Xlsx,
    Template = TemplateRef.ByName("SalesReport"),
    Data = new
    {
        Data = new
        {
            reportRows = new[]
            {
                new { serviceCode = "SRV-01", soldOn = "2026-09-28", sum = 480.5 },
            },
        },
    },
});

await File.WriteAllBytesAsync("sales.xlsx", xlsx);
```

</TabItem>
<TabItem label="TypeScript">

```ts
import { writeFile } from "node:fs/promises";
import { TypefoldClient, ReportFormat, TemplateRef } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL!,
  apiKey: process.env.API_KEY!,
});

const xlsx = await client.renderReport({
  format: ReportFormat.Xlsx,
  template: TemplateRef.byName("SalesReport"),
  data: {
    Data: { reportRows: [{ serviceCode: "SRV-01", soldOn: "2026-09-28", sum: 480.5 }] },
  },
});

await writeFile("sales.xlsx", xlsx);
```

</TabItem>
<TabItem label="JavaScript">

```js
import { writeFile } from "node:fs/promises";
import { TypefoldClient, ReportFormat, TemplateRef } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL,
  apiKey: process.env.API_KEY,
});

const xlsx = await client.renderReport({
  format: ReportFormat.Xlsx,
  template: TemplateRef.byName("SalesReport"),
  data: {
    Data: { reportRows: [{ serviceCode: "SRV-01", soldOn: "2026-09-28", sum: 480.5 }] },
  },
});

await writeFile("sales.xlsx", xlsx);
```

</TabItem>
<TabItem label="Python">

```python
import os
from pathlib import Path

from typefold import (
    TypefoldClient,
    RenderReportRequest,
    ReportFormat,
    TemplateRef,
)

client = TypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"])

xlsx = client.render_report(
    RenderReportRequest(
        template=TemplateRef.by_name("SalesReport"),
        data={
            "Data": {
                "reportRows": [
                    {"serviceCode": "SRV-01", "soldOn": "2026-09-28", "sum": 480.5},
                ],
            },
        },
        format=ReportFormat.XLSX,
    )
)

Path("sales.xlsx").write_bytes(xlsx)
```

</TabItem>
</Tabs>

The response is the file, saved here as `sales.xlsx`.

### 5. Get the same table as a PDF

Send `"format": "pdf"` instead and save the response as `sales.pdf`. In Studio, switch **Output**
in the preview toolbar from **XLSX** to **PDF** and click **Update preview**.

The PDF lays out the tables for you:

- Each sheet starts on a new page, headed by its name. Section titles become subheadings.
- Numbers are right-aligned and formatted for the request's `locale`, without thousands
  separators: `decimal` with two decimal places, `number` with as many as it needs. Dates show
  the locale's numeric date, in UTC.
- Columns share the page width in proportion to their `width` (15 when not set).
- The page follows the section with the most columns: A4 portrait, A4 landscape above 5 columns,
  A3 landscape above 10, with 10 mm margins.
- The PDF's title is the template's name and its language is the `locale`.

`page.json` does not apply to a spreadsheet template. To change the page, title, PDF/A or PDF/UA,
send `pdf` options with the request; `pdf.metadata.title` replaces the template-name title. The
fields are in the [API reference](/reference/api/).

```json
{
  "format": "pdf",
  "template": { "name": "SalesReport" },
  "data": { "Data": { "reportRows": [] } },
  "locale": "de-CH",
  "pdf": {
    "pageSize": "A4",
    "orientation": "landscape",
    "metadata": { "title": "Sales, September" }
  }
}
```

### sheets.json fields

| Object  | Field      | Value                                                                                         |
| ------- | ---------- | --------------------------------------------------------------------------------------------- |
| root    | `type`     | `"sheets"`.                                                                                   |
| root    | `sheets`   | 1 to 10 sheets, each a worksheet in order.                                                    |
| sheet   | `name`     | The tab name. 1 to 31 characters, none of `[ ] * ? : / \`, unique ignoring case.              |
| sheet   | `sections` | 1 to 20 sections, written one below another with a blank row between them.                    |
| section | `title`    | Optional. A bold title row above the section.                                                 |
| section | `source`   | Data path of the section's array, such as `Data.reportRows`.                                  |
| section | `columns`  | 1 to 50 columns.                                                                              |
| column  | `header`   | The header text.                                                                              |
| column  | `value`    | Data path inside each array item, such as `sum` or `customer.name`.                           |
| column  | `format`   | `text`, `number`, `decimal` or `date`. See [cell formats](#cell-formats).                     |
| column  | `width`    | Optional. 5 to 100 (Excel character units). Without it the column fits its header (12 to 60). |

- `title` and `header` are text of up to 200 characters, or a label per language picked by the
  request's `locale`; see [translations](/features/translations/).
- A column's width is the widest set for it across the sheet's sections.
- A section with no items still writes its title and header.
- Unknown fields are refused when you save.
- A data path is property names joined by dots, up to 200 characters. Names start with a
  letter, `_` or `$`, then letters, digits, `_` or `$`. A number after the first name reads an
  array element, such as `lines.0.amount`. `__proto__`, `constructor` and `prototype` are not
  allowed.
- A `value` that does not exist gives an empty cell. A `source` that is not an array fails the
  render with `400 BAD_REQUEST`, such as `Section Data.reportRows must resolve to an array.`

### Cell formats

| Format    | Send                                                                   | Cell                                        |
| --------- | ---------------------------------------------------------------------- | ------------------------------------------- |
| `text`    | Any value. Numbers and booleans become text.                           | Text. A value starting with `=` stays text. |
| `number`  | A JSON number.                                                         | A number in Excel's General format.         |
| `decimal` | A JSON number.                                                         | A number shown with two decimal places.     |
| `date`    | An ISO 8601 date, such as `2026-09-28` or `2026-09-28T14:30:00+02:00`. | A real Excel date in the short date format. |

- A missing value, `null` or `""` gives an empty cell in every format.
- `number` and `decimal` refuse strings such as `"12.50"`. Send amounts as JSON numbers.
- A date must be a real calendar date. A time without an offset is read as UTC. The cell keeps
  the time, but shows the date only.
- A value that does not fit its format fails the render with `400 BAD_REQUEST` naming the cell,
  such as `Cell C3 requires a number.` In a PDF the cell is named by its `value` and row, such as
  `Cell sum in row 3 requires a number.`

## Workbook templates

A workbook template fills a copy of an `.xlsx` you designed. Styles, merged cells, column widths,
formulas and charts are kept.

### 1. Design the workbook in Excel

Lay out the file as you want it and type Handlebars where data goes. To repeat a row once per
item, open `{{#each}}` in its first cell and close it in its last:

|       | A                                            | B                      |
| ----- | -------------------------------------------- | ---------------------- |
| **1** | Service                                      | Quantity               |
| **2** | `{{#each Data.rows as \|row\|}}{{row.code}}` | `{{row.qty}}{{/each}}` |
| **3** | `Total {{Data.total}}`                       | `=SUM(B2:B2)`          |

Rows below a repeated row move down, and formulas that point at it grow with it. With two items,
the total moves to row 4 and its formula becomes `=SUM(B2:B3)`.

### 2. Upload it as a template

In **Workspace → Editor**, choose **+ → New entity → Template**. Enter a **Template name**, set
**Start with** to **Excel workbook (XLSX)**, drop your `.xlsx` into **Workbook** and click
**Create template**. Studio saves the `.xlsx` as a file beside the template and sets the
template's `template.html` to `{{{xlsxPrint}}}`. Leave it as it is unless you add
[row commands](#row-commands).

Open the `.xlsx` in the explorer to see its cells, Handlebars included. Double-click a cell (or
press **Enter**) to change it, then save. To use another workbook, pick it in the **Workbook**
menu of the preview toolbar; it lists the `.xlsx` files in and below the template's folder.

### 3. Preview with sample data, then publish

Choose **+ → New entity → Sample data**, enter a **Name** and click **Create entity**. Replace
the `{}` in the new file with data such as this and save it:

```json
{
  "Data": {
    "rows": [
      { "code": "A", "qty": 2 },
      { "code": "C", "qty": 3 }
    ],
    "total": 5
  }
}
```

Go back to the template, pick the file under **Data** in the preview toolbar and click
**Update preview**. You should see the filled workbook with your styles, merged cells and
formulas. Save the template, then click **Publish**. Publishing copies the workbook into the
version, so after you change the `.xlsx`, publish again.

### 4. Render it

Use the call from [step 4 above](#4-render-it-from-your-app) with your workbook template's name
and data.

### Handlebars in cells

| In a cell                                                                 | Result                                                        |
| ------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `{{customer.name}}`                                                       | The value. Text around it is kept, such as `Total {{total}}`. |
| `{{#each rows}}` in one cell, `{{/each}}` in a later cell of the same row | The row repeats once per item.                                |
| `{{#each rows}}` in one row, `{{/each}}` in a later row                   | The block of rows repeats once per item.                      |
| `{{#each columns vertical=true}}` and `{{/each}}` in the same column      | The column repeats once per item, to the right.               |
| `{{#each}}` and `{{/each}}` in the same cell                              | The text repeats inside that one cell.                        |
| `{{xlsxCType t="n"}}` anywhere in the cell                                | The cell is a number. `t="b"` makes a boolean, `t="s"` text.  |

- A cell whose whole text is one expression takes the value's type: a number or boolean writes
  a numeric or boolean cell, not text.
- Formulas, merged cells, conditional formatting and data validation follow the cells they
  point at. Excel recalculates formulas when it opens the file.
- To fit a column's width to its content, add a note to its cell in row 1 containing
  `{{xlsxColAutofit}}`. `{{xlsxColAutofit all=true}}` fits every column of the sheet. The note
  is removed from the output.
- Handlebars in a chart title renders too, and `{{xlsxChart}}` there fills the chart from your
  data; see [Excel charts](/features/charts/).
- Your `helpers.js` helpers, the built-in helpers and translations work in cells; see
  [Handlebars templates](/templates/handlebars/) and [translations](/features/translations/).

### Row commands

For changes cells cannot express, the template's `template.html` can patch the workbook with
commands:

| Command                                                                                                          | Effect                                                        |
| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `{{#xlsxAdd "xl/worksheets/sheet1.xml" "worksheet.sheetData[0].row"}}<row ...>...</row>{{/xlsxAdd}}`             | Adds one `<row>` to the sheet.                                |
| `{{xlsxRemove "xl/worksheets/sheet1.xml" "worksheet.sheetData[0].row" 0}}`                                       | Removes the row at that position in the sheet's list of rows. |
| `{{#xlsxReplace "xl/worksheets/sheet1.xml" "worksheet.mergeCells"}}<mergeCells>...</mergeCells>{{/xlsxReplace}}` | Replaces the sheet's merged cells, or adds them.              |
| `{{#xlsxReplace "xl/styles.xml"}}<styleSheet>...</styleSheet>{{/xlsxReplace}}`                                   | Replaces the workbook's styles.                               |
| `{{{xlsxPrint}}}`                                                                                                | Marks the template as a command template. Prints nothing.     |

For example, with a `helpers.js` helper that turns the item's position into a row number:

```js title="helpers.js"
function rowNumber(index) {
  return index + 2;
}
```

```handlebars title="template.html"
{{#each Data.reportRows}}
  {{#xlsxAdd "xl/worksheets/sheet1.xml" "worksheet.sheetData[0].row"}}
    <row r="{{rowNumber @index}}">
      <c r="A{{rowNumber @index}}" t="inlineStr"><is><t>{{serviceCode}}</t></is></c>
      <c r="B{{rowNumber @index}}"><v>{{sum}}</v></c>
    </row>
  {{/xlsxAdd}}
{{/each}}
{{{xlsxPrint}}}
```

- Cells render first; commands then change the result.
- Commands can target only `xl/styles.xml` and the workbook's existing
  `xl/worksheets/sheetN.xml` parts, with the targets in the table.
- `xlsxRemove` counts from 0 in the rows the sheet holds (with rows added before it), not Excel
  row numbers.
- Each added `<row>` sets its Excel row number in `r` (1 to 1,048,576). Rows are sorted by it,
  and a row with the same number as another replaces it.
- Write values with `{{ }}`, not `{{{ }}}`, so text such as `A&B` stays valid XML.
- A replacement keeps only its root element; text around it is dropped.
- When the cells hold no Handlebars, `template.html` must call `xlsxPrint` and produce at least
  one command, unless it is exactly `{{{xlsxPrint}}}`, which returns the workbook unchanged.

## Create templates through the API

- A spreadsheet template's `content.composition.root` is the `sheets.json` object. `content.settings`
  is still required, though a spreadsheet does not use it.
- A workbook template's `.xlsx` is a [workspace file](/templates/overview/) (uploading needs the
  `asset:manage` scope), named by its path in the draft's `workbook` field.
- `GET /v1/reports/data-schema` returns the JSON Schema of the data a template reads; for a
  spreadsheet template it is built from its sections and columns.

Endpoints and fields are in the [API reference](/reference/api/).

## Limits and errors

| Limit                                 | Value                                | When exceeded                                                       |
| ------------------------------------- | ------------------------------------ | ------------------------------------------------------------------- |
| Spreadsheet XLSX cells per render     | 500,000, counting titles and headers | `400 LIMIT_EXCEEDED`: `Excel report exceeds the row or cell limit.` |
| Spreadsheet XLSX rows per sheet       | 1,048,576 (Excel's limit)            | `400 LIMIT_EXCEEDED`: `Excel report exceeds the row or cell limit.` |
| Spreadsheet PDF data cells per render | 50,000                               | `400 LIMIT_EXCEEDED`: `PDF report is too large.`                    |
| Spreadsheet PDF table size            | 8 MiB                                | `400 LIMIT_EXCEEDED`: `PDF report is too large.`                    |
| Files inside a workbook `.xlsx`       | 1,000                                | `400 LIMIT_EXCEEDED`                                                |
| One file inside a workbook `.xlsx`    | 50 MiB                               | `400 LIMIT_EXCEEDED`                                                |
| Workbook `.xlsx` uncompressed         | 100 MiB                              | `400 LIMIT_EXCEEDED`                                                |
| Row commands per render               | 20,000                               | `400 UNSUPPORTED_FEATURE`                                           |

Workbook templates also fail with:

- `400 BAD_REQUEST` when the `.xlsx` is not a valid workbook, or a command is malformed
  (`XLSX template produced an invalid command.`).
- `400 UNSUPPORTED_FEATURE` when `template.html` has no `xlsxPrint` or produced no commands while
  the cells hold no Handlebars, or a command targets an unsupported part, has an invalid row
  number or removal index, or does not hold exactly one `<row>` or `<mergeCells>`.

Other limits are in [limits](/clients/limits/).

## Next steps

- [Render a report by name](/guides/reports/): more on the Reports API.
- [Excel charts](/features/charts/): fill workbook charts from your data.
- [Translations](/features/translations/): labels per language and number and date formatting.

---

# Save PDFs to your own bucket

Source: https://docs.typefold.dev/guides/storage-destinations/

A storage destination is a bucket of yours that Typefold uploads finished PDFs to. Save it once
in your workspace, then name it in a render request. The PDF is in your bucket before the render
counts as succeeded.

Any S3-compatible service works, such as Amazon S3, Cloudflare R2, Backblaze B2, Hetzner Object
Storage and MinIO.

## Before you start

- **A bucket** and an **access key** for it from your storage provider. The key needs permission
  to write objects (`PutObject`); permission to delete them is optional. How to create one:
  [Amazon S3](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html),
  [Cloudflare R2](https://developers.cloudflare.com/r2/api/tokens/),
  [Backblaze B2](https://www.backblaze.com/docs/cloud-storage-application-keys),
  [Hetzner Object Storage](https://docs.hetzner.com/storage/object-storage/getting-started/generating-s3-keys/),
  [MinIO](https://min.io/docs/minio/linux/administration/identity-access-management/minio-user-management.html).
- **A workspace owner or admin** to save the destination in Studio, or an
  [API key](/clients/http/#scopes) with `destination:manage`. Rendering to a saved destination
  needs only `render:create`.
- **`PDF_URL` and `API_KEY`** set in your terminal as in the [quickstart](/start/quickstart/).

## 1. Save the destination

Typefold makes a test upload before it saves the destination: it writes an object named
`.typefold-connection-test` under the prefix, then deletes it. If the key may not delete, the
object stays. If the test fails, nothing is saved and the answer says why, so every saved
destination is known to work.

<Tabs syncKey="api-client">
<TabItem label="curl">

```sh
curl -X POST "$PDF_URL/v1/storage-destinations" \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "Invoices",
    "endpoint": "https://s3.example.com",
    "region": "eu-central-1",
    "bucket": "example-invoices",
    "prefix": "pdf",
    "accessKeyId": "<access key ID>",
    "secretAccessKey": "<secret access key>"
  }'
```

The response holds the destination, without its secret access key. A failed test upload answers
`400 BAD_REQUEST` with the reason.

</TabItem>
<TabItem label=".NET">

The client cannot save destinations. In Studio, open **Manage → Storage destinations**, add a
destination and fill in the [fields](#fields). Studio saves it once the test upload succeeds.

</TabItem>
<TabItem label="TypeScript">

The client cannot save destinations. In Studio, open **Manage → Storage destinations**, add a
destination and fill in the [fields](#fields). Studio saves it once the test upload succeeds.

</TabItem>
<TabItem label="JavaScript">

The client cannot save destinations. In Studio, open **Manage → Storage destinations**, add a
destination and fill in the [fields](#fields). Studio saves it once the test upload succeeds.

</TabItem>
<TabItem label="Python">

The client cannot save destinations. In Studio, open **Manage → Storage destinations**, add a
destination and fill in the [fields](#fields). Studio saves it once the test upload succeeds.

</TabItem>
</Tabs>

Only owners and admins see **Manage → Storage destinations**.

### Fields

| Field             | Default     | Description                                                                                               |
| ----------------- | ----------- | --------------------------------------------------------------------------------------------------------- |
| `name`            | required    | What render requests call it, up to 120 characters. Unique in the workspace, ignoring case.               |
| `endpoint`        | none        | The service's S3 endpoint; see [endpoints](#endpoints). Leave it out for Amazon S3.                       |
| `region`          | `us-east-1` | The bucket's region. `auto` for Cloudflare R2.                                                            |
| `bucket`          | required    | The bucket's name.                                                                                        |
| `prefix`          | none        | A folder put in front of every object key, such as `pdf`. Up to 512 characters.                           |
| `forcePathStyle`  | `false`     | `true` puts the bucket in the URL's path instead of its host name. MinIO and some other services need it. |
| `accessKeyId`     | required    | The access key's ID.                                                                                      |
| `secretAccessKey` | required    | Stored encrypted and never shown or returned again.                                                       |

### Endpoints

| Service                | `endpoint`                                                   | `region`                 |
| ---------------------- | ------------------------------------------------------------ | ------------------------ |
| Amazon S3              | Leave it out                                                 | The bucket's region      |
| Cloudflare R2          | `https://<account-id>.r2.cloudflarestorage.com`              | `auto`                   |
| Backblaze B2           | `https://s3.<region>.backblazeb2.com`, such as `us-west-004` | The same region          |
| Hetzner Object Storage | `https://<location>.your-objectstorage.com`, such as `fsn1`  | The same location        |
| MinIO and others       | Your server's S3 address, with `"forcePathStyle": true`      | As the service documents |

On the hosted service the endpoint must be an `https://` address on the public internet. A
self-hosted installation can also allow private and `http://` addresses; see
[on your own network](#on-your-own-network).

## 2. Render to it

Add `destination` to a render request with the destination's `name`:

<Tabs syncKey="api-client">
<TabItem label="curl">

```sh
curl "$PDF_URL/v1/renders" \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "templateVersionId": "c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
    "data": { "invoice": { "number": "INV-2041" } },
    "destination": { "name": "Invoices", "path": "2026/{renderId}.pdf" },
    "waitMs": 10000
  }'
```

</TabItem>
<TabItem label=".NET">

```csharp
using Typefold.Client;

var client = new TypefoldClient(
    new Uri(Environment.GetEnvironmentVariable("PDF_URL")!),
    Environment.GetEnvironmentVariable("API_KEY")!);

Render render = await client.CreateRenderAsync(new TemplateVersionRenderRequest
{
    TemplateVersionId = "c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
    Data = new { invoice = new { number = "INV-2041" } },
    Destination = new RenderDestination { Name = "Invoices", Path = "2026/{renderId}.pdf" },
});
render = await client.WaitForRenderAsync(render);

if (render.State == RenderState.Succeeded)
{
    Console.WriteLine(render.Result!.Destination!.Key);
}
```

</TabItem>
<TabItem label="TypeScript">

```ts
import { RenderState, TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL!,
  apiKey: process.env.API_KEY!,
});

let render = await client.createRender({
  templateVersionId: "c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
  data: { invoice: { number: "INV-2041" } },
  destination: { name: "Invoices", path: "2026/{renderId}.pdf" },
});
render = await client.waitForRender(render);

if (render.state === RenderState.Succeeded) {
  console.log(render.result?.destination?.key);
}
```

</TabItem>
<TabItem label="JavaScript">

```js
import { RenderState, TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL,
  apiKey: process.env.API_KEY,
});

let render = await client.createRender({
  templateVersionId: "c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
  data: { invoice: { number: "INV-2041" } },
  destination: { name: "Invoices", path: "2026/{renderId}.pdf" },
});
render = await client.waitForRender(render);

if (render.state === RenderState.Succeeded) {
  console.log(render.result.destination.key);
}
```

</TabItem>
<TabItem label="Python">

```python
import os

from typefold import (
    RenderDestination,
    RenderState,
    TemplateVersionRenderRequest,
    TypefoldClient,
)

client = TypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"])

render = client.create_render(
    TemplateVersionRenderRequest(
        template_version_id="c7e0b9a4-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
        data={"invoice": {"number": "INV-2041"}},
        destination=RenderDestination(name="Invoices", path="2026/{renderId}.pdf"),
    )
)
render = client.wait_for_render(render)

if render.state == RenderState.SUCCEEDED:
    print(render.result.destination.key)
```

</TabItem>
</Tabs>

| `destination` field | Default          | Description                                                                                                                                                                                                                                                                                              |
| ------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`              | required         | A saved destination's name. An unknown name answers `400 BAD_REQUEST`.                                                                                                                                                                                                                                   |
| `path`              | `{renderId}.pdf` | The object's key after the prefix. `{renderId}` is replaced with the render's ID. An [image](/guides/rendering/#render-an-image) defaults to its format's extension, such as `{renderId}.png`. Up to 512 characters; the whole key may be at most 1,024 bytes, or the request answers `400 BAD_REQUEST`. |
| `keepCopy`          | `true`           | `false` keeps no copy in Typefold; see [keep no copy](#keep-no-copy).                                                                                                                                                                                                                                    |

- The object key is the prefix, a slash, then `path`. Both are slash-separated names without a
  leading or trailing slash or `.` and `..` parts. With the destination above, the PDF lands
  at `pdf/2026/<render ID>.pdf`. Without a prefix it is `path` alone.
- An object already at that key is replaced.
- `destination` works on every `POST /v1/renders` request that renders a template version or
  your own HTML, and on [batch](/guides/batch-rendering/) items. Previews, in Studio or with a
  `preview` body, and the [Reports API](/guides/reports/), which returns the file directly, don't
  take it.
- [Webhooks](/guides/webhooks/) are sent as usual. A `render.succeeded` event means the PDF is in
  your bucket.

## 3. Find the PDF

A succeeded render's `result.destination` says where the PDF went:

```json
{
  "id": "0b6f0f8e-3c55-4c1e-a3a7-8d1a6f2c9e41",
  "state": "succeeded",
  "result": {
    "downloadUrl": "https://pdf.example.com/v1/storage/...",
    "expiresAt": "2026-10-08T09:25:13.480Z",
    "destination": {
      "name": "Invoices",
      "key": "pdf/2026/0b6f0f8e-3c55-4c1e-a3a7-8d1a6f2c9e41.pdf"
    },
    "pageCount": 2,
    "outputBytes": 48213,
    "durationMs": 1840
  }
}
```

`key` is the object's full key in the bucket. Typefold still keeps its own copy for
[30 days](/guides/rendering/#retention), which `downloadUrl` and the clients' download methods
fetch.

## Keep no copy

With `"keepCopy": false`, the PDF goes only to your bucket:

- The succeeded render has no `downloadUrl` or `expiresAt`, so the clients' download methods
  raise an error for it, and their render methods that return the PDF refuse `keepCopy: false`
  before creating a render. Create the render and wait for it instead, as in
  [step 2](#2-render-to-it).
- A [batch](/guides/batch-rendering/) with such items cannot be downloaded as one combined PDF:
  that request answers `409 CONFLICT`.
- The render itself, with its `result` and `destination`, is kept as usual.

## If the upload fails

The render then fails, with a `destination_upload_failed` diagnostic whose message names the
cause, such as
`the keys may not write to this bucket or prefix (AccessDenied, HTTP 403)`.

- Timeouts, dropped connections, throttling (`429`, `SlowDown`) and `5xx` answers from the
  service are retried with the render's other [retries](/guides/rendering/#retries). Wrong keys,
  permissions, bucket, region or an unknown host are final: fix the destination or the key's
  permissions, then render again.
- A render still queued when its destination is deleted fails the same way. Renaming the
  destination does not affect renders already created.
- New keys, a new bucket and other changes apply to renders still queued, because the destination
  is read when the PDF is uploaded. Only a new prefix applies to new renders alone: the object
  key is fixed when the render is created.
- A render cancelled, or failed by its time limit, after its upload has started may still leave
  its PDF in your bucket.

## Manage destinations

In Studio, open **Manage → Storage destinations** to change or delete destinations.

- A workspace can have up to 10 destinations. An eleventh answers `409 CONFLICT`.
- Saving a change runs the test upload again, except when you only rename the destination.
- The secret access key is never shown again. Leave the keys out of a change to keep the saved
  ones. Changing the endpoint, region, bucket or
  `forcePathStyle` needs the secret access key again.
- Deleting a destination deletes its saved keys. Objects already in your bucket stay.

With the API, every operation needs the `destination:manage` scope. Request and response fields
are in the [API reference](/reference/api/).

| Operation                              | What it does                                                                                                                                                 |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `POST /v1/storage-destinations`        | Test and save a destination. Answers `201 Created`.                                                                                                          |
| `GET /v1/storage-destinations`         | List all destinations, without secret access keys.                                                                                                           |
| `GET /v1/storage-destinations/{id}`    | Read one destination, without its secret access key.                                                                                                         |
| `PATCH /v1/storage-destinations/{id}`  | Change only the fields you send. `null` removes `endpoint` or `prefix`. Changing `endpoint`, `region`, `bucket` or `forcePathStyle` needs `secretAccessKey`. |
| `DELETE /v1/storage-destinations/{id}` | Delete the destination and its saved keys.                                                                                                                   |

## On your own network

A self-hosted installation can upload to services on private addresses or over plain `http://`,
such as a MinIO server next to it, with `DESTINATION_ALLOW_PRIVATE_NETWORKS=true`; see
[configuration](/self-hosting/configuration/#storage-destinations).

---

# Render email and SMS text

Source: https://docs.typefold.dev/guides/string-rendering/

Send a short text template, such as an email subject, an SMS or a simple HTML email body, together
with your data. The filled-in text comes back in the response. Nothing is stored, no webhooks are
sent, and string renders do not count against your [render allowances](/clients/limits/).

## Before you start

- An API key with the `render:create` scope. See [HTTP API](/clients/http/).
- curl or a client library, set up as in the [quickstart](/start/quickstart/).

## Fill in a text template

Write the text with `{{placeholders}}`. Each one reads a value from `data`, so
`{{customer.name}}` reads `data.customer.name`:

<Tabs syncKey="api-client">
<TabItem label="curl">

```sh
curl "$PDF_URL/v1/renders/string" \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "template": "Hello {{customer.name}}, your ticket is {{ticket.number}}.",
    "data": { "customer": { "name": "Marta" }, "ticket": { "number": "T-123" } }
  }'
```

</TabItem>
<TabItem label=".NET">

```csharp
using Typefold.Client;

var client = new TypefoldClient(
    new Uri(Environment.GetEnvironmentVariable("PDF_URL")!),
    Environment.GetEnvironmentVariable("API_KEY")!);

string content = await client.RenderStringAsync(new RenderStringRequest
{
    Template = "Hello {{customer.name}}, your ticket is {{ticket.number}}.",
    Data = new { customer = new { name = "Marta" }, ticket = new { number = "T-123" } },
});

Console.WriteLine(content);
```

</TabItem>
<TabItem label="TypeScript">

```ts
import { TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL!,
  apiKey: process.env.API_KEY!,
});

const content = await client.renderString({
  template: "Hello {{customer.name}}, your ticket is {{ticket.number}}.",
  data: { customer: { name: "Marta" }, ticket: { number: "T-123" } },
});

console.log(content);
```

</TabItem>
<TabItem label="JavaScript">

```js
import { TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL,
  apiKey: process.env.API_KEY,
});

const content = await client.renderString({
  template: "Hello {{customer.name}}, your ticket is {{ticket.number}}.",
  data: { customer: { name: "Marta" }, ticket: { number: "T-123" } },
});

console.log(content);
```

</TabItem>
<TabItem label="Python">

```python
import os

from typefold import TypefoldClient, RenderStringRequest

client = TypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"])

content = client.render_string(
    RenderStringRequest(
        template="Hello {{customer.name}}, your ticket is {{ticket.number}}.",
        data={"customer": {"name": "Marta"}, "ticket": {"number": "T-123"}},
    )
)

print(content)
```

</TabItem>
</Tabs>

The response is `200` with the text in `content`. The client libraries return `content` directly.

```json
{ "content": "Hello Marta, your ticket is T-123.", "format": "text" }
```

The request takes `template` and `data`, plus the optional `format`, `engine` and `helpers`
described below. Any other field answers `400 BAD_REQUEST`. The full schema is in the
[API reference](/reference/api/).

## Placeholders

A placeholder is a property name, or a dotted path to a nested value:

| Placeholder             | Reads                                                     |
| ----------------------- | --------------------------------------------------------- |
| `{{name}}`              | `data.name`                                               |
| `{{customer.name}}`     | `data.customer.name`                                      |
| `{{invoices.0.number}}` | `number` of the first element of the `invoices` array     |
| `{{ customer.name }}`   | The same as `{{customer.name}}`; outer spaces are ignored |

- Each name starts with a letter, `_` or `$`, followed by letters, digits, `_` or `$`. Keys such
  as `first-name` or `first name` cannot be read; rename them in your data.
- A numeric segment reads an array element: `0`, `1`, `12`, but not `01`. The first segment must
  be a name. A path has at most 20 segments.
- The value must be a string, a number or a boolean. Numbers and booleans are written as
  JavaScript prints them, such as `12.5` and `true`. To get `1,250.50` or `1 250,50`, format the
  value in your application and send it as a string.
- A value that is missing, `null`, an object or an array answers `400 BAD_REQUEST`. Send `""` for
  a value you want blank.
- Text outside `{{ }}` is copied unchanged, including single braces and a stray `}}`. Filled-in
  values are never read as placeholders.
- Every `{{` starts a placeholder, so the result cannot contain a literal `{{`. Blocks such as
  `{{#if}}` and `{{#each}}`, helpers, partials, triple braces `{{{ }}}` and comments answer
  `400 BAD_REQUEST`. Use the [Handlebars engine](#add-conditions-loops-and-helpers) for them.

## Write HTML safely

By default (`"format": "text"`), values are inserted exactly as they are, so a value such as
`<script>` stays markup. When the result goes into HTML, always send `"format": "html"`:

<Tabs syncKey="api-client">
<TabItem label="curl">

```sh
curl "$PDF_URL/v1/renders/string" \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "template": "<p>Hi <b>{{customer.name}}</b>, your order {{order.id}} has shipped.</p>",
    "data": { "customer": { "name": "Tom & Jerry" }, "order": { "id": "A-1009" } },
    "format": "html"
  }'
```

</TabItem>
<TabItem label=".NET">

```csharp
using Typefold.Client;

var client = new TypefoldClient(
    new Uri(Environment.GetEnvironmentVariable("PDF_URL")!),
    Environment.GetEnvironmentVariable("API_KEY")!);

string content = await client.RenderStringAsync(new RenderStringRequest
{
    Template = "<p>Hi <b>{{customer.name}}</b>, your order {{order.id}} has shipped.</p>",
    Data = new
    {
        customer = new { name = "Tom & Jerry" },
        order = new { id = "A-1009" },
    },
    Format = StringFormat.Html,
});

Console.WriteLine(content);
```

</TabItem>
<TabItem label="TypeScript">

```ts
import { TypefoldClient, StringFormat } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL!,
  apiKey: process.env.API_KEY!,
});

const content = await client.renderString({
  template: "<p>Hi <b>{{customer.name}}</b>, your order {{order.id}} has shipped.</p>",
  data: { customer: { name: "Tom & Jerry" }, order: { id: "A-1009" } },
  format: StringFormat.Html,
});

console.log(content);
```

</TabItem>
<TabItem label="JavaScript">

```js
import { TypefoldClient, StringFormat } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL,
  apiKey: process.env.API_KEY,
});

const content = await client.renderString({
  template: "<p>Hi <b>{{customer.name}}</b>, your order {{order.id}} has shipped.</p>",
  data: { customer: { name: "Tom & Jerry" }, order: { id: "A-1009" } },
  format: StringFormat.Html,
});

console.log(content);
```

</TabItem>
<TabItem label="Python">

```python
import os

from typefold import TypefoldClient, RenderStringRequest, StringFormat

client = TypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"])

content = client.render_string(
    RenderStringRequest(
        template="<p>Hi <b>{{customer.name}}</b>, your order {{order.id}} has shipped.</p>",
        data={"customer": {"name": "Tom & Jerry"}, "order": {"id": "A-1009"}},
        format=StringFormat.HTML,
    )
)

print(content)
```

</TabItem>
</Tabs>

```json
{
  "content": "<p>Hi <b>Tom &amp; Jerry</b>, your order A-1009 has shipped.</p>",
  "format": "html"
}
```

With `html`, the characters `&`, `<`, `>`, `"`, `'`, `` ` `` and `=` in values are escaped, so
values are also safe inside quoted or unquoted attributes. Control characters below U+0020, other
than tab and line breaks, become `�` (U+FFFD). The template's own markup is kept as written.

## Add conditions, loops and helpers

The default engine only fills in values. For `{{#if}}`, `{{#each}}` and your own helpers, send
`"engine": "handlebars"` and write the template in
[Handlebars](https://handlebarsjs.com/guide/). Put helpers in `helpers` as JavaScript: every
top-level function becomes a helper, as in a template's `helpers.js`.

<Tabs syncKey="api-client">
<TabItem label="curl">

```sh
curl "$PDF_URL/v1/renders/string" \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "template": "{{#if (isEqual status \"paid\")}}Paid{{else}}Due{{/if}}: {{#each tickets}}{{number}}{{#unless @last}}, {{/unless}}{{/each}}",
    "data": { "status": "paid", "tickets": [{ "number": "T-1" }, { "number": "T-2" }] },
    "engine": "handlebars",
    "helpers": "function isEqual(a, b) { return a === b; }"
  }'
```

</TabItem>
<TabItem label=".NET">

```csharp
using Typefold.Client;

var client = new TypefoldClient(
    new Uri(Environment.GetEnvironmentVariable("PDF_URL")!),
    Environment.GetEnvironmentVariable("API_KEY")!);

string content = await client.RenderStringAsync(new RenderStringRequest
{
    Template = "{{#if (isEqual status \"paid\")}}Paid{{else}}Due{{/if}}: "
        + "{{#each tickets}}{{number}}{{#unless @last}}, {{/unless}}{{/each}}",
    Data = new
    {
        status = "paid",
        tickets = new[] { new { number = "T-1" }, new { number = "T-2" } },
    },
    Engine = StringEngine.Handlebars,
    Helpers = "function isEqual(a, b) { return a === b; }",
});

Console.WriteLine(content);
```

</TabItem>
<TabItem label="TypeScript">

```ts
import { TypefoldClient, StringEngine } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL!,
  apiKey: process.env.API_KEY!,
});

const content = await client.renderString({
  template:
    '{{#if (isEqual status "paid")}}Paid{{else}}Due{{/if}}: ' +
    "{{#each tickets}}{{number}}{{#unless @last}}, {{/unless}}{{/each}}",
  data: { status: "paid", tickets: [{ number: "T-1" }, { number: "T-2" }] },
  engine: StringEngine.Handlebars,
  helpers: "function isEqual(a, b) { return a === b; }",
});

console.log(content);
```

</TabItem>
<TabItem label="JavaScript">

```js
import { TypefoldClient, StringEngine } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL,
  apiKey: process.env.API_KEY,
});

const content = await client.renderString({
  template:
    '{{#if (isEqual status "paid")}}Paid{{else}}Due{{/if}}: ' +
    "{{#each tickets}}{{number}}{{#unless @last}}, {{/unless}}{{/each}}",
  data: { status: "paid", tickets: [{ number: "T-1" }, { number: "T-2" }] },
  engine: StringEngine.Handlebars,
  helpers: "function isEqual(a, b) { return a === b; }",
});

console.log(content);
```

</TabItem>
<TabItem label="Python">

```python
import os

from typefold import TypefoldClient, RenderStringRequest, StringEngine

client = TypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"])

content = client.render_string(
    RenderStringRequest(
        template='{{#if (isEqual status "paid")}}Paid{{else}}Due{{/if}}: '
        "{{#each tickets}}{{number}}{{#unless @last}}, {{/unless}}{{/each}}",
        data={"status": "paid", "tickets": [{"number": "T-1"}, {"number": "T-2"}]},
        engine=StringEngine.HANDLEBARS,
        helpers="function isEqual(a, b) { return a === b; }",
    )
)

print(content)
```

</TabItem>
</Tabs>

This returns `Paid: T-1, T-2`. How the Handlebars engine differs from the default one:

- A missing value prints as empty text instead of answering `400`.
- With `html`, values in `{{ }}` are escaped the Handlebars way and values in `{{{ }}}` are not.
  With `text`, no value is escaped.
- `helpers` is accepted only with this engine; with the default engine it answers `400 BAD_REQUEST`.
- There are no partials, translations or scripts.

## Limits

| Limit                                             | Value                                        | Error                |
| ------------------------------------------------- | -------------------------------------------- | -------------------- |
| Request body                                      | 1,000,000 bytes                              | `413 LIMIT_EXCEEDED` |
| Input: `template`, `helpers` and `data` (as JSON) | 1,000,000 bytes                              | `400 LIMIT_EXCEEDED` |
| Result `content`, in UTF-8                        | 1,000,000 bytes                              | `400 LIMIT_EXCEEDED` |
| Nesting depth of `data`                           | 100 levels                                   | `400 BAD_REQUEST`    |
| Segments in one placeholder path                  | 20                                           | `400 BAD_REQUEST`    |
| `helpers`                                         | 500,000 characters                           | `400 BAD_REQUEST`    |
| Handlebars run                                    | 100 ms CPU time, 16 MiB memory               | `400 LIMIT_EXCEEDED` |
| Handlebars template size                          | 50,000 syntax nodes, nested at most 100 deep | `400 LIMIT_EXCEEDED` |

## Errors

Fix the template or the data and send the request again. Only `429` is worth retrying unchanged.
A request over a [limit](#limits) answers the error in its row, and the message names the limit.
Authentication and license errors are the same as for every endpoint; see
[HTTP API](/clients/http/).

| Status and code    | Message                                                                         | Cause                                               |
| ------------------ | ------------------------------------------------------------------------------- | --------------------------------------------------- |
| `400 BAD_REQUEST`  | `Use {{name}} or {{customer.name}} placeholders with at most 20 path segments.` | A placeholder is malformed or not closed.           |
| `400 BAD_REQUEST`  | `Each placeholder must resolve to a string, number, or boolean.`                | A value is missing, `null`, an object or an array.  |
| `400 BAD_REQUEST`  | `Invalid Handlebars template: …`                                                | Handlebars: the template does not compile.          |
| `400 BAD_REQUEST`  | `helpers.js: …`                                                                 | Handlebars: `helpers` is not valid JavaScript.      |
| `400 BAD_REQUEST`  | `Handlebars render failed: …`                                                   | Handlebars: a helper threw, or a helper is missing. |
| `429 RATE_LIMITED` | `Template scripts are busy. Retry shortly.`                                     | Handlebars: the server is busy. Retry shortly.      |

## Next steps

- [Handlebars templates](/templates/handlebars/): helpers, scripts and partials in full templates.
- [Render a report](/guides/reports/): when you need a PDF instead of text.

---

# Get notified with webhooks

Source: https://docs.typefold.dev/guides/webhooks/

Typefold sends a signed `POST` request to your URL each time a PDF render ends, so you don't
have to poll the [Renders API](/guides/rendering/) for its state.

## Before you start

- **An [API key](/clients/http/)** with `webhook:manage` to register the endpoint, and
  `render:read` for your application to fetch renders.
- **A URL on the public internet** in your application that will receive the events, such as
  `https://example.com/hooks/pdf`. `localhost` and private network addresses are refused; see
  [allowed destinations](#allowed-destinations).
- **`PDF_URL` and `API_KEY`** set in your terminal as in the [quickstart](/start/quickstart/).

## 1. Register an endpoint

Tell Typefold where to send events and which events you want:

<Tabs syncKey="api-client">
<TabItem label="curl">

```sh
curl -X POST "$PDF_URL/v1/webhook-endpoints" \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "url": "https://example.com/hooks/pdf",
    "eventTypes": ["render.succeeded", "render.failed"]
  }'
```

The response holds the endpoint's `id` and its signing `secret`.

</TabItem>
<TabItem label=".NET">

The client cannot register endpoints. In Studio, open **Manage → Webhooks**, click
**Add endpoint**, enter the **Endpoint URL** and pick the **Events**. Studio then shows the
signing secret.

</TabItem>
<TabItem label="TypeScript">

The client cannot register endpoints. In Studio, open **Manage → Webhooks**, click
**Add endpoint**, enter the **Endpoint URL** and pick the **Events**. Studio then shows the
signing secret.

</TabItem>
<TabItem label="JavaScript">

The client cannot register endpoints. In Studio, open **Manage → Webhooks**, click
**Add endpoint**, enter the **Endpoint URL** and pick the **Events**. Studio then shows the
signing secret.

</TabItem>
<TabItem label="Python">

The client cannot register endpoints. In Studio, open **Manage → Webhooks**, click
**Add endpoint**, enter the **Endpoint URL** and pick the **Events**. Studio then shows the
signing secret.

</TabItem>
</Tabs>

The secret is shown only once, so store it with your application straight away. In Studio, only
owners and admins see **Manage → Webhooks**.

## 2. Verify each request

Check every request's signature with your secret before you trust it; see
[signatures](#signatures).

## 3. Store the event, then answer `2xx`

Store or enqueue the event first, then answer with any `2xx` status within 10 seconds. Do slower
work, such as fetching the render, after you have answered. Once Typefold gets a `2xx`, it
does not retry that delivery. Any other answer, or none, makes it send the delivery again; see
[delivery rules and retries](#delivery-rules-and-retries).

## 4. Fetch the render

Events carry no PDF or download link. Read the render named in the event's `data.renderId`, and
download the PDF when it succeeded:

<Tabs syncKey="api-client">
<TabItem label="curl">

```sh
curl "$PDF_URL/v1/renders/b1f3c1d2-7a55-4d0e-9e59-2f3f5c0a9d11" \
  -H "x-api-key: $API_KEY"
```

Download the PDF from `result.downloadUrl`; see [Render a PDF](/guides/rendering/).

</TabItem>
<TabItem label=".NET">

```csharp
using Typefold.Client;

var client = new TypefoldClient(
    new Uri(Environment.GetEnvironmentVariable("PDF_URL")!),
    Environment.GetEnvironmentVariable("API_KEY")!);

// The event's data.renderId.
Render render = await client.GetRenderAsync("b1f3c1d2-7a55-4d0e-9e59-2f3f5c0a9d11");

if (render.State == RenderState.Succeeded)
{
    byte[] pdf = await client.DownloadAsync(render);
    await File.WriteAllBytesAsync("document.pdf", pdf);
}
```

</TabItem>
<TabItem label="TypeScript">

```ts
import { writeFile } from "node:fs/promises";
import { TypefoldClient, RenderState } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL!,
  apiKey: process.env.API_KEY!,
});

// The event's data.renderId.
const render = await client.getRender("b1f3c1d2-7a55-4d0e-9e59-2f3f5c0a9d11");

if (render.state === RenderState.Succeeded) {
  await writeFile("document.pdf", await client.download(render));
}
```

</TabItem>
<TabItem label="JavaScript">

```js
import { writeFile } from "node:fs/promises";
import { TypefoldClient, RenderState } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL,
  apiKey: process.env.API_KEY,
});

// The event's data.renderId.
const render = await client.getRender("b1f3c1d2-7a55-4d0e-9e59-2f3f5c0a9d11");

if (render.state === RenderState.Succeeded) {
  await writeFile("document.pdf", await client.download(render));
}
```

</TabItem>
<TabItem label="Python">

```python
import os
from pathlib import Path

from typefold import TypefoldClient, RenderState

client = TypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"])

# The event's data.renderId.
render = client.get_render("b1f3c1d2-7a55-4d0e-9e59-2f3f5c0a9d11")

if render.state == RenderState.SUCCEEDED:
    Path("document.pdf").write_bytes(client.download(render))
```

</TabItem>
</Tabs>

A `failed` render has an `error` instead; see [Render a PDF](/guides/rendering/).

## Events

| Event              | Sent when                                       |
| ------------------ | ----------------------------------------------- |
| `render.succeeded` | The PDF was stored and can be downloaded.       |
| `render.failed`    | The render failed, after any automatic retries. |
| `render.cancelled` | The render was cancelled before it finished.    |

- Every PDF render sends one event when it ends, however it was created: `POST /v1/renders`, a
  [batch](/guides/batch-rendering/) item, a [Reports API](/guides/reports/) PDF or a PDF
  preview. Excel output and [string rendering](/guides/string-rendering/) send none.
- An endpoint receives only the event types it subscribed to, and only for renders that end after
  it was created.
- A disabled endpoint misses the events of renders that end while it is disabled. They are not
  sent later.
- Events usually go out within a few seconds.

## Event payload

Each delivery is a `POST` with this JSON body:

```json
{
  "id": "5e0c8f5e-4a4c-4f55-9a8a-7f1f9b3f1a2c",
  "type": "render.failed",
  "createdAt": "2026-10-08T09:15:30.123Z",
  "data": {
    "renderId": "b1f3c1d2-7a55-4d0e-9e59-2f3f5c0a9d11",
    "status": "failed",
    "test": false,
    "errorCode": "LIMIT_EXCEEDED"
  }
}
```

| Field            | Description                                                                |
| ---------------- | -------------------------------------------------------------------------- |
| `id`             | The event's ID. Every endpoint that receives this event sees the same ID.  |
| `type`           | `render.succeeded`, `render.failed` or `render.cancelled`.                 |
| `createdAt`      | When the render reached its final state (ISO 8601, UTC).                   |
| `data.renderId`  | The render's ID. Fetch it with `GET /v1/renders/{id}`.                     |
| `data.status`    | `succeeded`, `failed` or `cancelled`.                                      |
| `data.test`      | `true` for a [test render](/guides/rendering/#test-renders), else `false`. |
| `data.errorCode` | Only on `render.failed`: the error's code, as on the render's `error`.     |

## Request headers

| Header              | Value                                                                        |
| ------------------- | ---------------------------------------------------------------------------- |
| `webhook-id`        | The delivery's ID. It stays the same on every retry of that delivery.        |
| `webhook-timestamp` | When this attempt was sent, in Unix seconds.                                 |
| `webhook-signature` | One or more space-separated `v1,<base64>` signatures, one per active secret. |
| `content-type`      | `application/json`                                                           |
| `user-agent`        | `typefold-webhooks/1`                                                        |

`webhook-id` identifies one delivery to one endpoint. The body's `id` identifies the event and is
the same for every endpoint, so use it to skip duplicates.

## Signatures

Deliveries are signed as [Standard Webhooks](https://www.standardwebhooks.com/) specifies, so a
Standard Webhooks library for your language can verify them with the endpoint's signing secret.
The secret looks like `whsec_<base64>`.

- Reject a request whose signature does not match.
- Reject a request whose `webhook-timestamp` is more than five minutes away from your clock,
  earlier or later, so a captured request cannot be replayed. Every retry is signed again with a
  fresh timestamp.

### Rotate the secret

If the secret may have leaked, or you lost it, rotate it. It cannot be read again. Update your
application with the new secret within 24 hours: until then, deliveries carry two signatures, one
from each secret. After that only the new secret signs.

<Tabs syncKey="api-client">
<TabItem label="curl">

```sh
curl -X POST "$PDF_URL/v1/webhook-endpoints/7c9e6679-7425-40de-944b-e07fc1f90ae7/rotate-secret" \
  -H "x-api-key: $API_KEY"
```

The response holds the new `secret`.

</TabItem>
<TabItem label=".NET">

The client cannot rotate secrets. In Studio, open **Manage → Webhooks**, select the
endpoint and click **Rotate secret**. Studio then shows the new secret.

</TabItem>
<TabItem label="TypeScript">

The client cannot rotate secrets. In Studio, open **Manage → Webhooks**, select the
endpoint and click **Rotate secret**. Studio then shows the new secret.

</TabItem>
<TabItem label="JavaScript">

The client cannot rotate secrets. In Studio, open **Manage → Webhooks**, select the
endpoint and click **Rotate secret**. Studio then shows the new secret.

</TabItem>
<TabItem label="Python">

The client cannot rotate secrets. In Studio, open **Manage → Webhooks**, select the
endpoint and click **Rotate secret**. Studio then shows the new secret.

</TabItem>
</Tabs>

## Delivery rules and retries

- A delivery succeeds when your endpoint answers any `2xx` status within 10 seconds. The response
  body is ignored.
- Anything else fails and is retried: another status, a timeout, a refused connection or a
  redirect. Redirects are not followed.
- The same event can arrive more than once, for example when your answer is lost. Skip events
  whose `id` you have already handled.
- Deliveries can arrive out of order. Act on the render's current `state`, not on event order.
- A failed attempt is retried after 30 seconds, then 2, 5, 15 and 30 minutes, then 1, 2, 4, 8 and
  8 hours, each wait counted from the previous attempt. If the 11th attempt fails, the delivery is
  marked `failed` and not sent again.

## Delivery history

`GET /v1/webhook-endpoints/{id}/deliveries` lists an endpoint's deliveries, newest first, in
pages like other [list endpoints](/clients/http/). Studio does not show deliveries.

```json
{
  "items": [
    {
      "id": "c2a5f1b0-3d4e-4f60-8a7b-9c0d1e2f3a4b",
      "eventId": "5e0c8f5e-4a4c-4f55-9a8a-7f1f9b3f1a2c",
      "eventType": "render.failed",
      "renderId": "b1f3c1d2-7a55-4d0e-9e59-2f3f5c0a9d11",
      "status": "pending",
      "attempts": 2,
      "lastStatusCode": 503,
      "lastError": "The endpoint answered HTTP 503.",
      "lastAttemptAt": "2026-10-08T09:16:01.512Z",
      "nextAttemptAt": "2026-10-08T09:18:01.512Z",
      "createdAt": "2026-10-08T09:15:31.004Z"
    }
  ]
}
```

- `id` is the `webhook-id` header; `eventId` is the event's `id`.
- `status` is `pending` (more attempts to come), `succeeded` or `failed`.
- `nextAttemptAt` is set only while `pending`.
- Delivery records are kept as long as renders, 30 days by default.

`lastError` says why the last attempt failed:

| `lastError`                                          | Meaning                                                                |
| ---------------------------------------------------- | ---------------------------------------------------------------------- |
| `The endpoint answered HTTP <status>.`               | Your endpoint answered with a status other than `2xx`.                 |
| `The endpoint did not respond in time.`              | No answer within 10 seconds.                                           |
| `The request failed (<code>).`                       | The connection failed, such as `ECONNREFUSED`.                         |
| `The endpoint is disabled.`                          | The endpoint was disabled while the delivery was waiting for a retry.  |
| `The endpoint's signing secret cannot be decrypted.` | Self-hosted only: the server can no longer read the secret. Rotate it. |
| A destination message                                | The URL is no longer an [allowed destination](#allowed-destinations).  |

## Allowed destinations

Webhook URLs must point at the public internet. A URL is refused when:

- its scheme is not `http` or `https`, or it is `http` on the hosted service;
- it contains credentials, such as `https://user:pass@example.com`;
- its host is `localhost` or ends in `.localhost`;
- it is, or its host name resolves to, a private, loopback, link-local, shared, reserved,
  documentation or multicast address (IPv4 or IPv6, including cloud metadata addresses such as
  `169.254.169.254`);
- its host name does not resolve.

Creating an endpoint or changing its URL to a refused URL answers `400 BAD_REQUEST`, with the
reason in `details`. The check runs again on every delivery, so a host name that later points at
a private address fails that delivery, which is then retried.

Self-hosted installations also accept `http`, and can allow private addresses; see
[configuration](/self-hosting/configuration/).

## Manage endpoints

In Studio, open **Manage → Webhooks**, select endpoints and click **Enable**, **Disable**,
**Rotate secret** or **Delete**.

- A disabled endpoint receives no new events. Deliveries waiting for a retry are marked `failed`
  at their next attempt.
- Deleting an endpoint discards its pending deliveries and its delivery history.
- A workspace can have up to 10 endpoints. An eleventh answers `409 CONFLICT`.

With the API, every operation needs the `webhook:manage` scope. Request and response fields are
in the [API reference](/reference/api/).

| Operation                                       | What it does                                                                                                                     |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `POST /v1/webhook-endpoints`                    | Create an endpoint. Answers `201 Created` with the `secret`.                                                                     |
| `GET /v1/webhook-endpoints`                     | List all endpoints, without secrets.                                                                                             |
| `GET /v1/webhook-endpoints/{id}`                | Read one endpoint, without its secret.                                                                                           |
| `PATCH /v1/webhook-endpoints/{id}`              | Change only the fields you send: `url`, `description`, `eventTypes` or `enabled`. `"description": null` removes the description. |
| `DELETE /v1/webhook-endpoints/{id}`             | Delete the endpoint and its delivery history.                                                                                    |
| `POST /v1/webhook-endpoints/{id}/rotate-secret` | Issue a new signing secret. Returns the endpoint and new `secret`.                                                               |
| `GET /v1/webhook-endpoints/{id}/deliveries`     | List recent deliveries; see [delivery history](#delivery-history).                                                               |

---

# Component templates

Source: https://docs.typefold.dev/templates/components/

A component template describes a document as a tree of JSON components (containers, text,
images, repeated lists and tables), each bound to a value in your data. Nothing in it runs:
text is never read as a template expression, and data values are always inserted as text.

Choose components over [Handlebars templates](/templates/handlebars/) when a program generates
the document, or when you want no code in the template at all. Scripts and `helpers.js` only run
in Handlebars templates.

## Build an order confirmation

You build a heading, a table of items and a "Paid" badge, then preview, publish and render it.

You need the `API_KEY` and `PDF_URL` variables from the [quickstart](/start/quickstart/) and an
[API key](/clients/http/) with the `template:write`, `template:read`, `template:publish`,
`render:create` and `render:read` scopes. Studio and the client libraries cannot start a component template, so
you create it with curl.

### 1. Write the composition

Save your data as `order.json`:

```json title="order.json"
{
  "order": { "number": "A-1042", "paid": true },
  "lines": [
    { "name": "Desk lamp", "price": 39.9 },
    { "name": "Bulb, 2 pack", "price": 6.5 }
  ]
}
```

The composition is the template's body. A `root` container holds a text bound to the order
number, a table with one row per line, and a badge shown only when the order is paid:

```json title="composition"
{
  "root": {
    "type": "container",
    "style": {
      "display": "flex",
      "flexDirection": "column",
      "gap": 16,
      "padding": 24
    },
    "children": [
      {
        "type": "text",
        "text": { "path": ["order", "number"], "prefix": "Order " },
        "style": { "fontSize": 20, "fontWeight": 700 }
      },
      {
        "type": "table",
        "source": { "path": ["lines"] },
        "columns": [
          { "id": "name", "header": "Item", "value": { "path": ["name"] } },
          {
            "id": "price",
            "header": "Price",
            "value": {
              "path": ["price"],
              "format": { "type": "currency", "currency": "EUR" }
            }
          }
        ]
      },
      {
        "type": "text",
        "text": "Paid",
        "visibleWhen": { "path": ["order", "paid"], "operator": "truthy" }
      }
    ]
  }
}
```

Inside the table, paths are relative to each line, so `["name"]` is the line's name.

### 2. Create the template

Send the composition in the draft's `content`, next to its page `settings` (the same fields as
[`page.json`](/templates/overview/#pagejson)):

```sh
curl $PDF_URL/v1/templates \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "Order confirmation",
    "content": {
      "composition": { "root": { ... } },
      "settings": {
        "pageSize": { "widthMm": 210, "heightMm": 297 },
        "margins": { "topMm": 10, "rightMm": 10, "bottomMm": 10, "leftMm": 10 }
      }
    }
  }'
```

Replace `{ ... }` with the `root` from step 1. The response is the new template with
`draftRevision` `1`. Save its `id`:

```sh
export TEMPLATE_ID='paste-the-id-here'
```

### 3. Preview it

```sh
curl $PDF_URL/v1/templates/$TEMPLATE_ID/preview \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  -d "{ \"data\": $(cat order.json) }" \
  --fail-with-body -o preview.pdf
```

`preview.pdf` shows "Order A-1042", a two-row table with prices such as "€39.90", and the
"Paid" badge. Preview again with `"paid": false` and the badge disappears.

The template also opens in Studio, where you edit `composition.json`. To preview there, add
`order.json` as a [workspace file](/templates/overview/) and pick it in the **Data** selector
above the preview.

### 4. Publish

Renders by name use the newest published version:

<Tabs syncKey="api-client">
<TabItem label="curl">

```sh
curl $PDF_URL/v1/templates/$TEMPLATE_ID/versions \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  -d '{ "expectedRevision": 1 }'
```

</TabItem>
<TabItem label=".NET">

The client cannot publish templates. Open **Order confirmation** in Studio and click **Publish**
in the header. The status changes to **Published v1**.

</TabItem>
<TabItem label="TypeScript">

The client cannot publish templates. Open **Order confirmation** in Studio and click **Publish**
in the header. The status changes to **Published v1**.

</TabItem>
<TabItem label="JavaScript">

The client cannot publish templates. Open **Order confirmation** in Studio and click **Publish**
in the header. The status changes to **Published v1**.

</TabItem>
<TabItem label="Python">

The client cannot publish templates. Open **Order confirmation** in Studio and click **Publish**
in the header. The status changes to **Published v1**.

</TabItem>
</Tabs>

### 5. Render

Render the template by name with the [Reports API](/guides/reports/) and save `order.pdf`:

<Tabs syncKey="api-client">
<TabItem label="curl">

```sh
curl "$PDF_URL/v1/reports/render" \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  --fail-with-body -o order.pdf \
  -d "{
    \"format\": \"pdf\",
    \"template\": { \"name\": \"Order confirmation\" },
    \"data\": $(cat order.json)
  }"
```

</TabItem>
<TabItem label=".NET">

```csharp
using Typefold.Client;

var client = new TypefoldClient(
    new Uri(Environment.GetEnvironmentVariable("PDF_URL")!),
    Environment.GetEnvironmentVariable("API_KEY")!);

byte[] pdf = await client.RenderReportAsync(new RenderReportRequest
{
    Template = TemplateRef.ByName("Order confirmation"),
    Data = new
    {
        order = new { number = "A-1042", paid = true },
        lines = new[]
        {
            new { name = "Desk lamp", price = 39.9 },
            new { name = "Bulb, 2 pack", price = 6.5 },
        },
    },
});

await File.WriteAllBytesAsync("order.pdf", pdf);
```

</TabItem>
<TabItem label="TypeScript">

```ts
import { writeFile } from "node:fs/promises";
import { TypefoldClient, TemplateRef } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL!,
  apiKey: process.env.API_KEY!,
});

const pdf = await client.renderReport({
  template: TemplateRef.byName("Order confirmation"),
  data: {
    order: { number: "A-1042", paid: true },
    lines: [
      { name: "Desk lamp", price: 39.9 },
      { name: "Bulb, 2 pack", price: 6.5 },
    ],
  },
});

await writeFile("order.pdf", pdf);
```

</TabItem>
<TabItem label="JavaScript">

```js
import { writeFile } from "node:fs/promises";
import { TypefoldClient, TemplateRef } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL,
  apiKey: process.env.API_KEY,
});

const pdf = await client.renderReport({
  template: TemplateRef.byName("Order confirmation"),
  data: {
    order: { number: "A-1042", paid: true },
    lines: [
      { name: "Desk lamp", price: 39.9 },
      { name: "Bulb, 2 pack", price: 6.5 },
    ],
  },
});

await writeFile("order.pdf", pdf);
```

</TabItem>
<TabItem label="Python">

```python
import os
from pathlib import Path

from typefold import TypefoldClient, RenderReportRequest, TemplateRef

client = TypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"])

pdf = client.render_report(
    RenderReportRequest(
        template=TemplateRef.by_name("Order confirmation"),
        data={
            "order": {"number": "A-1042", "paid": True},
            "lines": [
                {"name": "Desk lamp", "price": 39.9},
                {"name": "Bulb, 2 pack", "price": 6.5},
            ],
        },
    )
)

Path("order.pdf").write_bytes(pdf)
```

</TabItem>
</Tabs>

To render a specific version in the background, use the [Renders API](/guides/rendering/).

## Composition

| Field         | Type     | Description                                                                                                     |
| ------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `root`        | object   | Required. The top [component](#components), usually a `container`.                                              |
| `components`  | object   | Up to 100 [reusable components](#reusable-components) by ID.                                                    |
| `stylesheets` | string[] | Up to 20 workspace stylesheet paths from the template's folder, applied in order.                               |
| `header`      | string   | Handlebars page header, up to 100,000 characters. See [headers and footers](#headers-footers-and-translations). |
| `footer`      | string   | Handlebars page footer, up to 100,000 characters.                                                               |

In Studio, each part has its own file:

- `composition.json` holds only `root`.
- **Page header** and **Page footer** hold `header` and `footer`.
- **Template files** above the preview lists the folder's stylesheets; tick the ones to apply.
- Studio does not show `components`. Saving there keeps them unchanged; change them through the
  API ([`PUT /v1/templates/{id}/draft`](/reference/api/)).

## Components

Every component has a `type` and these optional fields:

| Field         | Type   | Description                                                                                |
| ------------- | ------ | ------------------------------------------------------------------------------------------ |
| `style`       | object | CSS properties in camelCase. See [styling](#styling).                                      |
| `className`   | string | Up to 1,000 characters of space-separated classes from the template's stylesheets.         |
| `visibleWhen` | object | A [condition](#conditions). When it is false, the component and its children are left out. |

### `container`

Groups other components. Lay them out with CSS in `style`.

| Field      | Type  | Description                             |
| ---------- | ----- | --------------------------------------- |
| `children` | array | Required. Up to 1,000 child components. |

### `text`

| Field  | Type  | Description                                                                |
| ------ | ----- | -------------------------------------------------------------------------- |
| `text` | value | Required. A literal, a [binding](#bindings), or [mixed text](#mixed-text). |

### `image`

| Field     | Type              | Description                                                           |
| --------- | ----------------- | --------------------------------------------------------------------- |
| `assetId` | string or binding | Required. The ID of an uploaded image, or a binding that selects one. |
| `width`   | number            | Width in CSS pixels, above 0.                                         |
| `height`  | number            | Height in CSS pixels, above 0.                                        |

To get an ID, add the image to the workspace in Studio and open it: the ID is shown as
**Asset ID**. Or upload it with `POST /v1/assets` (see the [API reference](/reference/api/)).
Publishing copies the image into the version, so deleting it later does not change published
versions.

A binding in `assetId` can only select an image the template already names literally, for
example in another `image` component. Anything else fails with `400 ASSET_INVALID`. To pick one
of several logos, add one `image` per logo and show the right one with `visibleWhen` and `equals`.

### `repeat`

Renders its children once for each item of an array. Inside, bindings read from the current item.

| Field      | Type        | Description                                                          |
| ---------- | ----------- | -------------------------------------------------------------------- |
| `source`   | data source | Required. The [path](#bindings) of the array.                        |
| `children` | array       | Required. Up to 1,000 components rendered for each item.             |
| `empty`    | array       | Up to 1,000 components rendered instead when the array has no items. |

The repeat is a flex column, and each item gets its own container. A `source` that is missing or
`null` counts as empty; any other value that is not an array fails with `400 BAD_REQUEST`.

### `table`

Renders a header row and one row per item of an array.

| Field         | Type        | Default | Description                                                                  |
| ------------- | ----------- | ------- | ---------------------------------------------------------------------------- |
| `source`      | data source |         | Required. The path of the array; each item becomes a row.                    |
| `columns`     | array       |         | Required. 1 to 30 columns, described below.                                  |
| `showHeader`  | boolean     | `true`  | `false` leaves out the header row.                                           |
| `headerStyle` | object      |         | Style for header cells, applied last.                                        |
| `cellStyle`   | object      |         | Style for every cell.                                                        |
| `emptyText`   | string      |         | Up to 10,000 characters shown in one full-width row when the array is empty. |

Each column has:

| Field    | Type   | Description                                                                                             |
| -------- | ------ | ------------------------------------------------------------------------------------------------------- |
| `id`     | string | Required. Unique in the table. Up to 128 letters, digits, `_` and `-`, starting with a letter or digit. |
| `header` | string | Required. Header text, up to 1,000 characters. Can be empty.                                            |
| `value`  | value  | Required. What the cell shows. Bindings read from the row's item.                                       |
| `width`  | number | Width in CSS pixels, above 0 and up to 2,000. Without it, the table sizes the column.                   |
| `style`  | object | Style for this column's cells.                                                                          |

Default look and behaviour:

- The table spans the full width with collapsed borders.
- Cells have 6px padding, a 1px `#d1d5db` border and left-aligned text. Header cells are
  semibold on `#f3f4f6`.
- `cellStyle` applies first, then the column's `style`, then `headerStyle` on header cells.
- A row is never split across a page break.
- Without `emptyText`, an empty array leaves only the header row.

Set column widths with `width`, not a percentage in `style`: percentage cell widths can clip the
contents.

### `component`

Renders a [reusable component](#reusable-components).

| Field         | Type        | Description                                                                 |
| ------------- | ----------- | --------------------------------------------------------------------------- |
| `componentId` | string      | Required. The key of the reusable component.                                |
| `data`        | data source | Where the component reads its data. Without it, it reads the caller's data. |

## Reusable components

Define a block once under `components`, next to `root`, and use it anywhere with a `component`.
The key is its ID: up to 128 letters, digits, `_` and `-`, starting with a letter or digit. Each
has a `name` (1 to 200 characters) and a `root` component.

```json
{
  "root": {
    "type": "component",
    "componentId": "address",
    "data": { "path": ["billing"] }
  },
  "components": {
    "address": {
      "name": "Postal address",
      "root": {
        "type": "container",
        "children": [
          { "type": "text", "text": { "path": ["name"] } },
          { "type": "text", "text": { "path": ["street"] } },
          { "type": "text", "text": { "path": ["city"] } }
        ]
      }
    }
  }
}
```

Reusable components can use each other, but not themselves, directly or indirectly. An unknown
`componentId`, a circular reference, or `data` pointing at a missing value fails the preview or
render with `400 BAD_REQUEST`.

## Values and bindings

`text`, a column's `value` and an image's `assetId` take a value:

- A literal string (up to 100,000 characters), number or boolean: `"Invoice"`, `42`, `true`.
- A binding to a path in the data: `{ "path": ["customer", "name"] }`.
- [Mixed text](#mixed-text) joining literals and bindings.

### Bindings

| Field      | Type                      | Default   | Description                                                                        |
| ---------- | ------------------------- | --------- | ---------------------------------------------------------------------------------- |
| `path`     | string[]                  |           | Required. 1 to 20 property names, each up to 128 characters.                       |
| `scope`    | string                    | `current` | `current` reads from the current repeat or table item, `root` from the whole data. |
| `fallback` | string, number or boolean |           | Shown when the path is missing or not a plain value.                               |
| `format`   | object                    |           | How to [format](#formats) a number or date.                                        |
| `prefix`   | string                    |           | Text before the value, up to 1,000 characters.                                     |
| `suffix`   | string                    |           | Text after the value, up to 1,000 characters.                                      |

Array items use their index as a string, such as `["lines", "0", "name"]`. The names
`__proto__`, `constructor` and `prototype` are not allowed.

A data source (`source` in `repeat` and `table`, `data` in `component`) takes only `path` and
`scope`.

Outside any `repeat` or `table`, the current item is the whole data. Inside one, use
`"scope": "root"` to reach data outside the item:

```json
{
  "id": "currency",
  "header": "Currency",
  "value": { "path": ["invoice", "currency"], "scope": "root" }
}
```

### Missing values

A binding must find a string, number or boolean. If the value is missing, `null`, an object or an
array, the preview or render fails with `400 BAD_REQUEST` naming the path. Give every optional
value a `fallback`, even `""`:

```json
{ "path": ["order", "note"], "fallback": "" }
```

The fallback is shown as written, without `format`, but with `prefix` and `suffix`.

### Mixed text

`parts` joins 1 to 100 literals and bindings into one string of up to 1,000,000 characters:

```json
{
  "type": "text",
  "text": {
    "parts": ["Dear ", { "path": ["customer", "firstName"] }, ", your order has shipped."]
  }
}
```

## Formats

A binding's `format` turns a number or date into text for a locale:

| Field                   | Type    | Default   | Description                                                          |
| ----------------------- | ------- | --------- | -------------------------------------------------------------------- |
| `type`                  | string  |           | Required. `number`, `currency`, `percent` or `date`.                 |
| `locale`                | string  | see below | A locale such as `de-CH`, 2 to 64 characters.                        |
| `currency`              | string  |           | A three-letter ISO 4217 code such as `EUR`. Required for `currency`. |
| `minimumFractionDigits` | integer |           | 0 to 20. For `number`, `currency` and `percent`.                     |
| `maximumFractionDigits` | integer |           | 0 to 20. For `number`, `currency` and `percent`.                     |
| `dateStyle`             | string  | `medium`  | `short`, `medium`, `long` or `full`. For `date`.                     |
| `timeZone`              | string  | `UTC`     | An IANA time zone such as `Europe/Berlin`. For `date`.               |

| Type       | Value                                                                                                         | Output (`en-GB`) |
| ---------- | ------------------------------------------------------------------------------------------------------------- | ---------------- |
| `number`   | A number                                                                                                      | `1,234.5`        |
| `currency` | A number                                                                                                      | `€1,234.50`      |
| `percent`  | A number, where `0.2` is 20%                                                                                  | `20%`            |
| `date`     | An ISO date (`2026-10-08`), an ISO timestamp with a zone (`2026-10-08T07:30:00Z`), or milliseconds since 1970 | `8 Oct 2026`     |

Numbers must be JSON numbers, not strings such as `"12.50"`. A value of the wrong type fails with
`400 BAD_REQUEST`.

Without `locale`, the format uses the render's language: the request's `locale` for the
[Reports API](/guides/reports/) (`en-US` when left out) and for a preview that sends one,
otherwise the `locale` in `page.json`. The Renders API always uses `page.json`.

## Conditions

`visibleWhen` shows a component only when a condition about the data holds:

```json
{
  "type": "text",
  "text": "PAID",
  "visibleWhen": {
    "path": ["invoice", "status"],
    "operator": "equals",
    "value": "paid"
  }
}
```

| Operator    | Shows the component when the value is            |
| ----------- | ------------------------------------------------ |
| `truthy`    | Present and not `false`, `0`, `""` or `null`.    |
| `falsy`     | Missing, `false`, `0`, `""` or `null`.           |
| `exists`    | Present and not `null`.                          |
| `notExists` | Missing or `null`.                               |
| `equals`    | Exactly equal to `value`, same type and content. |
| `notEquals` | Not exactly equal to `value`.                    |

Conditions take `path` and `scope` like a binding. `equals` and `notEquals` need a `value` (a
string, number or boolean); without one, the component is hidden. A missing path never fails a
condition.

## Styling

`style` takes CSS properties in camelCase. Numbers are CSS pixels; anything else is a string:

```json
{
  "style": {
    "display": "flex",
    "gap": 12,
    "padding": 8,
    "borderWidth": 1,
    "borderStyle": "solid",
    "borderColor": "#e5e7eb"
  }
}
```

Styles are static and cannot be bound to data. To change the look with the data, show
alternative components with `visibleWhen`.

For shared styles, apply workspace stylesheets (`stylesheets`, or **Template files** in Studio)
and refer to their classes with `className`. Stylesheets can load workspace fonts and images.
See [supported CSS](/templates/css-support/).

## Headers, footers and translations

`header` and `footer` are Handlebars, drawn in the page margins with the same data and page
numbers as in any template. See [build a template](/guides/first-template/).

[Translation files](/features/translations/) work as in Handlebars templates: the file for the
render's language is added to the data as `localization`, unless the data already has one. Bind
its labels like any value:

```json
{ "type": "text", "text": { "path": ["localization", "invoiceTitle"] } }
```

## Limits

Field limits are in the tables above. Limits on the whole composition, such as the number of
components, nesting depth and items in one `repeat` or `table`, are in [limits](/clients/limits/).
Limits checked when you save the draft fail with `400 BAD_REQUEST`; limits checked when a preview
or render fills in the data fail with `400 LIMIT_EXCEEDED`.

## Render a tree without a template

To render a tree you build in code without keeping a template, send a node document to
`POST /v1/renders`. It has its own shape, with no bindings; see
[render documents](/guides/rendering/).

---

# Let business users edit content

Source: https://docs.typefold.dev/templates/content-fields/

Content fields are the parts of a template that a **content editor** may change in Studio without
seeing its code: a logo, an accent colour, payment terms, a closing line. A developer marks them
once. A content editor then fills them in a form, previews the document, and publishes it.

## Mark the fields

Open the template in **Workspace → Editor** and choose **+ → Add fields.json** at the end of the
tab bar under its source. List the fields there:

```json title="fields.json"
[
  {
    "key": "accent",
    "label": "Accent colour",
    "type": "colour",
    "group": "Brand"
  },
  { "key": "logo", "label": "Logo", "type": "image", "group": "Brand" },
  {
    "key": "terms",
    "label": "Payment terms",
    "type": "richText",
    "group": "Footer"
  }
]
```

| Property    | What it does                                                                                  |
| ----------- | --------------------------------------------------------------------------------------------- |
| `key`       | Required. The name the template reads it by: a letter, then letters, digits or `_`, up to 64. |
| `label`     | Required. What the form shows.                                                                |
| `type`      | Required. One of the types below.                                                             |
| `group`     | Fields with the same group are shown together under it.                                       |
| `help`      | A hint shown under the input.                                                                 |
| `multiline` | A `text` field that holds several lines.                                                      |
| `maxLength` | The most characters a `text` or `richText` value holds.                                       |
| `options`   | Required for `choice`, and only allowed there: the values it offers.                          |

| `type`     | Value                                                                   | Default limit     |
| ---------- | ----------------------------------------------------------------------- | ----------------- |
| `text`     | Plain text, one line unless `multiline`                                 | 2,000 characters  |
| `richText` | Paragraphs, bold, italic, links and bulleted or numbered lists, as HTML | 20,000 characters |
| `image`    | An uploaded PNG, JPEG or SVG                                            |                   |
| `colour`   | A colour such as `#1f4fd1`                                              |                   |
| `toggle`   | On or off                                                               |                   |
| `choice`   | One of `options`                                                        |                   |
| `number`   | A number                                                                |                   |
| `date`     | A date such as `2026-10-16`                                             |                   |

A template has up to 100 fields, and their values take up to 64 KB together. The **Invoice
example** template comes with an accent colour, a logo and payment details already marked.

## Use them in the template

The values are in the data as `$content`:

```handlebars title="template.html"
<style>
  h1 { color:{{$content.accent}}; }
</style>
{{#if $content.logo}}<img src="{{$content.logo}}" alt="" />{{/if}}
<h1>Invoice</h1>
{{#each items}}
  <p style="border-color: {{@root.$content.accent}}">{{description}}</p>
{{/each}}
<footer>{{{$content.terms}}}</footer>
```

- Write rich text with three braces, `{{{$content.terms}}}`, so its formatting renders. Whatever
  is typed or pasted, only paragraphs, line breaks, bold, italic, links (`http`, `https` and
  `mailto`) and lists are kept.
- Inside `{{#each}}` and other blocks, read the values as `@root.$content.key`.
- An `image` value is the uploaded image's ID; use it as an `src` as above.
- A field without a value renders as empty.
- The **content.json** tab holds the values. The **Bindings** tab and autocomplete list them.
- Request data cannot set `$content`: a render or preview whose data has a `$content` key answers
  `400 BAD_REQUEST`.

Publish the template once yourself. A content editor can only publish a template that has been
published before.

## Invite a content editor

In **Manage → Team**, invite the person with the role **Content editor**, or select someone and
**Change role**. A content editor sees only **Content** in Studio and can:

- change the values of content fields, preview the document with sample data, and publish it;
- upload images for image fields;
- read templates, render them, and read the workspace's renders.

They cannot change a template's code, its sample data or workspace files, and cannot see API
keys, webhooks, the team or the audit log.

## Edit content

A content editor opens **Content**, which lists the templates that have content fields and
whether their changes are published, and picks one:

1. Change the fields in the form, and click **Update preview** to see the document with the
   template's sample data. For a template that fills an Excel workbook, click **Download
   spreadsheet** instead.
2. Click **Save**. Each save is kept as a revision; **History** shows the earlier versions and
   what each changed, and **Use this version** loads one back into the form.
3. Click **Publish**. Documents render with the new values from then on.

A content editor's publish never ships a developer's unfinished work. It is refused with
`403 FORBIDDEN` while the draft has changes other than content values that are not published yet;
a developer publishes those first.

When two people change the same template, a save keeps what the other saved in the meantime:

- Two content editors: each save keeps the other's values and changes only the fields this
  editor changed.
- A content editor and a developer with the template open: the developer's next save keeps the
  content editor's values, unless the developer changed **content.json** too.

A value left over from a field a developer removed is dropped at the next save.

## Over HTTP

Save content values with `PUT /v1/templates/{id}/content` and the `template:content` scope, plus
`template:read`. It replaces the values on the latest draft and keeps everything else:

```sh
curl -X PUT "$PDF_URL/v1/templates/$TEMPLATE_ID/content" \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  -d '{"values":{"accent":"#1f4fd1","terms":"<p>Due in <strong>30 days</strong>.</p>"}}'
```

- Values must fit their fields; a key no field declares, or a value of the wrong kind, answers
  `400 BAD_REQUEST`. A template without content fields answers `400` too.
- Send `"expectedRevision"` to refuse the change with `409 CONFLICT` if the draft has changed
  since you read it.
- `GET /v1/templates?content=true` lists the templates that have content fields. Each template
  carries `publishedRevision`, the draft revision its live version was published from.
- Publishing with `template:publish` but without `template:write` follows the rule above.
- Uploading an image for an image field needs `template:content` or `asset:manage`.

Each save is recorded in the [audit log](/self-hosting/users/#audit-history) as
`template.content_updated`, with the fields it changed. A [workspace
export](/guides/environments/) carries `fields.json` and `content.json`, and importing it
replaces the values in the target environment.

---

# Supported CSS

Source: https://docs.typefold.dev/templates/css-support/

Style templates with the CSS you would write for Chrome's print view; the renderer lays the HTML
out as Chrome prints it. This page lists what works and the rules specific to typefold. For a
walk-through of paper, header, footer, fonts and a logo, see
[build a template](/guides/first-template/).

```css
@page {
  size: A4 landscape;
  margin: 15mm 12mm;
}

.totals {
  break-inside: avoid;
}
```

## What works

- Block and inline layout, **flexbox** and **grid**, tables (including `border-collapse`,
  `<colgroup>` and `<col>` widths), floats, and `relative` and `absolute` positioning.
- Box model: margins, padding, borders, `border-radius`, `box-sizing`, `overflow`.
- Text: font properties, `line-height`, `letter-spacing`, `text-align`, `text-transform`,
  `text-decoration`, `white-space`, `word-break`, `overflow-wrap`, `text-overflow`.
- Colours and backgrounds, including linear, radial and conic gradients, `opacity`,
  `box-shadow` and `text-shadow`.
- `transform`, CSS custom properties (`var(--x)`) and `calc()`.
- Lists, links (clickable in the PDF) and SVG images.
- `@page` size and margins, and the [page break](#page-breaks) properties.

## What is not supported

| Feature                                                            | What happens     | Instead                                                                                                                                                                           |
| ------------------------------------------------------------------ | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@page :first` and other page selectors, named pages, margin boxes | Ignored          | Put [page numbers](#page-numbers) in the header or footer. For content that changes per page, such as a first-page letterhead, [combine templates](/features/combine-templates/). |
| `filter: blur()` and `filter: drop-shadow()`                       | The render fails | Prepare the effect as an image.                                                                                                                                                   |
| `backdrop-filter`                                                  | Ignored          | Prepare the effect as an image.                                                                                                                                                   |

JavaScript in the document and fonts or images at external URLs are not loaded either; see
[what's not supported](/start/not-supported/).

## Page size and margins

The paper and margins come from the template's `page.json` (see
[templates](/templates/overview/)). A Reports API request or a preview can override them for one
render with its `pdf` options (see the [API reference](/reference/api/)), and CSS `@page` rules
override both; see [which value wins](#which-value-wins).

### CSS `@page` rules

| Property                                                               | Effect                                                                                                                                    |
| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `margin`, `margin-top`, `margin-right`, `margin-bottom`, `margin-left` | Replace the margins side by side. A side the rule leaves out keeps its value. Each 0 to 500 mm.                                           |
| `size`                                                                 | Turns the page to the rule's orientation. The paper itself changes only when `page.json` or the request sets `"preferCssPageSize": true`. |

`size` accepts:

- `auto`.
- One or two lengths, such as `80mm 200mm`. One length makes a square page. Each side above 0
  and up to 2,000 mm. The orientation is the one the width and height imply.
- `A3`, `A4`, `A5`, `B4`, `B5`, `JIS-B4`, `JIS-B5`, `letter`, `legal` or `ledger`, optionally with
  `portrait` or `landscape`, or the orientation alone.

Lengths can use `mm`, `cm`, `Q`, `in`, `pt`, `pc` or `px`, or be a bare `0`. A value that cannot
be read, such as a percentage or a size over the limits, is skipped. `!important` makes no
difference.

Which rules count:

- Rules in the template's `<style>` elements and its stylesheets, at the top level or inside
  `@media` that print matches (`print`, `all`, or no media type). Later rules win.
- Only unnamed `@page` rules without a page selector.
- Not `@page` rules in `header.html` and `footer.html`.

### Which value wins

Values apply in this order, each replacing the one before:

1. The template's `page.json`.
2. The request's `pdf` options (Reports API and previews), field by field.
3. The document's `@page` rules.

When an `@page` rule sets an orientation, the paper (`pageSize`, or the rule's own size with
`preferCssPageSize`) is turned to it, and the `orientation` setting no longer applies.

## Headers and footers

`header.html` and `footer.html` (the **Page header** and **Page footer** tabs in Studio) are
Handlebars, with the same data, helpers, partials and translations as the body. They work in
HTML and [component](/templates/components/) templates, not in spreadsheet templates. Leave the
file empty for no band.

### Page numbers

An element with the class `pageNumber` or `totalPages`, anywhere in a header or footer, is
filled with the current page number or the total page count:

```html
<span class="pageNumber"></span> / <span class="totalPages"></span>
```

With `pageRanges`, the numbers still count the whole document.

### Layout rules

- The band is drawn inside the top or bottom margin, which does not grow to fit it. If it is cut
  off, make the margin larger.
- It spans the full page width.
- Its top-level elements sit in a flex row, aligned to the top of the margin in a header and the
  bottom in a footer. The band's own `html` and `body` tags are dropped.
- Backgrounds are not printed unless `header.html` or `footer.html` sets
  `print-color-adjust: exact`.
- Every page gets the same band. Only the page numbers change from page to page.
- Images resolve by path as in the body.
- The template's stylesheets apply to the bands, and a `<style>` element in a band applies to the
  whole document. Style the band with inline `style` attributes to keep it separate.

## Page breaks

Supported: `break-before: page`, `break-after: page`, `break-inside: avoid`, and
`page-break-before: always`, `page-break-after: always` and `page-break-inside: avoid`.

A table that runs over several pages repeats its `<thead>` at the top of each page and prints its
`<tfoot>` once, after the last row. Add `break-inside: avoid` to `tr` to keep each row on one
page.

## Fonts

Text is set in fonts bundled with Typefold and the fonts you upload, never in fonts installed
on the server or loaded from a URL.

| `font-family` in your CSS                                   | What is used                         |
| ----------------------------------------------------------- | ------------------------------------ |
| `Arial`                                                     | GNU FreeSans (regular and bold).     |
| A family you uploaded and declared                          | Your font.                           |
| Anything else, including `sans-serif`, `serif`, `Helvetica` | Geist, the built-in sans-serif font. |

- **Formats.** TTF, OTF and WOFF2.
- **Declaring.** An `@font-face` rule for each file, with `font-family`, `src: url(...)`,
  `font-weight` and `font-style`. `url()` paths start from the folder of the file they are written
  in; see [how paths resolve](/templates/overview/).
- **Embedding.** `src: url({#asset ../fonts/Inter-Regular.ttf @encoding=dataURI})` embeds the
  font in the CSS.
- **Fallback.** Characters the chosen font lacks fall back to the bundled fonts: Geist,
  FreeSans, FreeSerif Bold for symbols such as ★, and Noto Color Emoji for emoji. Uploaded fonts
  are never used as fallbacks for other families, so a monospace font you uploaded cannot replace
  text set in Arial.
- **Failures.** A character no font covers fails the render with `ASSET_INVALID`
  (`font_glyphs_missing`): upload a font that covers it and use it in your CSS. A font file that
  cannot be read fails with `ASSET_INVALID` (`font_invalid`). See [errors](/clients/http/).

## Images

- **Formats.** PNG, JPEG and SVG.
- **Referencing.** Upload the image to the workspace and name it by path from `src` or CSS
  `url()`, or embed it with `{#asset path @encoding=dataURI}`.
- **No network.** Images at external `https://` URLs are not fetched. Upload them, or send them
  in your data as `data:` URLs.
- **Failures.** An image that cannot be decoded fails with `ASSET_INVALID` (`image_invalid`).

## Chrome compatibility

The renderer lays out HTML as Chrome prints it, including in these cases:

- **HTML parsing** follows Chrome, which repairs unclosed tags and the like. Links are blue and
  underlined, and tables without a width shrink to their content, as in Chrome.
- **Wide documents shrink to fit.** A document wider than the page area is laid out on a larger
  page, up to twice the size, and scaled down onto the paper, header and footer included.
- **Full-page sections.** With `html, body { height: 100% }`, a percentage height on a child of
  `body` is a share of the page.
- **Grids with a fixed column.** In a grid that mixes `auto` and fixed-size tracks, the auto track
  may shrink so the fixed track stays on the page. A `min-width` on the grid's items opts out.
- **Images.** An image with `width: 100%` is laid out as a block. An image alone in its container
  with `max-width` (and `max-height`) is scaled down with its aspect ratio kept.
- **Percentage widths on inline blocks and floats** keep their size.
- **Row heights.** A `height` on a table row applies to its cells.
- **Line breaks.** Spaces around `<br>` and at the start or end of a block add no indentation.

## See what the renderer received

When the PDF of an HTML template looks different from what you expect, request a preview,
`POST /v1/templates/{id}/preview`, with `"format": "html"`. It returns the filled HTML, with its
stylesheets, header and footer, as one page you can open in a browser. See the
[API reference](/reference/api/).

---

# Handlebars templates

Source: https://docs.typefold.dev/templates/handlebars/

An HTML template is a `template.html` file written with [Handlebars](https://handlebarsjs.com/guide/)
4.7, such as `{{invoice.number}}`. Its **Page header** (`header.html`) and **Page footer**
(`footer.html`) are Handlebars too, with the same data, helpers and partials. Excel workbook
templates also use Handlebars; their cell and row helpers are in
[spreadsheet templates](/guides/spreadsheets/).

New to templates? Start with [build a template](/guides/first-template/).

```handlebars title="template.html"
<h1>Invoice {{invoice.number}}</h1>
{{#each lines}}
  {{component "components/line-row.html" currency=../currency}}
{{/each}}
<p>Total: {{sum lines "amount"}} {{currency}}</p>
```

## Where the data comes from

- **In Studio's preview**, the data is a sample data file, chosen in the **Data** box of the
  preview toolbar.
- **In production**, it is the `data` your application sends with the render request.

## What differs from plain Handlebars

- A missing value prints nothing and the render goes on. Test optional values with `{{#if}}`.
- A template whose output is empty fails with `400 BAD_REQUEST` ("The template rendered
  nothing.") instead of producing a blank PDF.
- `{{> line-row}}` looks for a partial file named `line-row`, `line-row.hbs`, `line-row.html` or
  `line-row.handlebars` in the template's folder, then in a `partials` folder there. See
  [how paths resolve](/templates/overview/#how-paths-resolve).

## Built-in helpers

Besides the standard Handlebars helpers (`if`, `unless`, `each`, `with`, `lookup`, `log`),
templates have:

| Helper                                             | What it does                                     | Details                                                   |
| -------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------- |
| `qrCode`, `barcode`                                | Draw a QR code or barcode from a value.          | [QR codes and barcodes](/features/qr-codes-and-barcodes/) |
| `component`                                        | Renders a partial file as a component.           | [Below](#reuse-a-block-with-component)                    |
| `localize`                                         | Prints a label from the active translation file. | [Translations](/features/translations/)                   |
| `pdfFormField`                                     | Adds a field the reader fills in.                | [Form fields](/features/form-fields/)                     |
| `pdfCreatePagesGroup`, `pdfAddPageItem`, `pdfDest` | Page data and link targets for other templates.  | [Combine templates](/features/combine-templates/)         |

There are no formatting helpers: format numbers, dates and amounts in
[your own helpers](#write-your-own-helpers); see
[translations and formatting](/features/translations/). A helper of your own named `qrCode`,
`barcode` or one of the `pdf…` helpers replaces the built-in one. Do not name your own helpers
`component` or `localize`: the built-in ones win.

### Reuse a block with `component`

`{{component "path"}}` renders a partial file with the caller's current data merged with the
arguments you pass:

```handlebars
{{#each lines}}
  {{component "components/line-row.html" currency=../currency}}
{{/each}}
```

- Inside the partial, that merged object is also `@root`.
- The partial does not see the caller's loop variables, such as `@index`. Pass them as
  arguments.

To build a whole document from JSON building blocks with no HTML, see
[component templates](/templates/components/).

## Write your own helpers

In Studio, open the template's **helpers.js** tab, under the HTML. Every top-level function is a
helper:

```js title="helpers.js"
function sum(items, field) {
  return items.reduce((total, item) => total + Number(item[field] ?? 0), 0);
}
```

```handlebars
<p>Total: {{sum lines "amount"}}</p>
```

- Helpers work as the [Handlebars guide](https://handlebarsjs.com/guide/expressions.html#helpers)
  describes: hash arguments, block helpers, `Handlebars.registerHelper`, `Handlebars.SafeString`
  and functions on `module.exports` all work.
- Helpers must return their value directly. An `async` helper, or one that returns a pending
  promise, fails with "Helper … must return synchronously".
- `require("moment")` formats dates and `require("bwip-js")` draws barcodes. See
  [translations and formatting](/features/translations/) and
  [QR codes and barcodes](/features/qr-codes-and-barcodes/).
- To share code with other templates, paste in a workspace file with
  `{#asset ./lib/money.js @encoding=utf8}`. The path starts from the file's own folder.

## Prepare data with a script

A script is a workspace file with a `beforeRender` function. It runs before the template and can
change the data, for example to sort lines or compute totals. Use a helper to format one value
where it is printed; use a script when several places need the same computed values.

1. In Studio's explorer, open the menu of the template's folder, choose
   **New entity → Script** and name it `totals.js`. Change `req.data` in `beforeRender`:

   ```js title="totals.js"
   function beforeRender(req, res) {
     const lines = req.data.lines ?? [];

     req.data.total = lines.reduce((sum, line) => sum + line.quantity * line.price, 0);
   }
   ```

2. Open the template, click **Template files** (the folder icon in the preview toolbar) and,
   under **Scripts**, tick `totals.js`.
3. Print the new value in the template, such as `<p>Total: {{total}}</p>`, and click
   **Update preview**.
4. Save the template and click **Publish**. Production renders use the script from this version
   on.

`async function beforeRender(req, res)` and the callback form `beforeRender(req, res, done)`
work too. A script without `beforeRender` fails with `400 BAD_REQUEST`, and one that declares
`afterRender` fails with `400 UNSUPPORTED_FEATURE`.

### What a script can read and change

| Field                                | Change | Meaning                                                                                         |
| ------------------------------------ | ------ | ----------------------------------------------------------------------------------------------- |
| `req.data`                           | Yes    | The render data. Must stay JSON.                                                                |
| `req.context`                        | Yes    | Starts empty. Passes values between scripts; it does not reach the template.                    |
| `req.template.name`                  | No     | The template's name.                                                                            |
| `req.template.localization.language` | No     | The `locale` in the template's `page.json`.                                                     |
| `req.options.localization.language`  | Yes    | The language of the render. Set it to render in another language.                               |
| `req.template.pdfMeta`               | Yes    | PDF properties: `title`, `author`, `subject`, `creator`, `producer`, `keywords` and `language`. |
| `req.template.pdfPassword`           | Yes    | Passwords and permissions. Absent when the template has none.                                   |

```js title="title.js"
function beforeRender(req, res) {
  req.template.pdfMeta = {
    ...req.template.pdfMeta,
    title: `Invoice ${req.data.invoice.number}`,
  };
}
```

- `req.template.pdfMeta` starts with the PDF properties in `page.json`, keywords joined by
  commas. What a script sets replaces them, and the request's own `metadata` wins over both.
  Setting `pdfMeta.language` changes only the PDF's language, not the translation file.
- `req.template.pdfPassword` holds `password`, `ownerPassword`, `printing` (`lowResolution` or
  `highResolution`; absent when printing is not allowed), and `modifying`, `copying`,
  `annotating`, `fillingForms`, `contentAccessibility` and `documentAssembly` as `true` or
  `false`. A script that sets it replaces the template's passwords entirely, so permissions it
  leaves out are not granted. The request's own `encryption` still wins. See
  [PDF standards and security](/guides/pdf-standards/).
- A language a script sets must be a language tag such as `de-CH`; anything else fails with
  `400 BAD_REQUEST`. How the language picks a translation file is in
  [translations](/features/translations/).
- `res` and any other change to `req` are discarded.

### Which scripts run

The button in a script's header sets when it runs:

| Studio label                           | Runs                                                                  |
| -------------------------------------- | --------------------------------------------------------------------- |
| **Runs where included** (the default)  | Only for templates that tick it under **Template files → Scripts**.   |
| **Runs before renders in this folder** | Before every render of a template in the script's folder or below.    |
| **Runs before every render**           | Before every render of an HTML or workbook template in the workspace. |

- "Runs before every render" scripts go first, then folder scripts, each group in name order,
  then the template's own scripts in the order ticked. They share one `req`, so a later script
  sees what earlier ones stored.
- Two scripts with the same name, or more scripts than the
  [limits](/clients/limits/) allow, fail the render with `400 BAD_REQUEST`.
- Component and spreadsheet (`sheets.json`) templates run no scripts and have no `helpers.js`.
- Editing, adding or rescoping a script changes previews at once, but production renders only
  after you publish the template again.

## Environment values

**Self-hosted installations only.** Scripts read per-environment values from `process.env`. They
come from the [`SCRIPT_ENV`](/self-hosting/configuration/#script_env) line in the server's `.env`
file, as comma-separated `NAME=value` pairs:

```sh title=".env"
SCRIPT_ENV=ADD_WATERMARK=true,COMPANY_CODE=ACME
```

- `process.env` holds only these values, nothing else from the server. Every workspace's scripts
  on the installation can read them, and scripts cannot change them.
- Names start with a letter or `_` and use letters, digits and `_`, each once. Values cannot
  contain commas, and surrounding spaces are trimmed.
- Values are always text: compare with `process.env.ADD_WATERMARK === "true"`. An unset name
  reads as `undefined`.
- Only scripts see `process.env`; `helpers.js` and the template do not. Pass a value on through
  `req.data`.
- A changed value applies once the server restarts with it, in previews too. The template needs
  no new publish.

For a worked example, see
[different settings per environment](/guides/environments/#different-settings-per-environment).

## Sandbox

Helpers, scripts and templates run in a sandbox:

- There is no network, file system, timers or browser API, and no npm packages: `require` gives
  you `moment` and `bwip-js`. Send everything a template needs in the data.
- Modern JavaScript syntax and built-ins work, except `Intl`.
- Variables in `helpers.js` do not carry over between renders.
- `console.log` and the `log` helper write to the **Profiler** tab of Studio's preview.

Time, memory and size limits are in [limits](/clients/limits/).

## When something goes wrong

A mistake in a script, helper or template fails the preview or render. In Studio, the error
appears in the preview pane and your edits stay. Through the API, it comes in the usual
[error envelope](/clients/http/). A helper that throws shows its own message after
`Handlebars render failed:`.

| Status and code           | Typical message                                       | What to do                                                             |
| ------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------- |
| `400 BAD_REQUEST`         | `Invalid Handlebars template: Parse error on line 4…` | Fix the template syntax at the reported line.                          |
| `400 BAD_REQUEST`         | `helpers.js: Unexpected token (3:14)`                 | Fix the JavaScript syntax in `helpers.js`.                             |
| `400 BAD_REQUEST`         | `Handlebars render failed: Missing helper: "fmt"`     | Define the helper, or fix its name.                                    |
| `400 BAD_REQUEST`         | `Script "totals.js": cannot read property…`           | Fix the named script. Check it against data shaped like the request's. |
| `400 BAD_REQUEST`         | `The template rendered nothing.`                      | Check the conditions around your content and the data you sent.        |
| `400 LIMIT_EXCEEDED`      | `Template execution limit exceeded.`                  | Look for endless loops, or move heavy work out of the template.        |
| `400 LIMIT_EXCEEDED`      | `Template memory limit exceeded.`                     | Send less data, or avoid building large strings and arrays.            |
| `400 UNSUPPORTED_FEATURE` | `Script "x.js": afterRender is not supported.…`       | Remove `afterRender`; only `beforeRender` runs.                        |

## Next steps

- [Build a template](/guides/first-template/): paper, margins, header and footer, fonts and
  images.
- [Translations and formatting](/features/translations/): languages, numbers, dates and time
  zones.
- [Render email and SMS text](/guides/string-rendering/) without a stored template.

---

# Templates and workspace files

Source: https://docs.typefold.dev/templates/overview/

A template is a document layout that you keep in your workspace and fill with data each time you
render. You edit its draft in Studio, preview it with sample data, and publish it as a numbered
version that your applications render. To build one step by step, start with
[build a template](/guides/first-template/).

<figure class="diagram"><svg viewBox="0 0 720 250" role="img" aria-label="You create a template and edit its draft. Saving keeps a revision, previewing renders the draft without saving, and publishing freezes it into a numbered version that renders to PDF or XLSX."><defs><marker id="d-workflow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path class="head" d="M0 0L10 5L0 10z"/></marker></defs><rect class="box" x="10" y="100" width="100" height="48" rx="8"/><text class="title" x="60.0" y="129.0" text-anchor="middle">Create</text><path class="line" d="M110 124H156" marker-end="url(#d-workflow)"/><rect class="box accent" x="160" y="96" width="130" height="56" rx="8"/><text class="title" x="225.0" y="120.0" text-anchor="middle">Draft</text><text class="sub" x="225.0" y="138.0" text-anchor="middle">what you edit</text><path class="line" d="M290 116C330 116 330 37 366 37" marker-end="url(#d-workflow)"/><text class="label" x="318" y="60" text-anchor="end">save</text><path class="line" d="M290 124H366" marker-end="url(#d-workflow)"/><text class="label" x="330" y="114" text-anchor="middle">preview</text><path class="line" d="M290 132C330 132 330 211 366 211" marker-end="url(#d-workflow)"/><text class="label" x="318" y="192" text-anchor="end">publish</text><rect class="box" x="370" y="10" width="190" height="54" rx="8"/><text class="title" x="465.0" y="33.0" text-anchor="middle">Revisions 2, 3…</text><text class="sub" x="465.0" y="51.0" text-anchor="middle">each save is kept</text><rect class="box" x="370" y="97" width="190" height="54" rx="8"/><text class="title" x="465.0" y="120.0" text-anchor="middle">Preview</text><text class="sub" x="465.0" y="138.0" text-anchor="middle">PDF, XLSX or HTML; nothing saved</text><rect class="box" x="370" y="184" width="190" height="54" rx="8"/><text class="title" x="465.0" y="207.0" text-anchor="middle">Version 1, 2…</text><text class="sub" x="465.0" y="225.0" text-anchor="middle">frozen and self-contained</text><path class="line" d="M560 211H606" marker-end="url(#d-workflow)"/><text class="label" x="583" y="203" text-anchor="middle">render</text><rect class="box" x="610" y="187" width="100" height="48" rx="8"/><text class="title" x="660.0" y="216.0" text-anchor="middle">PDF / XLSX</text></svg></figure>

## Kinds of templates

Create a template in Studio's explorer with **New entity → Template** (in the **+** menu or a
folder's **…** menu). **Start with** decides its kind:

| **Start with**                        | Source file                              | Renders     | Learn more                                     |
| ------------------------------------- | ---------------------------------------- | ----------- | ---------------------------------------------- |
| Blank template, Invoice example       | `template.html`                          | PDF         | [Handlebars templates](/templates/handlebars/) |
| PDF file, drafted with AI             | `template.html`                          | PDF         | [From a PDF](#from-a-pdf)                      |
| HTML file (upload one, up to 1 MB)    | `template.html`                          | PDF         | [Handlebars templates](/templates/handlebars/) |
| Excel workbook (XLSX)                 | `template.html` and the uploaded `.xlsx` | XLSX        | [Spreadsheet templates](/guides/spreadsheets/) |
| Spreadsheet (XLSX and PDF tables)     | `sheets.json`                            | XLSX or PDF | [Spreadsheet templates](/guides/spreadsheets/) |
| Not in Studio; create it with the API | `composition.json`                       | PDF         | [Component templates](/templates/components/)  |

A template has exactly one source, and the source decides what it can render. **Invoice example**
and **Spreadsheet** also create a `sample.json` data file beside the template (in a new folder named
after the template when you create it at the workspace root).

### From a PDF

**PDF file, drafted with AI** turns a PDF you already send, such as an invoice from your current
system, into a template that looks like it. Upload a PDF of up to 10 MB and 10 pages, without a
password.

1. Claude, Anthropic's AI, reads the PDF and writes a draft: `template.html` with the layout and
   fixed text, and a `sample.json` with the values that change from one document to the next.
2. Typefold renders the draft, compares it with your PDF page by page and sends the differences
   back, a few times, until the draft matches closely.
3. The best draft opens as a template in a new folder named after it, with `sample.json` and the
   PDF's raster images beside it. Edit it like any other template, then publish it.

It usually takes two to five minutes; you can close the window meanwhile. Fonts are replaced with
Arial, and vector logos with a box of the same size, so upload your fonts and logo afterwards.

The PDF and the images of each draft go to Anthropic; Typefold doesn't keep the PDF. On the hosted
service, see the [privacy policy](/legal/privacy/). Each plan allows a number of templates from a
PDF a month, shown under **Manage → Render limits**.

## The files of a template

A template's tab in Studio shows its source on top and its other files in tabs below it. An
**Export folder** zip holds each of them as a file.

| Studio tab       | File                                                 | What it holds                                                                                     |
| ---------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Source (top)     | `template.html`, `sheets.json` or `composition.json` | The body of the document.                                                                         |
| **helpers.js**   | `helpers.js`                                         | Your JavaScript helpers. HTML templates only; see [Handlebars templates](/templates/handlebars/). |
| **Page header**  | `header.html`                                        | Handlebars drawn in the top margin of every page. Not for spreadsheet templates.                  |
| **Page footer**  | `footer.html`                                        | Handlebars drawn in the bottom margin of every page. Not for spreadsheet templates.               |
| **page.json**    | `page.json`                                          | Paper, margins, language and PDF options; see [page.json](#pagejson).                             |
| **fields.json**  | `fields.json`                                        | The [content fields](/templates/content-fields/) a content editor may change.                     |
| **content.json** | `content.json`                                       | The values of those fields.                                                                       |

- The **Page header**, **Page footer**, **fields.json** and **content.json** tabs show once they
  have content. Add them with the **+** (**Add a file**) at the end of the tab bar. Page numbers and the other
  header and footer markup are in [build a template](/guides/first-template/).
- HTML templates also have a **Bindings** tab, which lists every placeholder in the HTML and the
  value the sample data gives it.
- Everything else a template uses is a [workspace file](#workspace-files-and-folders) that it
  names by path. The preview toolbar sets three of them:
  - **Data**: the sample data file previews render with. Pick one in or under the template's
    folder.
  - **Template files** (the folder icon): the stylesheets the template applies and the
    `beforeRender` scripts it runs, in the order you tick them. Up to 20 stylesheets and 10
    scripts.
  - **Workbook**, for an Excel workbook template: the `.xlsx` file it fills.

## page.json

`page.json` sets the template's paper and the PDF's defaults. Edit it in the **page.json** tab,
or use **PDF properties** in the preview toolbar, which edits the same settings in a form.

```json title="page.json"
{
  "pageSize": { "widthMm": 210, "heightMm": 297 },
  "orientation": "portrait",
  "margins": { "topMm": 15, "rightMm": 15, "bottomMm": 20, "leftMm": 15 },
  "locale": "en-GB",
  "metadata": { "title": "Invoice {{invoice.number}}" }
}
```

| Setting             | Default    | What it does                                                                                                                                            |
| ------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pageSize`          |            | Required. `widthMm` and `heightMm`, each above 0 and up to 2,000.                                                                                       |
| `orientation`       | `portrait` | `portrait` or `landscape`.                                                                                                                              |
| `margins`           |            | Required. `topMm`, `rightMm`, `bottomMm` and `leftMm`, each 0 to 500.                                                                                   |
| `locale`            | `en-US`    | The template's language: picks the translation file and sets the PDF's language. See [translations](/features/translations/).                           |
| `pageRanges`        |            | Pages to keep, such as `1-5, 8, 11-`. Page numbers still count the whole document.                                                                      |
| `metadata`          |            | PDF properties such as title, author and subject. Values may use `{{path}}` placeholders. See [PDF standards and security](/guides/pdf-standards/).     |
| `encryption`        |            | Passwords and permissions. Passwords may use `{{path}}` placeholders. See [PDF standards and security](/guides/pdf-standards/).                         |
| `signature`         |            | Sign with a workspace signing certificate. See [PDF standards and security](/guides/pdf-standards/).                                                    |
| `operations`        |            | Up to 10 steps that add another template's pages before or after this one, or draw them onto it. See [combine templates](/features/combine-templates/). |
| `pdfa`              |            | The PDF/A level to write and check. See [PDF standards and security](/guides/pdf-standards/).                                                           |
| `pdfua`             |            | The PDF/UA part to write and check. See [PDF standards and security](/guides/pdf-standards/).                                                           |
| `opaqueFills`       |            | `true` draws see-through content (CSS `opacity`, translucent colours) at full strength. Shown in **PDF properties** as **Ignore opacity**.              |
| `preferCssPageSize` |            | `true` prints on the paper a CSS `@page { size }` rule names instead of `pageSize`. See [supported CSS](/templates/css-support/).                       |

A [Reports API](/guides/reports/) request or a preview can override most of these for one render.

## Workspace files and folders

Templates and workspace files sit together in one tree of folders in Studio's explorer. One file
can be used by many templates, so a shared stylesheet or logo is edited in one place. Create a
file with **New entity** and the kind below, or drop files into **Import…**:

| **New entity** | Default name        | Holds                                                                                                           |
| -------------- | ------------------- | --------------------------------------------------------------------------------------------------------------- |
| Sample data    | `data.json`         | Data for previews. Must be valid JSON. Production renders use the data you send instead.                        |
| Localization   | `en.json`           | Translation labels, named for a language tag such as `de-CH.json`. See [translations](/features/translations/). |
| Partial        | `partial.html`      | A reusable piece of Handlebars, used with `{{> name}}` or `{{component "path"}}`.                               |
| Script         | `shared-helpers.js` | A `beforeRender` script. See [Handlebars templates](/templates/handlebars/).                                    |
| Stylesheet     | `shared-styles.css` | CSS, ticked under **Template files** or included with `{#asset}`.                                               |
| Asset          | the uploaded name   | An uploaded font, image, `.xlsx` workbook or PDF file.                                                          |

- Names are unique within a folder, ignoring case.
- A file's header in Studio shows **Used by** with the templates that use it, and their live
  version. Saving a shared file saves it straight to the workspace; it has no draft of its own.
- In the explorer, **Clone**, **Cut**, **Copy** and **Paste** copy or move templates, files and
  folders. A copy of a template is a new template that has not been published.
- Size and count limits are in [limits](/clients/limits/).

### How paths resolve

A template names a file by its path, such as `styles/invoice.css`. Keep a template's files in its
folder or in subfolders of it.

| Reference                                  | Example                                      | Where it looks                                                                                              |
| ------------------------------------------ | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Partial                                    | `{{> lines}}`                                | The referencing file's folder, then its `partials` subfolder. Also tries `.hbs`, `.html` and `.handlebars`. |
| Component                                  | `{{component "components/row.html"}}`        | The referencing file's folder, then the template's folder.                                                  |
| Include                                    | `{#asset styles/theme.css @encoding=utf8}`   | The referencing file's folder, then the template's folder. Includes can nest.                               |
| Embedded font or image                     | `{#asset fonts/brand.ttf @encoding=dataURI}` | As for an include.                                                                                          |
| HTML `src`, CSS `url()`                    | `src="./images/logo.svg"`                    | The referencing file's folder.                                                                              |
| **Data**, **Template files**, **Workbook** | `sample.json`                                | The template's folder.                                                                                      |
| Translation files                          | `de-CH.json`                                 | The template's folder and its `localizations` subfolder.                                                    |

- In a `{#asset}` or `{{component}}` path, a leading `/` starts at the workspace root.
- `../` goes up a folder; above the root it stays at the root.
- Folder and file names match ignoring case.
- Quote paths that contain spaces or parentheses: `url("../Client (2)/logo.png")`,
  `{#asset "../Client (2)/theme.css" @encoding=utf8}`.
- An `{#asset}` path may end in Handlebars, such as `{#asset ./icons/{{icon}}.svg @encoding=dataURI}`.
  Publishing then copies every uploaded file directly in that folder (`./icons`, not its
  subfolders) into the version.
- A `src` or `url()` value without a `/` that starts with no `.` and matches no file is left as
  it is.

### Missing and moved files

Renaming or moving a file, folder or template never rewrites the paths that point to it. Saving
does not check paths; previewing and publishing do. A missing file, or a file of the wrong kind
(such as a font included with `@encoding=utf8`), fails with `400 ASSET_INVALID` and lists each
path with the file that names it. Files that include each other in a loop fail with
`400 BAD_REQUEST`.

## Drafts and history

The **draft** is what you edit. **Save** in the editor header (or Ctrl+S, Cmd+S on a Mac) saves
it as a new revision. Revision 1 is the template as it was created or imported, and every save
adds one. Revisions cannot be changed or deleted.

**History** compares any two revisions file by file, including which data, stylesheets and
scripts the template used. **Restore revision** loads one into the editor as unsaved edits;
click **Save** to keep it.

If someone else saved the draft since you opened it, your save fails and your edits stay in the
editor. Copy your changes, reload the template, and apply them again.

## Preview

**Update preview** renders what is in the editor, unsaved edits included, with the sample data
file chosen in **Data**. Nothing is saved or published.

- **Output** switches between XLSX and PDF for a spreadsheet template.
- **Preview** picks one of the template's translation languages for this preview only. It shows
  once the template has a translation file.
- The **Profiler** tab shows how long the render took and any `console.log` output from helpers
  and scripts.
- **Check accessibility and conformance** checks the PDF against PDF/A and PDF/UA. See
  [PDF standards and security](/guides/pdf-standards/).
- Shared files render as last saved. An unsaved sample data file open in another tab is the
  exception: the preview uses its text as it is.

A PDF preview counts against your render allowances like any render. An XLSX preview does not
count, but it is refused while the allowances are used up. See [limits](/clients/limits/).
Through the API, a preview can also return the filled HTML before PDF layout; see the
[API reference](/reference/api/).

## Publish a version

**Publish** in the editor header publishes the saved draft as the template's next version: 1, 2, 3
and so on. Save first; **Publish** is unavailable while there are unsaved changes, and when the
saved draft is already live. The status beside the template's name shows where it stands:

| Status                       | Meaning                                          |
| ---------------------------- | ------------------------------------------------ |
| **Unsaved changes**          | The editor holds edits that are not saved.       |
| **Saved · not published**    | The template has never been published.           |
| **Saved · changes since v2** | The saved draft differs from the live version 2. |
| **Published v2**             | The saved draft is live as version 2.            |

Publishing copies into the version every file the template uses at that moment: partials,
stylesheets, scripts (including folder and workspace-wide ones), translations, sample data,
fonts, images and the workbook. It does not render the template, so preview first.

### When changes go live

- Editing the draft or a shared file changes the **next preview and the next publish** of every
  template that uses it.
- A version keeps its own copy of every file. What your applications render does not change until
  you publish again, and deleting or editing a file never breaks a version.
- Versions cannot be changed or deleted.
- A version freezes your template, not Typefold itself. An upgrade of Typefold that fixes
  layout can change the output of an existing version.

To render the latest version by name, use the [Reports API](/guides/reports/). To render one
specific version as a background job, use the [Renders API](/guides/rendering/).

## Import files and templates

In the explorer, click **+ → Import…**, or **Import into folder…** in a folder's **…** menu, then
drop files or a folder:

| You drop                                                   | Studio                                                                                                                                                                                 |
| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A project folder                                           | Creates a new template, in a folder of its own, from the HTML and its files.                                                                                                           |
| A `.zip` made by **Export folder** or **Export workspace** | Updates the folders, files and templates it holds, and creates the rest. See [deploy across environments](/guides/environments/).                                                      |
| A report archive from another tool                         | Imports its templates. See [migrating](/guides/jsreport-import/).                                                                                                                      |
| Other files                                                | Adds them to the folder: `.css` as a stylesheet, `.js` as a script, `.html` as a partial, a language-named `.json` as a translation, other `.json` as data, anything else as an asset. |

A project folder has exactly one `.html` file and at most one `.js` helpers file at the top
level, optional `.css` files, optional `data/`, `localizations/` and `partials/` folders, and
images (`.png`, `.jpg`, `.svg`) and fonts (`.woff2`, `.ttf`, `.otf`) in named folders such as
`fonts/`. It holds at most 245 files and 10 MB. Imported templates arrive as drafts: preview them,
then publish each one.

## Delete templates and folders

Choose **Delete** in a template's or folder's **…** menu in the explorer.

- Deleting a folder deletes everything in it. It is refused while a template or file outside the
  folder still uses one of its files.
- A single workspace file cannot be deleted on its own, only with its folder.
- There is no undo. New renders of a deleted template fail with `404 NOT_FOUND`, including renders
  by name. Files already rendered are kept.

## Manage templates through the API

Everything on this page can also be done through the API, for example from a build script:
create templates, save drafts, read revisions, preview, publish, manage folders and files, and
import or export a zip. Reading needs the `template:read` scope, changing `template:write`, and
publishing `template:publish`; uploading fonts and images also needs `asset:manage`. See the
[API reference](/reference/api/) for every endpoint and field, and the
[HTTP API](/clients/http/) for keys and errors.

## Next steps

- [Build a template](/guides/first-template/) in Studio: paper, header and footer, fonts and images.
- [Handlebars templates](/templates/handlebars/): helpers, scripts and partials.
- [Combine templates](/features/combine-templates/): covers, terms and letterheads.
- [Deploy across environments](/guides/environments/): copy templates to another workspace or
  installation.

---

# Excel charts

Source: https://docs.typefold.dev/features/charts/

Design a chart in Excel once, then let each render fill it with that report's numbers. The
chart keeps the type, colors, fonts and layout you gave it; only the title and the series
data change.

Type this as the chart's title in Excel:

```handlebars
Sales {{year}}{{xlsxChart data=salesChart options=salesAxes}}
```

Render the template with this data:

```json
{
  "year": 2026,
  "salesChart": {
    "labels": ["Jan", "Feb", "Mar"],
    "datasets": [
      { "label": "Online", "data": [120, 150, 170] },
      { "label": "Store", "data": [90, 85, 110] }
    ]
  },
  "salesAxes": {
    "scales": { "yAxes": [{ "ticks": { "min": 0, "max": 200, "stepSize": 50 } }] }
  }
}
```

The chart's title becomes `Sales 2026`, it shows two series, Online and Store, over January
to March, and its value axis runs from 0 to 200 in steps of 50.

Charts work in [workbook templates](/guides/spreadsheets/), which render XLSX only.

## Set up the chart

1. In Excel, put a few sample values in some cells, for example on a second sheet, and insert
   one of the [supported chart types](#chart-types) from them. Style it as you want the output
   to look.
2. Click the chart title and type the text you want, with `{{xlsxChart data=...}}` anywhere in
   it. The tag itself prints nothing, so a title that is only the tag renders empty.
3. Save the `.xlsx` and upload it as a workbook template, as in
   [Spreadsheet templates](/guides/spreadsheets/).

How it fills the chart:

- The chart must have at least one series. Dataset 1 fills series 1, dataset 2 fills series 2,
  and so on, and each keeps that series' formatting.
- Series without a dataset are removed. Datasets beyond the chart's series are added after the
  last one, without its colors or marker symbol, so Excel picks their colors.
- The values are written into the chart itself, so the chart no longer reads the sample cells.
  The cells stay in the workbook as you left them.
- Other Handlebars in the title, such as `{{year}}`, renders with the template's data. A title
  with Handlebars but no `xlsxChart` keeps the chart's own data.
- Only the chart title is read; axis titles and other text are left as they are.

`data` and `options` are values from your data or from a helper call, such as
`data=(salesChartData rows)` with a helper of your own in `helpers.js`; see
[Handlebars templates](/templates/handlebars/).

## Chart data

`data` is an object with two arrays, and neither may be empty:

| Field                   | Holds                                                                                     |
| ----------------------- | ----------------------------------------------------------------------------------------- |
| `labels`                | The categories, or the X values for scatter and bubble charts.                            |
| `datasets`              | One object per series.                                                                    |
| `datasets[].label`      | The series name shown in the legend.                                                      |
| `datasets[].data`       | The values, one per label.                                                                |
| `datasets[].dataLabels` | Scatter charts only: a label per point. See [point labels](#point-labels-and-error-bars). |
| `datasets[].dataErrors` | Error bar amounts per point. See [error bars](#point-labels-and-error-bars).              |

## Chart types

| Excel chart                                    | `labels`                           | `datasets[].data`                     |
| ---------------------------------------------- | ---------------------------------- | ------------------------------------- |
| Column and bar (2-D: clustered, stacked, 100%) | Category names                     | Numbers                               |
| Line, line with markers (2-D)                  | Category names                     | Numbers                               |
| Stock                                          | Dates as `YYYY-MM-DD`              | Numbers, one dataset per price series |
| Scatter (X Y)                                  | X values                           | Y values                              |
| Bubble                                         | X values                           | `[y, size]` pairs                     |
| Waterfall, funnel                              | Category names                     | Numbers (first dataset only)          |
| Treemap, sunburst                              | Names, or a list of levels (below) | Sizes (first dataset only)            |
| Histogram                                      | Required, but not used             | The values to group into bins         |

- A combo chart, such as columns with a line, works when every part is a supported type.
  Datasets fill the series in the order Excel stores them.
- For a treemap or sunburst with several levels, give `labels` as one array per level, top level
  first, each as long as `data`:

  ```json
  {
    "labels": [
      ["Europe", "Europe", "Asia"],
      ["Germany", "France", "Japan"]
    ],
    "datasets": [{ "label": "Revenue", "data": [40, 25, 35] }]
  }
  ```

- Pie, doughnut, area, radar, surface, box and whisker, and 3-D charts are not supported. Their
  titles still render, but `xlsxChart` in them makes the render fail with an error such as
  `Chart "pieChart" type is not supported`.

## Axes

`options` sets the axes of column, bar, line, stock, scatter and bubble charts. It is ignored for
waterfall, funnel, treemap, sunburst and histogram charts.

```json
{
  "scales": {
    "xAxes": [{ "display": false }],
    "yAxes": [{ "display": true, "ticks": { "min": 0, "max": 200, "stepSize": 50 } }]
  }
}
```

| Field                    | Effect                                                     |
| ------------------------ | ---------------------------------------------------------- |
| `xAxes`                  | One entry per category axis, in the chart's order.         |
| `yAxes`                  | One entry per value axis, in the chart's order.            |
| `display`                | `false` hides the axis; any other value shows it.          |
| `ticks.min`, `ticks.max` | Value axes only: the lowest and highest value on the axis. |
| `ticks.stepSize`         | Value axes only: the distance between major gridlines.     |

Scatter and bubble charts have two value axes, so both are set through `yAxes`. An axis without
an entry keeps its Excel settings.

## Point labels and error bars

In a scatter chart, `dataLabels` puts a label on each point. Each item is a string, or an object
with `value` and `position` (`left`, `right`, `center`, `top` or `bottom`). Without a position,
a label keeps the position set in Excel, or goes to the right.

```json
{
  "labels": [1.2, 2.5, 3.1],
  "datasets": [
    {
      "label": "Plants",
      "data": [10, 14, 9],
      "dataLabels": ["Berlin", { "value": "Lyon", "position": "top" }, "Osaka"]
    }
  ]
}
```

In column, bar, line, stock, scatter and bubble charts, `dataErrors` sets error bars: one
`[plus, minus]` pair per point, where a missing value counts as 0. Add error bars to the series
in Excel first so they keep your style.

```json
{
  "label": "Online",
  "data": [120, 150, 170],
  "dataErrors": [
    [10, 5],
    [12, 12],
    [8, 4]
  ]
}
```

## When the render fails

The render fails when:

- `data` is missing, or `labels` or `datasets` is not a non-empty array.
- `options` is not an object.
- The chart has no series.
- The chart type is not supported.
- A stock chart label is not a `YYYY-MM-DD` date, or a bubble chart value is not a `[y, size]` pair.
- `dataLabels` or `dataErrors` is not an array.

## Charts in PDF documents

`xlsxChart` fills charts in Excel files only. HTML templates do not run JavaScript, so a chart
in a PDF must be an image; see [What's not supported](/start/not-supported/).

---

# Combine templates

Source: https://docs.typefold.dev/features/combine-templates/

Build one document from several templates: a cover before the invoice, terms and conditions
after it, a letterhead or a "DRAFT" watermark on every page, a table of contents, or a section
name on each page. Each part is an ordinary template in the same workspace, so you design it
once and reuse it everywhere. A part can also be a PDF file you upload, such as a supplier's
terms or a form your template fills in; see [add an uploaded PDF file](#add-an-uploaded-pdf-file).

```json title="page.json"
{
  "operations": [
    { "type": "prepend", "template": "Cover" },
    { "type": "append", "template": "Terms" },
    { "type": "merge", "template": "Letterhead" }
  ]
}
```

With these steps, a render of the invoice returns the cover, the invoice and the terms in one
PDF, with the letterhead drawn beneath the content of every page.

## Add pages before or after

1. Create the other template, such as `Terms`, and publish it.
2. In the template that adds it, click **PDF properties** in the preview toolbar. Under
   **Other templates and PDF files**, click **Add template**.
3. Choose the template, then choose what to do with it:

   | Studio                      | `type`    | What it does                                                                           |
   | --------------------------- | --------- | -------------------------------------------------------------------------------------- |
   | **Add its pages before**    | `prepend` | Adds all its pages before the document's pages, such as a cover.                       |
   | **Add its pages after**     | `append`  | Adds all its pages after them, such as terms and conditions.                           |
   | **Draw it onto every page** | `merge`   | Draws it onto the document's pages. See [draw onto every page](#draw-onto-every-page). |

4. Click **Update preview** to see the added pages, then save and publish the template.

Studio writes each step to the `operations` list in the template's **page.json**, and you can
edit that list there instead.

## Draw onto every page

A `merge` step draws the other template onto the document's pages, beneath the content, like
printed letterhead paper. Its first page is drawn onto every page, at its own size from the
page's top-left corner, so give it the same paper size as the document.

For a step that draws, tick any of these in Studio:

| Studio                      | Field                | What it does                                                                                                                                                               |
| --------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Page by page**            | `mergeWholeDocument` | Draws its page 1 onto page 1, its page 2 onto page 2, and so on. Pages beyond its last page get nothing.                                                                   |
| **Render for every page**   | `renderForEveryPage` | Renders it once for each page, so it can show that page's details. See [print something on each page](#print-something-different-on-each-page). Not with **Page by page**. |
| **In front of the content** | `mergeToFront`       | Draws it over the content instead of beneath it.                                                                                                                           |

A watermark is a template drawn in front of the content. Make a template named `Watermark` with
no margins:

```json title="page.json"
{
  "pageSize": { "widthMm": 210, "heightMm": 297 },
  "margins": { "topMm": 0, "rightMm": 0, "bottomMm": 0, "leftMm": 0 }
}
```

```handlebars title="template.html"
<div style="height: 297mm; display: flex; align-items: center; justify-content: center;">
  <div style="transform: rotate(-45deg); font-size: 120pt; color: #e11d48; opacity: 0.15;">
    DRAFT
  </div>
</div>
```

Then add it to the document as a step:

```json title="page.json"
{ "type": "merge", "template": "Watermark", "mergeToFront": true }
```

Steps run in the order listed, and a `merge` draws onto the pages the document has at that
point. Put it last to draw onto added pages too, or before them to leave the cover and terms
plain.

## Add an uploaded PDF file

A step can add a PDF file instead of a template, such as terms you received as a PDF. Add the
file to the template's folder with **Import into folder…** in the folder's **…** menu, then in
**PDF properties** under **Other templates and PDF files**, click **Add PDF file** and choose it.
In page.json, the step names the file's path with `pdf` instead of `template`:

```json title="page.json"
{
  "operations": [{ "type": "append", "pdf": "terms.pdf" }]
}
```

The path starts at the template's folder, like the template's other
[workspace files](/templates/overview/). Every step type works with a file: `prepend` and
`append` add all its pages, and `merge` draws its first page, or with `mergeWholeDocument` its
page N onto page N. A file has no data to fill in, so `renderForEveryPage` does not apply.

### Fill in a supplier's form

To fill in a PDF form you received, draw it beneath your document page by page. Make a template
with the form's paper size and no margins, and place each value where the form has its box:

```handlebars title="template.html"
<div style="position: relative; height: 297mm;">
  <div style="position: absolute; top: 52mm; left: 40mm;">{{customer.name}}</div>
  <div style="position: absolute; top: 61mm; left: 40mm;">{{orderNumber}}</div>
</div>
```

Then draw the form beneath it:

```json title="page.json"
{
  "pageSize": { "widthMm": 210, "heightMm": 297 },
  "margins": { "topMm": 0, "rightMm": 0, "bottomMm": 0, "leftMm": 0 },
  "operations": [{ "type": "merge", "pdf": "forms/order-form.pdf", "mergeWholeDocument": true }]
}
```

The document keeps its own pages, so give the template one page for each page of the form: a
form page with no page of the template to draw onto is left out. The form's own fillable fields
are not filled in; your template draws the values over them.

## Use the document's pages in the other template

The other template can read `$pdf`, the document's pages as they are when its step runs, to
print a table of contents or details that change from page to page.

In the document, mark where each section starts with `pdfCreatePagesGroup`, and add a link
target with `pdfDest`. Print both with triple braces:

```handlebars title="template.html"
{{#each sections}}
  <h2>{{title}}{{{pdfCreatePagesGroup title=title id=id}}}{{{pdfDest id}}}</h2>
  <p>{{body}}</p>
{{/each}}
```

The other template then has:

| Field             | What it holds                                                                                                                                                                              |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `$pdf.pages`      | One entry per page of the document so far. Each has `group`, the value of the last `pdfCreatePagesGroup` on or before that page, and `items`, the values of `pdfAddPageItem` on that page. |
| `$pdf.pageIndex`  | With **Render for every page**: the page it is drawn onto, from 0.                                                                                                                         |
| `$pdf.pageNumber` | With **Render for every page**: the same page, from 1.                                                                                                                                     |

| Helper                            | What it does                                                                                                                                |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `{{{pdfCreatePagesGroup value}}}` | Sets the group of the page it is on, and of the pages after it until the next group. The value can be any data, or hash arguments as above. |
| `{{{pdfAddPageItem value}}}`      | Adds the value, or the hash arguments, to the `items` of the page it is on.                                                                 |
| `{{{pdfDest "name"}}}`            | Marks a place that a `#name` link in any part of the document leads to. See [link between parts](#link-between-parts).                      |

Keep these helpers out of elements with `display: inline-block`, where they are not found.

The other template still gets the document's data, with `$pdf` added. Read `$pdf` in its HTML,
its page header and footer, or its [helpers.js](/templates/handlebars/). Its scripts run before
the pages exist, so they cannot read it, and only an HTML template can read it, not a component
template.

### Print a table of contents

Make a template named `Contents` that lists the first page of each group. In its **helpers.js**:

```js title="helpers.js"
function sections(pages, offset) {
  const result = [];

  pages.forEach((page, index) => {
    const last = result[result.length - 1];

    if (page.group !== undefined && (last === undefined || last.id !== page.group.id)) {
      result.push({ ...page.group, page: index + 1 + offset });
    }
  });

  return result;
}
```

```handlebars title="template.html"
<h1>Contents</h1>
<ul>
  {{#each (sections $pdf.pages 1)}}
    <li><a href="#{{id}}">{{title}}</a>, page {{page}}</li>
  {{/each}}
</ul>
```

Add it to the document with **Add its pages before** (`prepend`). The page numbers count the
document as it is before the contents are added, so `offset` adds the contents' own length,
here one page.

### Print something different on each page

Add the other template with **Draw it onto every page** and tick **Render for every page**. It
renders once for each page, with `$pdf.pageIndex` and `$pdf.pageNumber` naming the page it is
drawn onto. This template prints the section name and a page number that restarts in each
section, at the bottom of every page:

```js title="helpers.js"
function sectionPage(pages, index) {
  let start = index;

  while (start > 0 && pages[start - 1].group?.id === pages[index].group?.id) {
    start -= 1;
  }

  return index - start + 1;
}
```

```handlebars title="template.html"
<div style="height: 297mm; position: relative;">
  <div style="position: absolute; bottom: 10mm; left: 18mm; right: 18mm; font-size: 9pt;">
    {{#with (lookup $pdf.pages $pdf.pageIndex)}}{{group.title}}{{/with}}, page
    {{sectionPage $pdf.pages $pdf.pageIndex}}
  </div>
</div>
```

Give it the document's paper size and no margins, as for the watermark above. For a plain
"Page 1 of 3" footer you need no other template: use the template's own page footer, see
[build a template](/guides/first-template/).

## Link between parts

Mark a place with `{{{pdfDest "terms"}}}` in one template, and link to it with
`<a href="#terms">` from any template in the same document, such as from the invoice to its
terms. `{{{pdfDest id="terms"}}}` works too. A link to an `id` in the same template works as
usual, and a link to a name that no part defines is left as plain text.

## Rules

- The other template renders with the same data and language as the document, on its own
  paper size, margins, page header and footer.
- Studio previews use the other template's saved draft. Every other render uses its published
  version, so publish it first. When you publish a new version of it, every template that adds
  it uses that version from then on. See [publishing](/templates/overview/).
- An uploaded PDF file is read when the document renders, so replacing the file changes every
  render from then on, without publishing again. Publishing checks that the file exists; if it
  is deleted or moved later, renders fail.
- An uploaded PDF file can be up to 5 MB, and it cannot be encrypted. It counts toward the
  render's input size, and in a [batch](/guides/batch-rendering/) every document carries it, so a
  large file leaves room for fewer documents; see [limits](/clients/limits/).
- Added pages from an uploaded file keep their look and their bookmarks, but not their fillable
  form fields or their links to named places inside the file.
- Templates are found by name, ignoring case. If none has that name, Studio warns under
  **Other templates and PDF files** and renders fail until one is created and published.
- A template can have up to 10 steps. A template that another one adds cannot have steps of its
  own, and a spreadsheet template cannot be added.
- Steps run only when you render a template: by name with the [Reports API](/guides/reports/),
  or a template version with the [Renders API](/guides/rendering/). A render of raw HTML and a
  [string render](/guides/string-rendering/) cannot have steps.
- A Reports API request can replace the template's steps with `pdf.operations`, and an empty
  list runs none. See the [API reference](/reference/api/).
- The added pages count toward the page limit; see [limits](/clients/limits/).
- If the other template or PDF file fails, the error message names it.
- A PDF/A or PDF/UA document keeps its standard with parts from other templates. In a PDF/UA
  document, pages added before or after keep their headings and bookmarks, and a drawn
  template is decoration that screen readers skip. See [PDF standards](/guides/pdf-standards/).
- A PDF/A or PDF/UA document cannot add an uploaded PDF file, since nothing checks that the file
  meets the standard. Rebuild that part as a template instead.

---

# Fillable form fields

Source: https://docs.typefold.dev/features/form-fields/

Turn a rendered document into a form: application forms, order sheets, consent forms and
contracts with a place to sign. The reader fills the fields in their PDF viewer and can save or
submit the result.

```handlebars
<p>Name: {{{pdfFormField name="name" type="text" width="200px" height="20px" value=user.name}}}</p>
<p>Plan: {{{pdfFormField name="plan" type="combo" width="120px" height="20px" items=plans}}}</p>
<p>{{{pdfFormField name="agree" type="checkbox" width="14px" height="14px"}}} I agree</p>
<p>Signature: {{{pdfFormField name="sign" type="signature" width="200px" height="40px"}}}</p>
```

With the data `{ "user": { "name": "Ada Lovelace" }, "plans": ["Basic", "Pro"] }`, the name box
starts filled in and the list offers both plans.

`pdfFormField` works in an HTML template's Handlebars source. Print it with triple braces. The
field sits inline in the text where you print it, at the size you give.

## Pick the field type

| `type`      | Adds                                                                                  |
| ----------- | ------------------------------------------------------------------------------------- |
| `text`      | A text box. Add `multiline=true` for several lines, `password=true` to hide the text. |
| `checkbox`  | A check box.                                                                          |
| `combo`     | A drop-down list of `items`.                                                          |
| `button`    | A push button that submits or resets the form.                                        |
| `signature` | An empty signature field the reader signs in their viewer.                            |

A signature field is only a place to sign. To sign the document with your own certificate when it
renders, see [PDF standards and signatures](/guides/pdf-standards/).

## Arguments

Every field needs `name`, `type`, `width` and `height`. Sizes are in `px`, such as `width="200px"`.

| Argument                           | Applies to            | What it does                                                                                                                                                                    |
| ---------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                             | all                   | The field's name, which a submitted form sends its value under.                                                                                                                 |
| `value`, `defaultValue`            | text, combo, checkbox | The value it starts with, and the value a reset restores.                                                                                                                       |
| `label`                            | all                   | The text a screen reader announces, and a button's caption. Without it, the name is used.                                                                                       |
| `fontFamily`, `fontSize`           | all but checkbox      | One of the 14 standard PDF fonts, such as `Helvetica` (the default), `Times-Roman` or `Courier`, and a size in `px`. Without `fontSize`, the viewer fits the text to the field. |
| `color`                            | all                   | The text color, or a check box's mark, as `#rrggbb`, `#rgb` or `rgb(r, g, b)`.                                                                                                  |
| `backgroundColor`                  | all                   | The fill color, in the same forms.                                                                                                                                              |
| `border`                           | all                   | Three numbers separated by commas: horizontal and vertical corner radius, then width. `"0,0,1"` draws a thin border. No border by default.                                      |
| `textAlign`                        | all                   | `left` (the default), `center` or `right`.                                                                                                                                      |
| `readOnly`, `required`, `noExport` | all                   | `true` makes the field read-only, required, or left out when the form is submitted.                                                                                             |
| `multiline`, `password`            | text                  | `true` allows several lines, or hides what the reader types.                                                                                                                    |
| `items`                            | combo                 | The choices, as an array from your data or a string separated by commas, such as `"Basic,Pro"`. Required.                                                                       |
| `visualType`                       | checkbox              | `check` (the default) draws a check mark, `square` a filled square.                                                                                                             |
| `action`, `url`                    | button                | `submit` sends the form to `url`; `reset` restores every field's `defaultValue`.                                                                                                |

Write `true` without quotes, as in `readOnly=true`. A quoted `"true"` is ignored.

A comma-separated `items` string is split at each comma as is, so leave out spaces after the
commas or they become part of the choice.

### Check box values

A check box is ticked when its `value` (or, without one, its `defaultValue`) is `true` or any
other value except `false`, `0`, an empty string, `"false"`, `"0"`, `"off"` or `"no"`. Pass a
field from your data, as in `value=order.giftWrap`.

### Submit options

A `submit` button also takes these arguments, each set to `true` to turn it on: `exportFormat`,
`getMethod`, `XFDF`, `submitPDF`, `includeNoValueFields`, `includeAnnotations`,
`includeAppendSaves`, `submitCoordinates`, `canonicalFormat`, `exclNonUserAnnots`, `excldFKEy`
and `embedForm`. They are the PDF submit-form flags; without any, the viewer sends the values as
FDF.

## Format what the reader types

A text field can format its value as the reader types, in viewers that run form scripts, such as
Adobe Acrobat Reader. Set `formatType` and the arguments that go with it:

| `formatType`      | Arguments                                                                                                                                                                                                                                               |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `date`            | `formatMask`: a date pattern such as `"dd/mm/yyyy"` (`mm` is the month).                                                                                                                                                                                |
| `time`            | `formatMask`: `"HH:mm"`, `"hh:mm"`, `"HH:mm:ss"` or `"hh:mm:ss"`.                                                                                                                                                                                       |
| `number`          | `formatFractionalDigits` (0 to 10, default 0), `formatSepComma=true` for thousands separators, `formatNegStyle` (default `MinusBlack`), `formatCurrency` (a symbol such as `"€"`) and `formatCurrencyPrepend=false` to put the symbol after the number. |
| `percent`         | `formatFractionalDigits` and `formatSepComma`.                                                                                                                                                                                                          |
| `zip`, `zipPlus4` | A US ZIP code, or ZIP+4.                                                                                                                                                                                                                                |
| `phone`, `ssn`    | A US phone number, or a US Social Security number.                                                                                                                                                                                                      |

```handlebars
{{{pdfFormField
  name="amount"
  type="text"
  width="100px"
  height="20px"
  textAlign="right"
  formatType="number"
  formatFractionalDigits=2
  formatSepComma=true
  formatCurrency="€"
}}}
```

## Rules

- A missing `name`, `type`, `width` or `height`, a size without `px`, or an invalid argument
  fails the render with a message that says what is wrong.
- Keep a field out of elements with `display: inline-block`; a field there is not added.
- A PDF/A document cannot have form fields: the render fails with `UNSUPPORTED_FEATURE`. Turn
  PDF/A off for templates with fields. In a PDF/UA document each field is tagged as a form field
  and announced with its `label`. See [PDF standards](/guides/pdf-standards/).
- In a password-protected PDF, readers cannot fill the fields when the `fillingForms` and
  `annotating` permissions are both off; see [PDF standards](/guides/pdf-standards/).

---

# QR codes and barcodes

Source: https://docs.typefold.dev/features/qr-codes-and-barcodes/

Print a QR code or a barcode from any value in your data, for tickets, shipping labels, invoices
and product sheets. Each is drawn as a sharp vector image, an `<img>` element you can style.

```handlebars
<p>Ticket {{ticket.number}}</p>
{{qrCode ticket.url style="width: 30mm"}}
{{barcode ticket.number type="ean13" includetext=true style="height: 15mm"}}
```

`qrCode` draws a QR code; `barcode` draws Code 128 unless you pick another `type`. Both work in
an HTML template's source, its **Page header** and **Page footer**, and its partials.

## Pick the symbology

Set `type` to any symbology bwip-js supports, for example:

| `type`       | Draws                                |
| ------------ | ------------------------------------ |
| `qrcode`     | QR code. The default for `qrCode`.   |
| `code128`    | Code 128. The default for `barcode`. |
| `ean13`      | EAN-13 (12 or 13 digits).            |
| `ean8`       | EAN-8.                               |
| `upca`       | UPC-A.                               |
| `code39`     | Code 39.                             |
| `itf14`      | ITF-14 for shipping cartons.         |
| `gs1-128`    | GS1-128, with `(01)…` style data.    |
| `datamatrix` | Data Matrix.                         |
| `pdf417`     | PDF417.                              |
| `azteccode`  | Aztec code.                          |

See the [full list of barcode types](https://github.com/metafloor/bwip-js/wiki/BWIPP-Barcode-Types)
upstream.

## Size and options

Set a CSS `width` or `height` with `style` or `class`; the other side follows. Without one, each
module (the smallest bar or square) is 4 CSS pixels wide, so a QR code of a short value is about
22 mm wide.

Every other argument is passed to the encoder as an option:

```handlebars
{{qrCode order.trackingUrl eclevel="H" class="qr"}}
{{barcode sku height=10 includetext=true textxalign="center" barcolor="1F3A93"}}
```

| Argument                      | What it does                                                              |
| ----------------------------- | ------------------------------------------------------------------------- |
| `type`                        | The symbology. See above.                                                 |
| `class`, `style`              | Go on the image, to size and place it.                                    |
| `alt`                         | The image's alternative text. Defaults to the encoded value.              |
| `includetext`                 | `true` prints the value under the bars.                                   |
| `height`                      | Bar height of a linear barcode. `10` is about 15 mm at the default scale. |
| `scale`                       | Module size multiplier (default `2`), which changes the natural size.     |
| `eclevel`                     | A QR code's error correction: `L`, `M`, `Q` or `H`.                       |
| `rotate`                      | `N`, `R`, `L` or `I` to turn the symbol.                                  |
| `barcolor`, `backgroundcolor` | Colors as hex without `#`, such as `1F3A93`.                              |

Each symbology has more; see the
[options reference](https://github.com/bwipp/postscriptbarcode/wiki/Options-Reference) upstream.

Because `alt` is always set, the images have the alternative text that
[PDF/UA](/guides/pdf-standards/) requires.

## When a value cannot be drawn

The render fails, with a message saying why, when:

- the value is missing or empty (`qrCode needs a value to encode.`);
- the symbology cannot encode it, such as letters or the wrong number of digits in an EAN-13,
  or the `type` is unknown;
- the value is longer than 8,000 characters.

Wrap the helper in `{{#if}}` when the value is optional.

## Draw your own in helpers.js or a script

A function in the template's **helpers.js** tab, or in a script, can call bwip-js directly.
`toSVG(options)` returns SVG markup; print it with triple braces:

```js title="helpers.js"
const bwipjs = require("bwip-js");

function shippingCode(value) {
  return bwipjs.toSVG({ bcid: "datamatrix", text: String(value) });
}
```

```handlebars
<div style="width: 20mm">{{{shippingCode parcel.id}}}</div>
```

This SVG has no size of its own and fills its container, so size the element around it. See
[Handlebars templates](/templates/handlebars/) for helpers.js and scripts.

## Component and spreadsheet templates

[Component templates](/templates/components/) have no barcode component, but their **Page header**
and **Page footer** are Handlebars, so `qrCode` and `barcode` work there. For a barcode in the
body, use an HTML template.

[Spreadsheet templates](/guides/spreadsheets/) cannot draw QR codes or barcodes.

---

# Translations and formatting

Source: https://docs.typefold.dev/features/translations/

Keep one template and render it in every language your customers read. The labels live in
translation files, the request names the language, and numbers and dates are formatted to match.

```json title="de-CH.json"
{ "invoice": "Rechnung", "dueDate": "Fällig am" }
```

```handlebars
<h1>{{localize "invoice"}} {{invoice.number}}</h1>
<p>{{localize "dueDate"}}: {{invoice.dueDate}}</p>
```

A request with `"locale": "de-CH"` prints `Rechnung` and `Fällig am`; one with `"locale": "en-GB"`
reads `en-GB.json` instead.

## Add translation files

1. In Studio's explorer, open the menu of the template's folder and choose
   **New entity → Localization**. Name the file for its language tag, such as `de-CH.json` or
   `en-GB.json`. It can also go in a `localizations` folder inside the template's folder.
2. Write the labels as one JSON object, with the same keys in every file.
3. Print a label with `{{localize "key"}}`, or read it from `localization` in the data, such as
   `{{localization.invoice}}`.
4. Pick the language in the **Preview** box of the preview toolbar. The box appears once the
   template has a translation file.
5. Publish the template. Production renders use the files from the published version on.

What to know about labels:

- `localize` looks up top-level keys. A key the file does not have prints the key itself.
- `localize` also works inside `helpers.js` functions.
- The chosen file is added to the data as `localization`, unless your data already has a
  `localization` property; then yours wins.
- When a translation file applies, the render data must be a JSON object.

## Choose the language

The template's own language is the `locale` in its `page.json`, shown in Studio as **Language**
under **PDF properties** in the preview toolbar. A render uses it unless something picks another:

- **Reports API:** send `locale` with the request. Without it, the language is `en-US`.

  ```json
  {
    "format": "pdf",
    "template": { "name": "Invoice" },
    "data": { "invoice": { "number": "INV-2041" } },
    "locale": "de-CH"
  }
  ```

  See [Render a report by name](/guides/reports/) for runnable code in each client.

- **Renders API:** send `locale` with a template version render. Without it, the render uses the
  `page.json` locale. A script can still change it, as below.
- **A script:** set `req.options.localization.language` in a `beforeRender` script, for example
  from your data:

  ```js title="scripts/language.js"
  function beforeRender(req, res) {
    req.options.localization.language = req.data.customer.language ?? "en-GB";
  }
  ```

  A script's choice wins over the request's `locale`. See
  [Handlebars templates](/templates/handlebars/) for how scripts run.

A `locale` or script language must be a language tag such as `en` or `de-CH`; anything else
fails with `400 BAD_REQUEST`. The render's language also becomes the PDF's document language.

### Which file a render reads

The render reads the first file that exists:

1. The file for the render's language.
2. The file for the `locale` in `page.json`.
3. `en-GB.json`.

File names must match the whole language tag, ignoring case. A `de` request does not find
`de-CH.json`, and `de-CH` does not fall back to `de.json`. So a Reports API request without
`locale` reads `en-US.json` if the template has one, and otherwise the `page.json` language's
file.

## Format numbers and amounts

In an HTML template, write a helper in the template's **helpers.js** tab.
`Number.prototype.toLocaleString()` does not group digits and there is no `Intl` object, so build
the text yourself. Keeping the separators in the translation files lets one helper serve every
language:

```json title="de-CH.json"
{ "groupSeparator": "’", "decimalSeparator": "." }
```

```js title="helpers.js"
function formatMoney(amount, currency) {
  const [whole, cents] = Number(amount).toFixed(2).split(".");
  const grouped = whole.replace(/\B(?=(\d{3})+(?!\d))/g, localize("groupSeparator"));

  return `${currency} ${grouped}${localize("decimalSeparator")}${cents}`;
}
```

```handlebars
<td>{{formatMoney total "CHF"}}</td>
```

With `de-CH` and a total of `1234567.5`, this prints `CHF 1’234’567.50`.

## Format dates

Helpers and scripts have two ways to print dates: `require("moment")` and the `toLocale…`
methods of `Date`.

### Moment

`require("moment")` returns a built-in subset of [Moment](https://momentjs.com/docs/#/displaying/).
Keep the pattern and Moment's language in the translation files too:

```json title="de-CH.json"
{ "language": "de-CH", "dateFormat": "D. MMMM YYYY" }
```

```js title="helpers.js"
const moment = require("moment");

function formatDate(value) {
  return moment(value)
    .locale(String(localize("language")))
    .format(String(localize("dateFormat")));
}
```

`{{formatDate invoice.dueDate}}` prints `30. November 2026` in `de-CH` and, with
`"dateFormat": "D MMMM YYYY"` in `en-GB.json`, `30 November 2026` in `en-GB`.

| Supported                               | Details                                                                                      |
| --------------------------------------- | -------------------------------------------------------------------------------------------- |
| `moment()`, `moment(value)`             | Now, or whatever `new Date(value)` accepts, such as ISO 8601 strings and epoch milliseconds. |
| `.format(pattern)`                      | The tokens below. Text in `[brackets]` is literal. Without a pattern, ISO 8601 with offset.  |
| `.locale(name)`, `.lang(name)`          | Month and weekday names. `moment.locale(name)` sets the default.                             |
| `.isSame(other, "day")`                 | Same calendar day. Without `"day"`, the same instant.                                        |
| `.diff(other)`                          | Difference in milliseconds only.                                                             |
| `moment.duration(ms)`                   | `.days()`, `.hours()`, `.minutes()`, `.seconds()`, `.milliseconds()`.                        |
| `.toDate()`, `.valueOf()`, `.isValid()` | As in Moment.                                                                                |

Format tokens: `YYYYYY`, `YYYYY`, `YYYY`, `YY`, `MMMM`, `MMM`, `MM`, `M`, `Do`, `DD`, `D`,
`dddd`, `ddd`, `dd`, `HH`, `H`, `hh`, `h`, `mm`, `m`, `ss`, `s`, `SSS`, `A`, `a`, `ZZ` and `Z`.

- An unsupported token, or a unit other than milliseconds for `.diff` and `moment.duration`,
  fails the render with an error naming it, instead of printing something wrong.
- `moment(text, format)` ignores the format argument.
- In languages such as Polish and Russian, a month name after a day number takes its declined
  form, as in Moment.

### Date methods

`toLocaleDateString`, `toLocaleTimeString` and `toLocaleString` take a language and the usual
`weekday`, `year`, `month`, `day`, `hour`, `minute`, `second` and `hour12` options:

```js title="helpers.js"
function longDate(value) {
  return new Date(value).toLocaleDateString("de-CH", {
    day: "numeric",
    month: "long",
    year: "numeric",
  });
}
```

### Date languages

Month and weekday names, and the date layouts of the `toLocale…` methods, exist for `en`,
`en-GB`, `sv`, `nb`, `da`, `fi`, `et`, `de`, `fr`, `es`, `it`, `nl`, `pl`, `pt`, `cs`, `lt`,
`lv`, `ru` and `uk`. A regional tag such as `de-AT` uses its language's names, and other
languages fall back to English.

## Time zones

Helpers and scripts show dates in the server's time zone, and the `timeZone` option of the
`toLocale…` methods is ignored. Convert times to the reader's zone before you send them: a
date-time without an offset, such as `2026-11-30T09:00:00`, prints as written.

## Component and spreadsheet templates

- **[Component templates](/templates/components/)** format numbers, currency, percentages and
  dates with a `format` on a value binding, including a `timeZone` for dates, without any code.
  Without a `locale` in the format, the render's language is used. Translation files work there
  too.
- **[Spreadsheet templates](/guides/spreadsheets/)** built from sheets and columns take a label
  per language for a `title` or `header`:

  ```json
  {
    "header": { "default": "Amount", "de": "Betrag", "lt-LT": "Suma" },
    "value": "sum",
    "format": "decimal"
  }
  ```

  The render's language picks the label: an exact match first, then the language without its
  region (`de-CH` finds `de`), then `default`. `default` is required. Up to 20 entries, each
  label up to 200 characters.

- Workbook templates designed in Excel use helpers, `localize` and translation files in their
  cells like HTML templates.

---

# Use with AI assistants

Source: https://docs.typefold.dev/clients/ai-assistants/

Typefold has an [MCP](https://modelcontextprotocol.io/) server, so AI assistants can list your
workspace's templates and render PDFs from them. Ask, for example, "render the Invoice template
for order 2041 as a test" and the assistant sends the data and hands you a download link.

To have a coding agent write code that calls the API instead, use the
[Agent Skill](/start/ai-agents/).

## Before you start

- **The server's address:** the address you open Studio at, followed by `/mcp`, such as
  `https://pdf.example.com/mcp`. On the hosted service it is `https://app.typefold.dev/mcp`.
- **An [API key](/clients/http/#api-keys)** with `template:read`, `render:create` and
  `render:read`. The assistant sees only that key's workspace. Give it a key of its own, so you
  can revoke it without affecting your applications.

The assistant sends the key in an `Authorization: Bearer` header. Examples below read it from the
`TYPEFOLD_API_KEY` environment variable.

## Connect your assistant

### Claude Code

```sh
claude mcp add --transport http typefold https://pdf.example.com/mcp \
  --header "Authorization: Bearer $TYPEFOLD_API_KEY"
```

See [Claude Code MCP](https://code.claude.com/docs/en/mcp) for where the server is saved.

### Claude Desktop

Claude Desktop's custom connectors cannot send an API key header.
Connect through [mcp-remote](https://www.npmjs.com/package/mcp-remote) instead: add this to
`claude_desktop_config.json` (**Settings → Developer → Edit Config**) and restart Claude.

```json
{
  "mcpServers": {
    "typefold": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://pdf.example.com/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": { "AUTH_HEADER": "Bearer paste-the-secret-here" }
    }
  }
}
```

### Cursor

Add the server to `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` for all projects,
and set `TYPEFOLD_API_KEY` in your shell profile. See [Cursor MCP](https://cursor.com/docs/context/mcp).

```json
{
  "mcpServers": {
    "typefold": {
      "url": "https://pdf.example.com/mcp",
      "headers": { "Authorization": "Bearer ${env:TYPEFOLD_API_KEY}" }
    }
  }
}
```

### n8n AI agent

1. Add an **MCP Client Tool** to your **AI Agent** node.
2. Set **Endpoint** to the server's address and **Server Transport** to **HTTP Streamable**.
3. Set **Authentication** to **Bearer Auth** and create a credential with the API key as its
   token.
4. Keep **Tools to Include** at **All**.

See [n8n's MCP Client Tool](https://docs.n8n.io/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.toolmcp/).

## Tools

| Tool                       | What it does                                                                                                               |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `list_templates`           | Lists the workspace's templates, their folders and formats, and whether each is published.                                 |
| `get_template_data_schema` | Returns the shape of the data a published template takes.                                                                  |
| `render_report`            | Renders a published template to PDF or an image, as the [Reports API](/guides/reports/) does, and returns a download link. |
| `start_render`             | Starts a background render of a published template, as the [Renders API](/guides/rendering/) does, for large files.        |
| `get_render_status`        | Returns a render's state, and once it succeeded, a download link.                                                          |

- Download links work for 5 minutes. Ask for the render's status to get a new one.
- `render_report` and `start_render` take `test: true` for a free
  [test render](/guides/rendering/#test-renders) with a "TEST" watermark. Ask for test renders
  while you try things out.
- Both also take a `locale` for the template's translations and a
  [`watermark`](/guides/rendering/#watermarks), such as "DRAFT" across every page.
- Both also take `format: "png"`, `"jpeg"` or `"webp"` for one page drawn as an
  [image](/guides/rendering/#render-an-image), such as a social preview, with `image` choosing
  the page and width.
- `start_render` also takes a `destination` to upload the file to one of your
  [storage destinations](/guides/storage-destinations/) by its name. With `keepCopy: false` the
  render has no download link.
- Real renders count against your plan's documents, as API renders do, and the same
  [limits](/clients/limits/) apply.
- The server doesn't render Excel files. For those, use the [Reports API](/guides/reports/).

## For other AI tools

These docs are also published for language models: [`/llms.txt`](/llms.txt) lists every page,
and [`/llms-full.txt`](/llms-full.txt) holds them all in one file. The API's OpenAPI document is
at [`/reference/api/openapi.json`](/reference/api/openapi.json).

---

# .NET client

Source: https://docs.typefold.dev/clients/dotnet/

`Typefold.Client` is the NuGet package for the Typefold API. It renders reports by name
through the [Reports API](/guides/reports/); HTML, template versions and batches through the
[Renders API](/guides/rendering/); and email and SMS text. It also reads render status, cancels
renders and downloads PDFs. The .NET, [Python](/clients/python/) and
[TypeScript](/clients/typescript/) clients have the same features. For templates, assets,
webhooks and administration, call the [HTTP API](/clients/http/).

## Before you start

- .NET Framework 4.6.2 or later, .NET Core 2.0 or later, or .NET 5 or later.
- An API key with the `render:create`, `render:read` and `template:read` scopes; see
  [API keys and scopes](/clients/http/#api-keys).
- A published template to render, such as one named `Invoice`. See
  [Build your first template](/guides/first-template/).

## 1. Install the package

```sh
dotnet add package Typefold.Client
```

On `net8.0` it has no dependencies; on `netstandard2.0` it uses `System.Text.Json` 8.0.6. The
package version matches the Typefold release it came with. Use a client no newer than your
server; see [versioning](/clients/http/#compatibility).

## 2. Create a client

```csharp
using Typefold.Client;

var client = new TypefoldClient(
    new Uri(Environment.GetEnvironmentVariable("PDF_URL")!),
    Environment.GetEnvironmentVariable("API_KEY")!);
```

`PDF_URL` is your installation's address, the URL you open Studio at, such as
`https://pdf.example.com`. Create one client per API key and reuse it; it is safe to share between
threads.

## 3. Render a report

`RenderReportAsync` renders the published version of a template, found by name, and returns the
file's bytes. It waits up to 95 seconds for a PDF:

```csharp
byte[] pdf = await client.RenderReportAsync(new RenderReportRequest
{
    Template = TemplateRef.ByName("Invoice"),
    Data = new { number = "2026-0042", customer = new { name = "Ada Lovelace" } },
});

await File.WriteAllBytesAsync("invoice.pdf", pdf);
```

Open `invoice.pdf`: you should see the template filled with your data, so `{{customer.name}}`
prints `Ada Lovelace`.

For an Excel file from a spreadsheet template, set `Format = ReportFormat.Xlsx`. To change the
paper, margins or PDF standard for one render, set `Pdf`.

## Use dependency injection

Register the client as a typed `HttpClient`, so it shares pooled connections:

```csharp
builder.Services
    .AddHttpClient<TypefoldClient>((http, services) =>
    {
        var config = services.GetRequiredService<IConfiguration>();

        return new TypefoldClient(
            new Uri(config["Typefold:BaseUrl"]!),
            config["Typefold:ApiKey"]!,
            http);
    })
    .ConfigureHttpClient(http => http.Timeout = TimeSpan.FromSeconds(120));
```

Then inject `TypefoldClient` where you need it. Keep the API key in user secrets or environment
variables, not in `appsettings.json`.

## Render HTML or a template version

`RenderAsync` renders HTML you send, or a published template version, through the
[Renders API](/guides/rendering/). It creates the render, waits for it and downloads the PDF.

```csharp
byte[] pdf = await client.RenderAsync(new DirectRenderRequest
{
    Document = new HtmlDocument
    {
        Html = "<h1>Invoice 42</h1><p>Total: 1,250.00 EUR</p>",
        Css = new[] { "h1 { color: #0b5394; }" },
    },
    Settings = new RenderSettings { PageSize = PageSize.Letter },
});
```

To render a published template version, pass its ID and the data:

```csharp
byte[] ticket = await client.RenderAsync(new TemplateVersionRenderRequest
{
    TemplateVersionId = versionId,
    Data = new { ticket = new { number = "TK-1" } },
});
```

`RenderAsync` waits two minutes by default; pass `timeout: TimeSpan.FromMinutes(5)` to wait five.
Without `Settings`, the page is A4 with 10 mm margins.

## Render in the background

For long or numerous renders, create the render, store its ID, and pick up the PDF later:

```csharp
// 1. Create. Returns as soon as the render is queued.
Render render = await client.CreateRenderAsync(request);
await SaveRenderIdAsync(orderId, render.Id);

// 2. Later, in a job or after a webhook arrives:
render = await client.GetRenderAsync(renderId);

if (render.State == RenderState.Succeeded)
{
    byte[] pdf = await client.DownloadAsync(render);
}
```

To wait in the same process instead, call `WaitForRenderAsync(render)`, which polls until the
render finishes. To be called when it finishes, use [webhooks](/guides/webhooks/). If you no
longer need a render, call `CancelRenderAsync(render.Id)`.

## Render a batch

`CreateBatchAsync` creates up to 100 renders in one request; if any item is invalid, none is
created. `WaitForBatchAsync` waits until every item has finished, and `DownloadBatchAsync`
returns one PDF of every item in order:

```csharp
RenderBatch batch = await client.CreateBatchAsync(
    tickets.Select(ticket => new TemplateVersionRenderRequest
    {
        TemplateVersionId = versionId,
        Data = ticket,
    }),
    idempotencyKey: "tickets-2026-10-12");

batch = await client.WaitForBatchAsync(batch);

if (batch.Counts.Succeeded == batch.Total)
{
    byte[] pdf = await client.DownloadBatchAsync(batch.Id);
}
```

A failed item does not stop the others. `batch.Items` gives each item's render `Id` and `State`,
to download or cancel it as a single render. See
[Render many documents at once](/guides/batch-rendering/).

## Retry safely

`RenderReportAsync`, `CreateRenderAsync`, `RenderAsync` and `CreateBatchAsync` take an optional
`idempotencyKey`. Retrying with the same key returns what the first call created instead of
rendering again, so a network failure never produces a duplicate document:

```csharp
var key = $"invoice-{invoice.Id}-v{invoice.Revision}";

byte[] pdf = await client.RenderReportAsync(request, idempotencyKey: key);
```

Use a key that names the document. For reports, keys apply to PDF only. The rules are in
[idempotency keys](/guides/rendering/#idempotency-keys).

## Handle errors

The client retries `429 RATE_LIMITED` for you, up to `MaxRateLimitRetries` times. Any other API
error, or a `429` still refused after those retries, throws `TypefoldException`; its
`Error.Code` says what went wrong and `Error.Retryable` whether trying again can help:

```csharp
try
{
    byte[] pdf = await client.RenderReportAsync(request, idempotencyKey: key);
}
catch (TypefoldException ex) when (ex.Error.Code == "RENDER_TIMEOUT")
{
    // Still rendering after 95 seconds. Follow it later with GetRenderAsync(ex.Error.RenderId).
    await QueueFollowUpAsync(ex.Error.RenderId!);
}
catch (TypefoldException ex) when (ex.Error.Retryable)
{
    // RATE_LIMITED, a 5xx, and similar: back off and retry with the same idempotency key.
}
catch (TypefoldException ex)
{
    // Not worth retrying as is: fix the request, template or key.
    logger.LogError(ex, "PDF render failed: {Code}", ex.Error.Code);
}
```

Every code is in the [error reference](/clients/http/#errors).

## Render email and SMS text

`RenderStringAsync` fills a template string and returns the text, with no PDF. See
[Render email and SMS text](/guides/string-rendering/).

```csharp
string body = await client.RenderStringAsync(new RenderStringRequest
{
    Template = "{{#if (isEqual Status 'paid')}}Paid{{else}}Due{{/if}}: {{Booking.Code}}",
    Data = model,
    Engine = StringEngine.Handlebars,
    Helpers = "function isEqual(a, b) { return a === b; }",
    Format = StringFormat.Html,
});
```

`StringFormat.Html` escapes values and `StringFormat.Text` (the default) does not. Without
`Engine`, only `{{path}}` placeholders are filled.

## Reference

Everything is in the `Typefold.Client` namespace.

### Client options

`new TypefoldClient(baseUrl, apiKey, httpClient)`:

| Option                | Default                  | Meaning                                                                                                                      |
| --------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `baseUrl`             | Required                 | The API's address as a `Uri`, such as `https://pdf.example.com`. A base path such as `/pdf` is kept.                         |
| `apiKey`              | Required                 | Your API key.                                                                                                                |
| `httpClient`          | One with a 120 s timeout | A shared `HttpClient`. A report PDF can take up to 95 seconds, so keep its timeout above that.                               |
| `MaxRateLimitRetries` | `3`                      | How many times a `429` is sent again, after its `Retry-After` (else 1, 2, 4… seconds, at most 30). `0` throws the first one. |

`MaxRateLimitRetries` is a property: `new TypefoldClient(baseUrl, apiKey) { MaxRateLimitRetries = 5 }`.

### Methods

Every method also takes a `CancellationToken`.

| Method                                          | Returns                        | Scopes                                                       |
| ----------------------------------------------- | ------------------------------ | ------------------------------------------------------------ |
| `RenderReportAsync(request, idempotencyKey)`    | `byte[]`                       | `render:create`, `template:read`, plus `render:read` for PDF |
| `RenderStringAsync(request)`                    | `string`                       | `render:create`                                              |
| `ListReportsAsync()`                            | `IReadOnlyList<ReportSummary>` | `template:read`                                              |
| `GetReportDataSchemaAsync(format, template)`    | `JsonElement` (JSON Schema)    | `template:read`                                              |
| `CreateRenderAsync(request, idempotencyKey)`    | `Render`                       | `render:create`                                              |
| `GetRenderAsync(id)`                            | `Render`                       | `render:read`                                                |
| `WaitForRenderAsync(render, timeout)`           | `Render`                       | `render:read`                                                |
| `DownloadAsync(render)`                         | `byte[]`                       | `render:read`, only when it refreshes the link               |
| `RenderAsync(request, idempotencyKey, timeout)` | `byte[]`                       | `render:create`, `render:read`                               |
| `CancelRenderAsync(id)`                         | Nothing                        | `render:cancel`                                              |
| `CreateBatchAsync(items, idempotencyKey)`       | `RenderBatch`                  | `render:create`                                              |
| `GetBatchAsync(id)`                             | `RenderBatch`                  | `render:read`                                                |
| `WaitForBatchAsync(batch, timeout)`             | `RenderBatch`                  | `render:read`                                                |
| `DownloadBatchAsync(id)`                        | `byte[]`                       | `render:read`                                                |

`WaitForRenderAsync` polls every 1 to 5 seconds and throws `RENDER_TIMEOUT` after `timeout`, two
minutes by default; a dropped connection or a retryable error such as `RATE_LIMITED` does not
stop it. `WaitForBatchAsync` polls the same way, for up to 10 minutes by default. `DownloadAsync`
re-reads the render first when its download link is about to expire, and throws
`InvalidOperationException` for a render that has no file. Cancelling a `CancellationToken` stops
your code waiting, not the render on the server; call `CancelRenderAsync` for that.

### Request types

Requests are classes with the API's fields in PascalCase.

| Type                           | Properties                                                                                                                                                                               |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RenderReportRequest`          | `Template`, `Data`, `Format` (`pdf`), `Locale` (`en-US`), `Pdf`, `Image`, `Test`                                                                                                         |
| `ReportPdfOptions`             | `PageSize`, `Orientation`, `Margins`, `PageRanges`, `Metadata`, `Pdfa`, `Pdfua`, `OpaqueFills`, `PreferCssPageSize`, `Attachments`, `Encryption`, `Signature`, `Operations`, `Watermark` |
| `TemplateVersionRenderRequest` | `TemplateVersionId`, `Data`, `Locale`, `Metadata`, `Attachments`, `Encryption`, `Signature`, `Watermark`, `Format`, `Image`, `Test`, `WaitMs`                                            |
| `DirectRenderRequest`          | `Document` (`Html`, `Css`, `AssetIds`), `Settings`, `Metadata`, `Attachments`, `Encryption`, `Signature`, `Watermark`, `Format`, `Image`, `Test`, `WaitMs`                               |
| `RenderSettings`               | `PageSize` (A4), `Orientation`, `Margins` (10 mm each, all four required), `Locale`, `PageRanges`, `Metadata`, `Pdfa`, `Pdfua`, `OpaqueFills`, `PreferCssPageSize`                       |
| `Margins`                      | `TopMm`, `RightMm`, `BottomMm`, `LeftMm`                                                                                                                                                 |
| `RenderStringRequest`          | `Template`, `Data`, `Format`, `Engine`, `Helpers`                                                                                                                                        |
| `PdfMetadata`                  | `Title`, `Author`, `Subject`, `Creator`, `Keywords`, `Producer`, `Language`, `Xmp`                                                                                                       |
| `PdfEncryption`                | `OpenPassword`, `OwnerPassword`, `Permissions` (`PdfPermissions`, with `Printing` from `PdfPrinting`)                                                                                    |
| `PdfSignature`                 | `Certificate`, `Reason`, `Location`, `ContactInfo`, `Field` (`PdfSignatureField`)                                                                                                        |
| `PdfAttachment`                | `Name`, `MimeType`, `Description`, `Relationship`, `Content` (text) or `ContentBase64` (bytes)                                                                                           |
| `PdfOperation`                 | `Type` (`PdfOperationType`), `Template` or `Pdf`, `MergeWholeDocument`, `MergeToFront`, `RenderForEveryPage`                                                                             |
| `PdfWatermark`                 | `Text`, `Opacity`, `Rotation`, `FontSize`, `Color`; see [watermarks](/guides/rendering/#watermarks)                                                                                      |
| `ImageOptions`                 | `Page`, `Width`, `Quality`, with `Format` set to `RenderFormat.Png`, `Jpeg` or `Webp`; see [images](/guides/rendering/#render-an-image)                                                  |

`TemplateRef.ByName`, `ById` and `ByShortid` pick the template; a shortid exists only on
[imported](/guides/jsreport-import/) templates. `PageSize` has `A3`, `A4`, `A5`, `Letter` and
`Legal`, or use `new PageSize(widthMm, heightMm)`. What each field does is in
the [API reference](/reference/api/) and
[PDF standards and security](/guides/pdf-standards/).

### How data is sent

`Data` is sent with its property names unchanged, so `new { CustomerName = "Ada" }` is
`{{CustomerName}}` in the template, and null values are kept. Anonymous types, records, classes,
dictionaries, `JsonElement` and `JsonNode` all work. A Newtonsoft `JObject` works only as the
whole `Data` value; convert a nested one first, for example with
`JsonNode.Parse(jObject.ToString())`. A template version or string render without `Data` sends
`{}`.

### Exceptions

`TypefoldException` has `StatusCode` (`null` when the error did not come from an HTTP response,
such as a failed render or a wait that ran out) and `Error`, the API's error with `Code`,
`Message`, `Retryable`, `Details`, `Diagnostics` and `RenderId`. The client raises these codes
itself:

| Code             | When                                                                                                                          |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `RENDER_TIMEOUT` | A wait ran out of time. Retryable; follow `RenderId`, or the batch for `WaitForBatchAsync`.                                   |
| `RENDER_FAILED`  | A render was cancelled while `RenderAsync` waited. A failed render throws with the error it recorded instead.                 |
| `HTTP_ERROR`     | A response that was not the API's error format, such as a proxy's error page or a failed download. Retryable for 429 and 5xx. |

---

# HTTP API

Source: https://docs.typefold.dev/clients/http/

Any language that can send JSON over HTTPS can render with typefold. The [.NET](/clients/dotnet/),
[Python](/clients/python/) and [TypeScript](/clients/typescript/) clients wrap the same API. Every
endpoint, the scope it needs and its request and response fields are in the
[API reference](/reference/api/).

```sh
export PDF_URL='https://pdf.example.com'
export API_KEY='paste-the-secret-here'

curl "$PDF_URL/v1/renders?limit=1" -H "x-api-key: $API_KEY"
```

A working key with `render:read` answers `{ "items": [...] }`. To render, follow the
[quickstart](/start/quickstart/), [Render a report by name](/guides/reports/) or
[Render with the Renders API](/guides/rendering/).

## Base URL

The API answers at the address you open Studio at, such as `https://pdf.example.com`, and every
endpoint is under `/v1`. On a self-hosted installation the address is `PUBLIC_URL` in `.env`.

## Authentication

Send an API key in the `x-api-key` header of every request. A key belongs to one workspace and
only sees what is in it.

| Situation                                                 | Result                                                    |
| --------------------------------------------------------- | --------------------------------------------------------- |
| No `x-api-key` header, or a wrong, revoked or expired key | `401 UNAUTHORIZED`                                        |
| The key lacks the scope the endpoint needs                | `403 FORBIDDEN`, with a message naming the refused action |
| An ID that belongs to another workspace                   | `404 NOT_FOUND`, as if it did not exist                   |

A few endpoints, such as creating API keys, are only for people signed in to Studio and refuse
any API key. These need no credential: `GET /v1/instance`, the upload and download links under
`/v1/storage/`, and the [health checks](/self-hosting/monitoring/#health-checks).

:::caution
Keep API keys on your servers. Never put one in browser or mobile app code: anyone who has the
key can use it. The API sends no CORS headers, so browsers cannot call it from other sites.
:::

## API keys

Workspace owners and admins manage keys in Studio under **Manage → API keys**. Members do not see
that page.

To create a key, select **Create API key**, then:

1. Enter a **Key name** of up to 64 characters.
2. Tick the [scopes](#scopes) the application needs under **Permissions**.
3. Pick when it **Expires**: **Never**, **30 days**, **90 days** or **365 days**.
4. Select **Create API key** and copy the secret. It is shown only once.

Select keys in the list to change them:

| Action     | Effect                                                                                                                                                                                      |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Rotate** | Replaces one key with a new secret that has the same name, scopes and lifetime, counted from now. The old secret keeps working for 15 minutes, or until its own expiry if that comes first. |
| **Revoke** | Stops the key. It stays in the list as **Revoked**.                                                                                                                                         |
| **Delete** | Removes the key. Its audit history stays.                                                                                                                                                   |

A revoked or deleted key stops working within about a second. To rotate without downtime, rotate
the key, put the new secret in your application, and restart it within the 15 minutes.

The same actions are the `/v1/api-keys` endpoints in the [API reference](/reference/api/), where
`expiresInDays` takes any whole number from 1 to 365. Creating, rotating, revoking and deleting
keys needs a Studio sign-in. An API key with `admin:manage` can only list keys, never their secrets.

### Deploy key

On a self-hosted installation, the [deploy key](/self-hosting/users/#the-deploy-key) set by
`DEPLOY_API_KEY` in `.env` has `template:read`, `template:write`, `template:publish` and
`asset:manage`, and never expires. Studio marks it **Set by server**. You can revoke it, but
rotating or deleting it answers `409 CONFLICT`.

## Scopes

Give each key only the scopes its application needs.

| Scope                | Allows                                                                                                                                                          |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `render:create`      | Create renders, batches and string renders, render reports, and preview template drafts.                                                                        |
| `render:read`        | List and read renders and batches, get download links, read render limits, and receive a PDF from the Reports API.                                              |
| `render:cancel`      | Cancel a queued or processing render.                                                                                                                           |
| `template:read`      | Read templates, drafts, revisions and versions; list reports and read their data schemas; read and export workspace folders and files; inspect report archives. |
| `template:write`     | Create, edit and delete templates and save drafts; create and change workspace folders and files; import report archives and workspace exports.                 |
| `template:publish`   | Publish a draft as a new version.                                                                                                                               |
| `template:content`   | Save the values of a template's [content fields](/templates/content-fields/), and upload images for them.                                                       |
| `asset:manage`       | [Upload](#upload-fonts-images-and-workbooks), list, read and delete fonts, images, stylesheets and XLSX workbooks, and use them as workspace files.             |
| `audit:read`         | Read the workspace's audit history.                                                                                                                             |
| `usage:read`         | Read daily render usage.                                                                                                                                        |
| `webhook:manage`     | Manage webhook endpoints and their signing secrets, and read their deliveries.                                                                                  |
| `certificate:manage` | Upload and delete signing certificates. Listing and reading them needs only `template:read`.                                                                    |
| `destination:manage` | Save, list, change and delete [storage destinations](/guides/storage-destinations/). Rendering to one needs only `render:create`.                               |
| `admin:manage`       | List the workspace's API keys.                                                                                                                                  |

Some operations need more than one:

| Operation                                               | Scopes                                                                                                             |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Render a template by name (Reports API)                 | `render:create` and `template:read`, plus `render:read` for a PDF                                                  |
| Preview a draft as a file                               | `render:create` and `template:read`, plus `render:read` for a PDF                                                  |
| Render a published version with `POST /v1/renders`      | `render:create`                                                                                                    |
| Render a draft with `POST /v1/renders` (`preview` body) | `render:create` and `template:read`                                                                                |
| Import a report archive, folder or workspace export     | `template:write`, plus `asset:manage` to bring its uploaded files, and `template:publish` to publish its templates |
| Export a folder or the workspace                        | `template:read`, plus `asset:manage` when it holds uploaded files                                                  |

Common sets:

| Key for                                     | Scopes                                                                                          |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| A backend that renders templates by name    | `render:create`, `render:read`, `template:read`                                                 |
| A backend that renders its own HTML         | `render:create`, `render:read`                                                                  |
| A release pipeline that publishes templates | `template:read`, `template:write`, `template:publish`, plus `asset:manage` for fonts and images |
| A monitoring job                            | `render:read`, `usage:read`                                                                     |

## Roles

People in a workspace have one role each. In Studio, owners and admins have every scope; members
have every scope except `admin:manage`, `webhook:manage`, `certificate:manage` and
`destination:manage`. Content
editors have `template:read`, `template:content`, `template:publish`, `render:create` and
`render:read`, and publish only content changes; see
[content fields](/templates/content-fields/#invite-a-content-editor).

| Action                                                          | Member | Admin | Owner |
| --------------------------------------------------------------- | :----: | :---: | :---: |
| Read, edit and publish templates and workspace files            |  Yes   |  Yes  |  Yes  |
| Create, read and cancel renders                                 |  Yes   |  Yes  |  Yes  |
| Upload and delete assets                                        |  Yes   |  Yes  |  Yes  |
| Read render limits, usage and the audit log                     |  Yes   |  Yes  |  Yes  |
| Create, rotate, revoke and delete API keys                      |   No   |  Yes  |  Yes  |
| Manage webhooks                                                 |   No   |  Yes  |  Yes  |
| Upload and delete signing certificates                          |   No   |  Yes  |  Yes  |
| Manage storage destinations                                     |   No   |  Yes  |  Yes  |
| Invite people, cancel invitations, change roles, remove members |   No   |  Yes  |  Yes  |
| Make someone an owner, or change or remove an owner             |   No   |  No   |  Yes  |

Members do not see **API keys**, **Webhooks** and **Storage destinations** in the **Manage** menu. They see **Signing
certificates** but cannot upload or delete them. A workspace always keeps at least one owner. To
invite people, see [invite someone](/self-hosting/users/#invite-someone).

## Requests and responses

- **Bodies are JSON.** Send `content-type: application/json`.
- **Unknown fields are refused.** A misspelled or unsupported field in a body or query string
  answers `400 BAD_REQUEST` instead of being ignored.
- **Body sizes** are limited per endpoint, 1 MiB for most; see [limits](/clients/limits/).
- **IDs** are opaque strings of up to 128 characters.
- **Timestamps** are ISO 8601 in UTC, such as `2026-10-08T07:41:05.112Z`.
- **Creates** answer `201 Created` with the new resource. `POST /v1/renders` answers `200` when
  the render ended within `waitMs` and `202` otherwise; a batch answers `202`.
- **Deletes** answer `200 OK` with `"deleted": true` and the deleted IDs.
- **Download and upload links** last five minutes. Read the render or asset again for a fresh one.

## Pagination

Lists that can grow large take a cursor:

| Parameter | Default | Description                             |
| --------- | ------- | --------------------------------------- |
| `limit`   | 25      | Items per page, 1 to 100                |
| `cursor`  | none    | The `nextCursor` from the previous page |

The response is `{ "items": [...], "nextCursor": "..." }`. While `nextCursor` is present, send it
back as `cursor` with the same filters for the next page. When it is absent, you have the last
page.

```sh
curl "$PDF_URL/v1/renders?limit=100&cursor=$NEXT_CURSOR" -H "x-api-key: $API_KEY"
```

- **Paged:** renders, templates and their revisions and versions, assets, audit events, workspace
  folders and files, template resources, and webhook deliveries. Renders, assets, audit events
  and deliveries come newest first; revisions and versions take `?order=asc` or `desc`.
- **Not paged** (every item at once): reports, API keys, webhook endpoints, signing certificates,
  storage destinations, workspace references and a file's usages.

## Retries and idempotency

- **You got an error response:** retry only when `retryable` is `true`, after the `Retry-After`
  header's seconds when it is sent.
- **You got no response** (a timeout or dropped connection): you can always retry a `GET`. Retry
  a render `POST` only when it carries an `Idempotency-Key` header.

An `Idempotency-Key` header makes `POST /v1/renders`, `POST /v1/renders/batch` and
`POST /v1/reports/render` safe to send twice: the repeat returns what the first request created
instead of rendering again. Use a value that names the document, such as `invoice-2026-0042`, and
send the same value on every retry. How long a key is remembered, and what counts as the same
request, are in [Render with the Renders API](/guides/rendering/).

## Rate limits

`429 RATE_LIMITED` means you sent too many requests in a minute, or your workspace reached its
render allowances. It is always retryable: wait the seconds in `Retry-After`, or a few seconds
with backoff when there is none. The numbers are in [limits](/clients/limits/).

## Upload fonts, images and workbooks

Upload a file once, then use its ID in a direct document's `assetIds` (see
[Render with the Renders API](/guides/rendering/)) or add it as a
[workspace file](/templates/overview/). The .NET, Python and TypeScript clients do not upload
files, so use HTTP. It needs the `asset:manage` scope.

1. Register the file with its size in bytes and its lowercase hex SHA-256:

   ```sh
   SIZE=$(wc -c < logo.png)
   SHA=$(sha256sum logo.png | cut -d' ' -f1)   # on macOS: shasum -a 256 logo.png

   curl "$PDF_URL/v1/assets" \
     -H "x-api-key: $API_KEY" \
     -H "content-type: application/json" \
     -d "{\"kind\": \"image\", \"filename\": \"logo.png\", \"mediaType\": \"image/png\", \"size\": $SIZE, \"sha256\": \"$SHA\"}"
   ```

   The response has the asset's `id`, an `uploadUrl` and the `uploadHeaders` to send.

2. Within five minutes, `PUT` the file to `uploadUrl` with every header in `uploadHeaders`:

   ```sh
   # Repeat -H for each entry in uploadHeaders.
   curl -X PUT "$UPLOAD_URL" -H "<header name>: <header value>" --data-binary @logo.png
   ```

| `kind`       | `mediaType`                                                                |
| ------------ | -------------------------------------------------------------------------- |
| `image`      | `image/png`, `image/jpeg`                                                  |
| `svg`        | `image/svg+xml`                                                            |
| `font`       | `font/woff2`, `font/ttf`, `font/otf`                                       |
| `stylesheet` | `text/css`                                                                 |
| `workbook`   | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` (XLSX) |

A file can be up to 50,000,000 bytes. An upload that does not match the registered size and
checksum is refused, and a file whose contents are not its `mediaType` answers `ASSET_INVALID`
when a render uses it.

## Compatibility

Changes within `/v1` only add things: new endpoints, and new optional request or response fields.
To keep working across releases:

- Ignore response fields you do not know.
- Handle unknown enum values and error codes, falling back on the HTTP status.
- Send only fields the server knows. A self-hosted server older than your client answers `400` to
  a field it does not know and `404` to an endpoint it does not have.

## Errors

Every failed request answers with the same shape:

```json
{
  "error": {
    "code": "ASSET_INVALID",
    "message": "Missing workspace files: shared/logo.png (referenced by template.html).",
    "retryable": false,
    "details": [
      {
        "path": "shared/logo.png",
        "message": "Referenced by template.html but not found in the workspace."
      }
    ]
  }
}
```

| Field       | Description                                                                        |
| ----------- | ---------------------------------------------------------------------------------- |
| `code`      | One of the codes below. Branch on this, never on `message`.                        |
| `message`   | Readable text that says what went wrong.                                           |
| `retryable` | `true` when the same request may succeed later without changes.                    |
| `details`   | Optional. Each specific problem, as `{ path?, message }`.                          |
| `renderId`  | Optional. On `RENDER_FAILED` and `RENDER_TIMEOUT`, the render the request created. |

| Code                  | Status     | Retry?    | What to do                                                                                                                                                                                                                                                                               |
| --------------------- | ---------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BAD_REQUEST`         | 400 or 415 | No        | Fix the request. Compare it with the [API reference](/reference/api/). `415` means the body was not sent as `application/json`. A template syntax error or a script without `beforeRender` also answers this.                                                                            |
| `UNAUTHORIZED`        | 401        | No        | Send a valid, active key in `x-api-key`. Check it under **Manage → API keys**.                                                                                                                                                                                                           |
| `FORBIDDEN`           | 403        | No        | Give the key the scope the message names, or do the action in Studio. An expired upload or download link also answers `403`, and so does a [suspended workspace](/clients/limits/#suspended-workspaces).                                                                                 |
| `NOT_FOUND`           | 404        | No        | Check the ID or name, and the key's workspace. The Reports API also answers this when no published template with that name renders the requested format. Deleted renders are gone after retention.                                                                                       |
| `CONFLICT`            | 409        | Sometimes | Read the current state and try again. See [conflicts](#conflicts).                                                                                                                                                                                                                       |
| `ASSET_INVALID`       | 400        | No        | Upload or fix each file named in `details`.                                                                                                                                                                                                                                              |
| `UNSUPPORTED_FEATURE` | 400        | No        | Change the template or request; see [what's not supported](/start/not-supported/).                                                                                                                                                                                                       |
| `LIMIT_EXCEEDED`      | 400 or 413 | No        | Make the input smaller or split the work. `413` is a body over its size limit. See [limits](/clients/limits/).                                                                                                                                                                           |
| `QUOTA_EXCEEDED`      | 402        | No        | The workspace used its documents for this month, its file storage, or its test renders for today. Send [test renders](/guides/rendering/#test-renders), delete unused files, wait for 00:00 UTC, or move to a bigger plan. See [limits](/clients/limits/#monthly-documents-and-storage). |
| `LICENSE_REQUIRED`    | 403        | No        | Self-hosted only: the installation has no valid license, so it cannot render; reading and editing still work. See [when rendering stops](/self-hosting/licensing/#when-rendering-stops).                                                                                                 |
| `RATE_LIMITED`        | 429        | Yes       | Wait, then retry. See [rate limits](#rate-limits).                                                                                                                                                                                                                                       |
| `RENDER_FAILED`       | 422        | No        | A request that waits for a PDF made a render that failed or was cancelled. Read `GET /v1/renders/{renderId}`; see [render failures](#render-failures).                                                                                                                                   |
| `RENDER_TIMEOUT`      | 504        | Yes       | The PDF was not ready in time, but the render carries on. Follow it with `GET /v1/renders/{renderId}`, or repeat the request with the same `Idempotency-Key` to wait again without a second render.                                                                                      |
| `INTERNAL`            | 500        | No        | Retry `GET` requests, and requests with an `Idempotency-Key`, a few times with backoff. If it keeps happening, check the [status page](https://status.typefold.dev) on the hosted service, or tell whoever runs the installation.                                                        |

### Conflicts

- **Someone changed it first.** You saved a draft or file with an `expectedRevision` that is no
  longer current. Read the latest, reapply your change and save again.
- **Idempotency key reused** with a different request. Use a new key for a new request.
- **Already exists.** A file or folder with that name is already there.
- **Render already ended.** You cancelled a render that had finished.
- **Folder not empty, or still in use.** `details` lists the files and what uses them.
- **Batch not finished.** You asked for a [combined batch PDF](/guides/batch-rendering/) while
  items are still rendering (`retryable: true`), or after one failed.

### Render failures

A render created with `POST /v1/renders` or in a batch can fail after the request returned. That
is not an HTTP error: the render's `state` becomes `failed`, with an
[error object](/guides/rendering/) whose `code` is one of:

- `ASSET_INVALID`: a font, image or other file could not be loaded.
- `UNSUPPORTED_FEATURE`: the document uses something the renderer does not support.
- `LIMIT_EXCEEDED`: the document is over a render limit, or the render ran past its time limit.
- `RENDER_FAILED`: anything else.

Each diagnostic names one problem:

| Diagnostic                   | What to do                                                                                                                                                                          |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `max_pages`                  | The PDF has too many pages. Shorten the document or split it.                                                                                                                       |
| `max_output_bytes`           | The PDF is too large. Use smaller images or split the document.                                                                                                                     |
| `max_input_bytes`            | The document, its fonts, images and attachments together are too large. Use smaller images or fonts.                                                                                |
| `render_memory_limit`        | The document is too complex. Split long tables or reduce images.                                                                                                                    |
| `render_process_exited`      | The render stopped, for example out of working memory (code `RENDER_FAILED`). Reduce the document's size or complexity.                                                             |
| `font_glyphs_missing`        | No font covers some characters. Add a font that has them.                                                                                                                           |
| `font_invalid`               | A font file is damaged. Replace it with a valid WOFF2, TTF or OTF.                                                                                                                  |
| `image_invalid`              | An image is damaged. Replace it with a valid PNG, JPEG or SVG.                                                                                                                      |
| `document_invalid`           | The content has an invalid value, or `pageRanges` selects none of the document's pages. Fix what the message names.                                                                 |
| `pdf_postprocess_failed`     | The PDF could not be given its producer, password, signature or pages from other templates. Check those settings.                                                                   |
| `pdfa_validation_failed`     | The PDF cannot meet the requested PDF/A or PDF/UA level. Fix each problem the message lists; see [PDF standards](/guides/pdf-standards/).                                           |
| `image_page_missing`         | The [image](/guides/rendering/#render-an-image) asks for a page the document doesn't have. Ask for one it has.                                                                      |
| `image_too_large`            | The [image](/guides/rendering/#render-an-image) would be taller than 8192 pixels. Ask for a smaller `width`.                                                                        |
| `watermark_text_unsupported` | The [watermark](/guides/rendering/#watermarks) text has characters its font cannot draw. Use Latin, Greek or Cyrillic letters.                                                      |
| `destination_upload_failed`  | The file could not be uploaded to the render's storage destination. Fix the cause the message names; see [storage destinations](/guides/storage-destinations/#if-the-upload-fails). |

Other diagnostics carry their own advice in `message`.

---

# Limits

Source: https://docs.typefold.dev/clients/limits/

Over a size or count limit, a request answers `LIMIT_EXCEEDED` (`400`, or `413` for a request
body) unless a row says otherwise. Every `429` is retryable. Error codes and retries are in the
[HTTP API](/clients/http/).

If you run your own installation, you can change the render allowances, the request rate per
address, the page, size, input, time and memory limits of a render, and how long renders are
kept; see [self-hosting limits](/self-hosting/limits/).

## Render allowances

Each workspace has two allowances, shared by every person and API key in it. Over either one, a
request answers `429 RATE_LIMITED` with a `Retry-After` header, and nothing is created.

| Allowance                                                     | Default | `Retry-After`                  |
| ------------------------------------------------------------- | ------- | ------------------------------ |
| `maxActiveRenders`: renders queued or processing at once      | 10      | 1 second                       |
| `rendersPerMinute`: renders created in any rolling 60 seconds | 60      | The time until a slot frees up |

See your workspace's values in Studio under **Manage → Render limits** (**Maximum outstanding
renders** and **Renders per minute**), or with `GET /v1/render-limits` (scope `render:read`).
Only a platform administrator can change them.

On the hosted service, each plan sets both:

| Plan     | `maxActiveRenders` | `rendersPerMinute` |
| -------- | ------------------ | ------------------ |
| Free     | 10                 | 60                 |
| Starter  | 30                 | 120                |
| Pro      | 50                 | 300                |
| Business | 100                | 1,000              |

| Request                                                                   | Counts                                            |
| ------------------------------------------------------------------------- | ------------------------------------------------- |
| `POST /v1/renders`: direct documents, published versions and previews     | One each                                          |
| `POST /v1/renders/batch`                                                  | One per item; the whole batch is admitted or none |
| Reports API PDF output, and template previews as PDF                      | One each                                          |
| Reports API XLSX output, and template previews as XLSX                    | Nothing, but refused while the workspace is full  |
| `POST /v1/renders/string`, and template previews as HTML                  | Nothing                                           |
| [Test renders](/guides/rendering/#test-renders) (`"test": true`)          | Nothing; they have their own allowance, below     |
| Polling, downloads, cancelling and template edits                         | Nothing                                           |
| A repeat with the same `Idempotency-Key`, and invalid or refused requests | Nothing                                           |

- A render counts once, whatever its page count.
- A finished render frees its `maxActiveRenders` slot at once, but counts toward
  `rendersPerMinute` for 60 seconds, even if it failed or was cancelled.
- A batch with more items than either allowance answers `400 LIMIT_EXCEEDED` instead of `429`.

### Monthly documents and storage

A workspace can also have a monthly document allowance and a storage allowance. On your own
installation both are unlimited unless a platform administrator sets them.

| Allowance                                                     | Counts                                                                        |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `documentsPerMonth`: real documents per calendar month (UTC)  | Each render that is not a test render, and each XLSX output, once it succeeds |
| `maxStorageBytes`: uploaded fonts, images, workbooks and PDFs | Every file not deleted, and once each, deleted files published versions use   |

- Renders still queued or processing count too, so the allowance can't be overrun. A render that
  fails or is cancelled doesn't count.
- Over either allowance, the request answers `402 QUOTA_EXCEEDED`, which is not retryable, and
  nothing is created. The document allowance starts again on the 1st of each month (UTC).
  Publishing again doesn't use more storage. Deleting a file frees its space once no published
  version uses it, and deleting a template frees the files only its published versions use.
- On a paid hosted plan, an owner or administrator can turn on overage under **Manage → Render
  limits**. Documents past the plan's are then rendered and billed per 1,000 with the plan's next
  invoice, until the month's overage reaches the spend cap set there; past the cap, requests
  answer `402 QUOTA_EXCEEDED`. Owners and administrators get an email at 80% and 100% of the
  plan's documents, and when the cap is reached.
- [Test renders](/guides/rendering/#test-renders) never count, so they keep working when the
  month's documents are used up.
- While a workspace has a monthly document allowance, every PDF preview, in Studio and through the
  API, is a test render with the watermark. Test renders then have the workspace's own render
  allowances instead of the test allowance below. XLSX previews have no watermark, so each counts
  as a document.
- See both allowances and how much of them is used in Studio under **Manage → Render limits**,
  or with `GET /v1/render-limits` (`documentsThisMonth` and `storageBytes`). An unlimited
  allowance reads `null`.
- [Templates from a PDF](/templates/overview/#from-a-pdf) have a monthly allowance too,
  `templateConversionsPerMonth`, with `templateConversionsThisMonth` beside it. One counts from
  the moment it starts, unless it fails before the AI answers or because the server restarted.
  Over the allowance, new ones are refused with `402 QUOTA_EXCEEDED` until the next month. On the
  Free plan they can also be refused earlier, when the service's AI capacity for Free workspaces
  is used up for the month.

### Test renders

[Test renders](/guides/rendering/#test-renders) are watermarked PDFs that count against none of
the allowances above. Each workspace has a separate allowance for them, counted and answered the
same way:

| Allowance                                      | Value                                       |
| ---------------------------------------------- | ------------------------------------------- |
| Test renders queued or processing at once      | 10, or your own `maxActiveRenders` if lower |
| Test renders created in any rolling 60 seconds | 10, or your own `rendersPerMinute` if lower |

- A workspace can also have a daily allowance of test renders, `testRendersPerDay`, counted per
  day (UTC) and including previews. Over it, test renders answer `402 QUOTA_EXCEEDED` until
  00:00 UTC. It is unlimited (`null`) unless a platform administrator sets it;
  `GET /v1/render-limits` shows it and `testRendersToday`.
- A batch's test items count against this allowance and its other items against the workspace's.
  A batch with more test items than this allowance answers `400 LIMIT_EXCEEDED`.
- Test renders still appear in usage, like any other render.

### Suspended workspaces

A platform administrator can suspend a workspace. While it is suspended, every render answers
`403 FORBIDDEN`, and so does every request with one of its API keys. Its members can still sign
in to Studio, read its templates and files, and export them. `GET /v1/render-limits` reads
`"suspended": true`.

## Request rates

| Limit                                                                       | Value                                        | Over it                                    |
| --------------------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------ |
| Requests to `/v1/` per client IP address (IPv6: per /64)                    | 1,200 per clock minute                       | `429`, `Retry-After` until the next minute |
| Requests to the [MCP server](/clients/ai-assistants/) per client IP address | 1,200 per clock minute                       | `429`, `Retry-After` until the next minute |
| Reports API renders and template previews waiting their turn                | 100 per workspace, each for up to 30 seconds | `429`, no `Retry-After`                    |
| Report archive imports, workspace imports and exports                       | 1 at a time per workspace                    | `429`, no `Retry-After`                    |
| Studio sign-in attempts per client address                                  | 10 a minute                                  | `429`                                      |

Reports API requests can be sent in parallel, up to the workspace's `maxActiveRenders`. Each
waits its turn while the workspace's earlier requests are prepared, which takes milliseconds for
a typical template.

Template renders, previews and Handlebars string renders can also answer `429 RATE_LIMITED`
without a `Retry-After` when the server is busy. Wait a few seconds and retry.

## Request bodies

A body over its endpoint's limit is refused with `413 LIMIT_EXCEEDED` before it is read.

| Endpoint                                                     | Largest body    |
| ------------------------------------------------------------ | --------------- |
| `POST /v1/renders`                                           | 11 MiB          |
| `POST /v1/renders/batch`                                     | 32 MiB          |
| `POST /v1/renders/string`                                    | 1,000,000 bytes |
| `POST /v1/reports/render`                                    | 10 MiB          |
| `POST /v1/templates/{id}/preview`                            | 30 MiB          |
| `POST /v1/reports/import`, `POST /v1/reports/import/inspect` | 30 MiB          |
| `POST /v1/workspace-folders/import`                          | 60 MiB          |
| Every other endpoint                                         | 1 MiB           |

Text in a JSON body may not contain NUL characters or unpaired surrogates; such a body answers
`400 BAD_REQUEST`.

## Renders

These apply to every PDF, from the Renders API and the Reports API alike. A render over one fails
with `LIMIT_EXCEEDED` unless the row says otherwise, and the render's error names the diagnostic
code.

| Limit                                                        | Value                  | Diagnostic code                                     |
| ------------------------------------------------------------ | ---------------------- | --------------------------------------------------- |
| Pages per PDF                                                | 200                    | `max_pages`                                         |
| PDF size                                                     | 50 MiB                 | `max_output_bytes`                                  |
| [Image](/guides/rendering/#render-an-image) width and height | 4096 × 8192 pixels     | `image_too_large` for the height                    |
| Input: document, CSS, fonts, images and attachments together | 10 MiB                 | `max_input_bytes`                                   |
| Memory to lay out the pages of one render                    | 512 MiB                | `render_memory_limit`                               |
| Other working memory of one render                           | 256 MiB                | `render_process_exited`, failing as `RENDER_FAILED` |
| Render time                                                  | 60 seconds             |                                                     |
| Reports API wait for a PDF                                   | 95 seconds             | See below                                           |
| Finished renders, their PDFs and webhook deliveries kept     | 30 days after creation |                                                     |

- After 95 seconds the Reports API answers `504 RENDER_TIMEOUT` with the render's ID, and the
  render keeps going. Set your HTTP client's timeout above 95 seconds.
- After 30 days, `GET /v1/renders/{id}` answers `404 NOT_FOUND`. Keep your own copy of PDFs you
  need.

Field limits of a render request, such as `html` length or page size, are in the
[API reference](/reference/api/).

### Batches

| Limit                                                        | Value                              | Over it                                                                         |
| ------------------------------------------------------------ | ---------------------------------- | ------------------------------------------------------------------------------- |
| Items per batch                                              | 1 to 100                           | `400 BAD_REQUEST`                                                               |
| Request body                                                 | 32 MiB                             | `413 LIMIT_EXCEEDED`                                                            |
| Input for all items together                                 | 64 MiB                             | `400 LIMIT_EXCEEDED`                                                            |
| Each item                                                    | The same limits as a single render | Checks on the request refuse the whole batch; render limits fail only that item |
| All item PDFs as one file (`GET /v1/renders/batch/{id}/pdf`) | 50 MiB together                    | `400 LIMIT_EXCEEDED`                                                            |

## Templates and workspace files

| Limit                                       | Value                                                            |
| ------------------------------------------- | ---------------------------------------------------------------- |
| Template name                               | 1 to 120 characters                                              |
| Template description                        | 2,000 characters                                                 |
| Templates deleted in one request            | 100                                                              |
| `template.html`                             | 2,000,000 characters                                             |
| **Page header**, **Page footer**            | 100,000 characters each                                          |
| `helpers.js`                                | 500,000 characters; with the translation labels it reads, 2 MB   |
| Stylesheets per template                    | 20, each up to 1,000,000 characters                              |
| Partials per template                       | 200, each up to 1,000,000 characters; names up to 255 characters |
| Scripts per template                        | 10, each up to 100,000 characters                                |
| Sample data sets and translation files      | 20 each per template; names up to 80 characters                  |
| Fonts, images and workbooks                 | 500 per template, 20 MiB together                                |
| Uploaded PDF file a template adds           | 5 MB                                                             |
| Workspace files one template references     | 100, nested at most 20 levels deep                               |
| Template source with every file it includes | 5 MB                                                             |
| Workspace file                              | 1,000,000 characters; name up to 120 characters                  |
| Workspace folder name                       | 80 characters                                                    |

### Helpers and scripts

These apply to `helpers.js`, Handlebars and `beforeRender` scripts when a template renders or is
previewed. The scripts together, the body, the header and the footer each run as one step. A step
over a limit fails with `LIMIT_EXCEEDED` unless the row says otherwise; later renders are not
affected.

| Limit                             | Value                                                   |
| --------------------------------- | ------------------------------------------------------- |
| CPU time                          | 2 seconds per step                                      |
| Memory                            | 64 MiB per step                                         |
| Source plus data sent into a step | 8,000,000 bytes                                         |
| HTML a step produces              | 5,000,000 bytes                                         |
| Data nesting                      | 100 levels (`400 BAD_REQUEST`)                          |
| Template complexity               | 50,000 Handlebars syntax nodes, nested at most 100 deep |
| Logged `console` calls            | The first 100 per run, each cut to 2,000 characters     |

### Components

| Limit                                                 | Value               | Checked   |
| ----------------------------------------------------- | ------------------- | --------- |
| Components in the composition, reusable ones included | 1,000               | On save   |
| Nesting depth in the composition                      | 50                  | On save   |
| Reusable components                                   | 100                 | On save   |
| Reusable component name                               | 1 to 200 characters | On save   |
| Columns per table                                     | 30                  | On save   |
| Path segments in a binding                            | 1 to 20             | On save   |
| Components after repeats and tables are expanded      | 10,000              | On render |
| Nesting depth after expansion                         | 100                 | On render |
| Items in one `repeat` or `table` source               | 500                 | On render |
| Expanded document                                     | 1 MB                | On render |

## Imports and exports

| Limit                                              | Value                                                |
| -------------------------------------------------- | ---------------------------------------------------- |
| Report archive                                     | 20 MB decoded (`400 BAD_REQUEST` over it)            |
| Entries in a report archive                        | 10,000                                               |
| Workspace or folder export to import               | 42 MB zip                                            |
| Project folder imported in Studio with **Import…** | 245 files, 10 MB in total, each text file up to 1 MB |
| Import `label`                                     | 200 characters                                       |

## Limits on other pages

| Feature                                                | Where                                                 |
| ------------------------------------------------------ | ----------------------------------------------------- |
| API key names and lifetime, upload size, link lifetime | [HTTP API](/clients/http/)                            |
| Direct document `html`, stylesheets and assets         | [Render with the Renders API](/guides/rendering/)     |
| String renders                                         | [String rendering](/guides/string-rendering/)         |
| Spreadsheet and workbook templates                     | [Spreadsheet templates](/guides/spreadsheets/)        |
| Steps that add or merge other templates                | [Combine templates](/features/combine-templates/)     |
| Passwords and signing certificates                     | [PDF standards and security](/guides/pdf-standards/)  |
| Webhook endpoints and deliveries                       | [Webhooks](/guides/webhooks/)                         |
| Storage destinations: 10 per workspace                 | [Storage destinations](/guides/storage-destinations/) |
| Report archive contents                                | [Import report archives](/guides/jsreport-import/)    |

---

# Python client

Source: https://docs.typefold.dev/clients/python/

`typefold-client` is the Python package for the Typefold API. It renders reports, HTML and
template versions, email and SMS text, and batches, and handles render status, cancellation and
downloads. The [.NET](/clients/dotnet/), Python and [TypeScript](/clients/typescript/) clients
have the same features. For templates, assets, webhooks and administration, call the
[HTTP API](/clients/http/).

## Before you start

- Python 3.10 or later.
- An API key with the `render:create`, `render:read` and `template:read` scopes; see
  [API keys and scopes](/clients/http/#api-keys).
- A published template to render, such as one named `Invoice`. See
  [Build your first template](/guides/first-template/).
- `PDF_URL` set to the address you open Studio at, where the API also answers, and `API_KEY` set
  to the key.

## 1. Install the package

```sh
pip install typefold-client
```

Its only dependency is [`httpx`](https://www.python-httpx.org/). A self-hosted server older than
the client refuses fields and endpoints it does not know; see
[versioning](/clients/http/#compatibility).

## 2. Create a client

```python
import os

from typefold import TypefoldClient

client = TypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"])
```

Create one client per API key and reuse it. Call `client.close()` when your application stops, or
use the client in a `with` block.

## 3. Render a report

`render_report` renders the published version of a template, found by name, through the
[Reports API](/guides/reports/) and returns the file's bytes:

```python
from pathlib import Path

from typefold import RenderReportRequest, TemplateRef

pdf = client.render_report(
    RenderReportRequest(
        template=TemplateRef.by_name("Invoice"),
        data={"number": "2026-0042", "customer": {"name": "Ada Lovelace"}},
    )
)

Path("invoice.pdf").write_bytes(pdf)
```

Open `invoice.pdf`: you should see the template filled with your data, so `{{customer.name}}`
prints `Ada Lovelace`.

For an Excel file from a [spreadsheet template](/guides/spreadsheets/), pass
`format=ReportFormat.XLSX`. To change the paper, margins or PDF standard for one render, pass
`pdf=ReportPdfOptions(...)`.

## Use asyncio

`AsyncTypefoldClient` has the same methods as coroutines. Use it in FastAPI, aiohttp and other
asyncio applications:

```python
import os

from typefold import AsyncTypefoldClient

async with AsyncTypefoldClient(os.environ["PDF_URL"], os.environ["API_KEY"]) as client:
    pdf = await client.render_report(request)
```

Outside an `async with` block, close it with `await client.aclose()`. Cancelling an asyncio task
stops your code waiting, not the render; call `cancel_render` for that.

## Render HTML or a template version

`render` renders through the [Renders API](/guides/rendering/): HTML you send, or a published
template version. It creates the render, waits for it and downloads the PDF.

```python
from typefold import DirectRenderRequest, HtmlDocument, PageSize, RenderSettings

pdf = client.render(
    DirectRenderRequest(
        document=HtmlDocument(
            html="<h1>Invoice 42</h1><p>Total: 1,250.00 EUR</p>",
            css=["h1 { color: #0b5394; }"],
        ),
        settings=RenderSettings(page_size=PageSize.LETTER),
    )
)
```

To render a published template version, pass its ID and the data:

```python
from typefold import TemplateVersionRenderRequest

ticket = client.render(
    TemplateVersionRenderRequest(template_version_id=version_id, data={"ticket": {"number": "TK-1"}})
)
```

`render` waits two minutes by default; pass `timeout=300` to wait five. Without `settings`, the
page is A4 with 10 mm margins.

## Render in the background

For long or numerous renders, create the render, store its ID, and pick up the PDF later:

```python
from typefold import RenderState

# 1. Create. Returns as soon as the render is queued.
render = client.create_render(request)
save_render_id(order_id, render.id)

# 2. Later, in a job or after a webhook arrives:
render = client.get_render(render_id)

if render.state == RenderState.SUCCEEDED:
    pdf = client.download(render)
```

To wait in the same process instead, call `client.wait_for_render(render)`, which polls until the
render finishes. To be called when it finishes, use [webhooks](/guides/webhooks/). If you no
longer need a render, call `client.cancel_render(render.id)`.

## Render a batch

`create_batch` creates up to 100 renders in one request; if any item is invalid, none is created.
`wait_for_batch` waits until every item has finished, and `download_batch` returns one PDF of
every item in order:

```python
batch = client.create_batch(
    [TemplateVersionRenderRequest(template_version_id=version_id, data=ticket) for ticket in tickets],
    idempotency_key="tickets-2026-10-12",
)
batch = client.wait_for_batch(batch)

if batch.counts.succeeded == batch.total:
    pdf = client.download_batch(batch.id)
```

A failed item does not stop the others. `batch.items` gives each item's render `id` and `state`,
to download or cancel it as a single render. See
[Render many documents at once](/guides/batch-rendering/).

## Retry safely

`render_report`, `create_render`, `render` and `create_batch` take an optional `idempotency_key`.
Retrying with the same key returns what the first call created instead of rendering again, so a
network failure never produces a duplicate document:

```python
key = f"invoice-{invoice.id}-v{invoice.revision}"

pdf = client.render_report(request, idempotency_key=key)
```

Use a key that names the document. For reports, keys apply to PDF only. The rules are in
[idempotency keys](/guides/rendering/#idempotency-keys).

## Handle errors

The client resends a request the API refused with `429 RATE_LIMITED`, up to three times by
default. When those run out, and for every other API error, it raises `TypefoldError`; its
`code` says what went wrong and `retryable` whether trying again can help:

```python
from typefold import TypefoldError

try:
    pdf = client.render_report(request, idempotency_key=key)
except TypefoldError as error:
    if error.code == "RENDER_TIMEOUT":
        # Still rendering. Follow it later with client.get_render(error.error.render_id).
        queue_follow_up(error.error.render_id)
    elif error.retryable:
        # RATE_LIMITED, a 5xx, and similar: back off and retry with the same idempotency key.
        raise
    else:
        # Not worth retrying as is: fix the request, template or key.
        log.error("PDF render failed: %s", error.code)
```

Every code is in the [error reference](/clients/http/#errors).

## Render email and SMS text

`render_string` fills a template string and returns the text, with no PDF. The formats and
engines are explained in [Render email and SMS text](/guides/string-rendering/).

```python
from typefold import RenderStringRequest, StringEngine, StringFormat

body = client.render_string(
    RenderStringRequest(
        template="{{#if (isEqual Status 'paid')}}Paid{{else}}Due{{/if}}: {{Booking.Code}}",
        data=model,
        engine=StringEngine.HANDLEBARS,
        helpers="function isEqual(a, b) { return a === b; }",
        format=StringFormat.HTML,
    )
)
```

## Reference

Everything is in the `typefold` module.

### Client options

`TypefoldClient(base_url, api_key, *, http_client=None, max_rate_limit_retries=3)`:

| Option                   | Default                  | Meaning                                                                                                                                                                                 |
| ------------------------ | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `base_url`               | Required                 | The address you open Studio at, such as `https://pdf.example.com`. A base path such as `/pdf` is kept.                                                                                  |
| `api_key`                | Required                 | Your API key.                                                                                                                                                                           |
| `http_client`            | A new one, 120 s timeout | A shared `httpx.Client` (`httpx.AsyncClient` for the async client), not closed with this client. Keep its timeout above the [Reports API wait](/clients/limits/#renders) of 95 seconds. |
| `max_rate_limit_retries` | `3`                      | How many times a request refused with `429` is sent again, after the wait the API asks for. `0` raises the first one.                                                                   |

### Methods

`AsyncTypefoldClient` has the same methods as coroutines.

| Method                                         | Returns               | Scopes                                                       |
| ---------------------------------------------- | --------------------- | ------------------------------------------------------------ |
| `render_report(request, *, idempotency_key)`   | `bytes`               | `render:create`, `template:read`, plus `render:read` for PDF |
| `render_string(request)`                       | `str`                 | `render:create`                                              |
| `list_reports()`                               | `list[ReportSummary]` | `template:read`                                              |
| `get_report_data_schema(format, template)`     | `dict` (JSON Schema)  | `template:read`                                              |
| `create_render(request, *, idempotency_key)`   | `Render`              | `render:create`                                              |
| `get_render(id)`                               | `Render`              | `render:read`                                                |
| `wait_for_render(render, *, timeout)`          | `Render`              | `render:read`                                                |
| `download(render)`                             | `bytes`               | `render:read`, only when it refreshes the link               |
| `render(request, *, idempotency_key, timeout)` | `bytes`               | `render:create`, `render:read`                               |
| `cancel_render(id)`                            | `None`                | `render:cancel`                                              |
| `create_batch(items, *, idempotency_key)`      | `RenderBatch`         | `render:create`                                              |
| `get_batch(id)`                                | `RenderBatch`         | `render:read`                                                |
| `wait_for_batch(batch, *, timeout)`            | `RenderBatch`         | `render:read`                                                |
| `download_batch(id)`                           | `bytes`               | `render:read`                                                |

`wait_for_render` and `wait_for_batch` poll every 1 to 5 seconds, and keep polling through a
dropped connection or a retryable error such as `RATE_LIMITED`. They raise `RENDER_TIMEOUT` after
`timeout` seconds: two minutes by default for a render, ten minutes for a batch. `download`
re-reads the render first when its download link is about to expire.

### Request types

Requests are dataclasses with the API's fields in snake_case. Fields you don't set are not sent.

| Type                           | Use it for                                                                                                                                               |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RenderReportRequest`          | `render_report`: `template`, `data`, `format` (default `pdf`), `locale` (default `en-US`), `pdf`, `image` and `test`.                                    |
| `ReportPdfOptions`             | A report's `pdf`: paper, margins, page ranges, metadata, PDF/A, PDF/UA, attachments, passwords, signature, other templates' pages and watermark.         |
| `TemplateVersionRenderRequest` | `render`, `create_render` and `create_batch`: a published template version, by `template_version_id`, with `data`.                                       |
| `DirectRenderRequest`          | `render`, `create_render` and `create_batch`: your HTML, as an `HtmlDocument`, with `RenderSettings`.                                                    |
| `RenderSettings`               | A direct render's page: size (default A4), orientation, margins (default 10 mm each), locale, page ranges, metadata, PDF/A, PDF/UA.                      |
| `RenderStringRequest`          | `render_string`: `template`, `data`, `format`, `engine` and `helpers`.                                                                                   |
| `PdfMetadata`                  | The document's title, author, language and other properties.                                                                                             |
| `PdfEncryption`                | Passwords, and the `PdfPermissions` readers get without the owner password.                                                                              |
| `PdfSignature`                 | A digital signature. `certificate` is the name of a certificate under **Manage → Signing certificates** in Studio; `PdfSignatureField` makes it visible. |
| `PdfAttachment`                | A file embedded in the PDF, such as e-invoice XML.                                                                                                       |
| `PdfOperation`                 | Another template's or a PDF file's pages added to a report, before, after or drawn onto its pages (`PdfOperationType`).                                  |
| `PdfWatermark`                 | Text such as `DRAFT` across every page; see [watermarks](/guides/rendering/#watermarks).                                                                 |
| `ImageOptions`                 | The page, width and JPEG quality of an [image](/guides/rendering/#render-an-image), with `format` set to `RenderFormat.PNG`, `JPEG` or `WEBP`.           |

`TemplateVersionRenderRequest` and `DirectRenderRequest` also take `metadata`, `attachments`,
`encryption`, `signature`, `watermark`, `format`, `image` and `test`, and `TemplateVersionRenderRequest` takes `locale`. `test=True` makes a free, watermarked
[test render](/guides/rendering/#test-renders).

`TemplateRef.by_name`, `by_id` and `by_shortid` pick the template; `by_shortid` is for templates
you [migrated](/guides/jsreport-import/). `PageSize` has `A3`, `A4`, `A5`, `LETTER` and `LEGAL`,
or use `PageSize(width_mm, height_mm)`. What each field does is in
the [API reference](/reference/api/) and
[PDF standards and security](/guides/pdf-standards/).

### How data is sent

`data` is sent with its keys unchanged, so `{"CustomerName": "Ada"}` is `{{CustomerName}}` in the
template, and `None` is sent as `null`. Dates and datetimes are written in ISO 8601, `Decimal`
values as numbers, UUIDs as strings and dataclasses as objects. A NaN or infinity raises
`ValueError` before the request is sent. A template version or string render without `data` sends
`{}`.

### Errors

`TypefoldError` has `status_code` (`None` when the client raised the error itself), `code`,
`retryable` and `error`, the API's [error object](/clients/http/#errors) with `message`, `details`,
`diagnostics` and `render_id`. The client raises these codes itself:

| Code             | When                                                                                                                          |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `RENDER_TIMEOUT` | `render`, `wait_for_render` or `wait_for_batch` ran out of time. Retryable. For a render, `render_id` names it to follow.     |
| `RENDER_FAILED`  | A render was cancelled while `render` waited. A failed render raises with the error it recorded instead.                      |
| `HTTP_ERROR`     | A response that was not the API's error format, such as a proxy's error page or a failed download. Retryable for 429 and 5xx. |

`download` raises `ValueError` for a render that has no file, because it has not succeeded.

---

# TypeScript and JavaScript client

Source: https://docs.typefold.dev/clients/typescript/

`@typefold/client` is the npm package for the Typefold API, for TypeScript and
JavaScript. It renders reports, HTML and template versions, email and SMS text, and batches, and
handles render status, cancellation and downloads. The [.NET](/clients/dotnet/),
[Python](/clients/python/) and TypeScript clients have the same features. For templates, assets,
webhooks and administration, call the [HTTP API](/clients/http/).

## Before you start

- Node.js 20.3 or later, on a server. The API sends no CORS headers, so the client does not work
  in a browser, and your API key stays on the server.
- An API key with the `render:create`, `render:read` and `template:read` scopes. Create it in
  Studio under **Manage → API keys**; see [API keys and scopes](/clients/http/#api-keys).
- A published template to render, such as one named `Invoice`. See
  [Build your first template](/guides/first-template/).

## 1. Install the package

```sh
npm install @typefold/client
```

It has no dependencies; it uses the built-in `fetch`. Use a client no newer than your server;
see [versioning](/clients/http/#compatibility).

## 2. Create a client

```ts
import { TypefoldClient } from "@typefold/client";

const client = new TypefoldClient({
  baseUrl: process.env.PDF_URL!,
  apiKey: process.env.API_KEY!,
});
```

Set `PDF_URL` to your installation's address, the URL you open Studio at, and `API_KEY` to your
key. In JavaScript, leave out the `!`. Create one client per API key and reuse it for the
lifetime of your application.

## 3. Render a report

`renderReport` renders the published version of a template, found by name, and returns the
file's bytes:

```ts
import { writeFile } from "node:fs/promises";
import { TemplateRef } from "@typefold/client";

const pdf = await client.renderReport({
  template: TemplateRef.byName("Invoice"),
  data: { number: "2026-0042", customer: { name: "Ada Lovelace" } },
});

await writeFile("invoice.pdf", pdf);
```

Open `invoice.pdf`: you should see the template filled with your data, so `{{customer.name}}`
prints `Ada Lovelace`.

For an Excel file from a spreadsheet template, set `format: ReportFormat.Xlsx`. To change the
paper, margins or PDF standard for one render, set `pdf`.

## Render HTML or a template version

`render` renders through the [Renders API](/guides/rendering/): HTML you send, or a published
template version. It creates the render, waits for it and downloads the PDF.

```ts
import { PageSize } from "@typefold/client";

const pdf = await client.render({
  document: {
    html: "<h1>Invoice 42</h1><p>Total: 1,250.00 EUR</p>",
    css: ["h1 { color: #0b5394; }"],
  },
  settings: { pageSize: PageSize.Letter },
});
```

To render a published template version, pass its ID and the data:

```ts
const ticket = await client.render({
  templateVersionId: versionId,
  data: { ticket: { number: "TK-1" } },
});
```

`render` waits two minutes by default; pass `{ timeoutMs: 300_000 }` to wait five. Without
`settings`, the page is A4 with 10 mm margins.

## Render in the background

For long or numerous renders, create the render, store its ID, and pick up the PDF later:

```ts
import { RenderState } from "@typefold/client";

// 1. Create. Returns as soon as the render is queued.
let render = await client.createRender(request);
await saveRenderId(orderId, render.id);

// 2. Later, in a job or after a webhook arrives:
render = await client.getRender(renderId);

if (render.state === RenderState.Succeeded) {
  const pdf = await client.download(render);
}
```

To wait in the same process instead, call `client.waitForRender(render)`, which polls until the
render finishes. To be called when it finishes, use [webhooks](/guides/webhooks/). If you no
longer need a render, call `client.cancelRender(render.id)`.

## Render a batch

`createBatch` creates up to 100 renders in one request; if any item is invalid, none is created.
`waitForBatch` waits until every item has finished, and `downloadBatch` returns one PDF of every
item in order:

```ts
let batch = await client.createBatch(
  tickets.map((ticket) => ({ templateVersionId: versionId, data: ticket })),
  { idempotencyKey: "tickets-2026-10-12" },
);
batch = await client.waitForBatch(batch);

if (batch.counts.succeeded === batch.total) {
  const pdf = await client.downloadBatch(batch.id);
}
```

A failed item does not stop the others. `batch.items` gives each item's render `id` and `state`,
to download or cancel it as a single render. See
[Render many documents at once](/guides/batch-rendering/).

## Retry safely

`renderReport`, `createRender`, `render` and `createBatch` take an optional `idempotencyKey`.
Retrying with the same key returns what the first call created instead of rendering again, so a
network failure never produces a duplicate document:

```ts
const idempotencyKey = `invoice-${invoice.id}-v${invoice.revision}`;

const pdf = await client.renderReport(request, { idempotencyKey });
```

Use a key that names the document. For reports, keys apply to PDF only. The rules are in
[idempotency keys](/guides/rendering/#idempotency-keys).

## Handle errors

The client retries `429 RATE_LIMITED` for you. Every other API error throws
`TypefoldError`; its `code` says what went wrong and `retryable` whether trying again can
help:

```ts
import { TypefoldError } from "@typefold/client";

try {
  const pdf = await client.renderReport(request, { idempotencyKey });
} catch (error) {
  if (!(error instanceof TypefoldError)) {
    throw error;
  }

  if (error.code === "RENDER_TIMEOUT") {
    // Still rendering. Follow it later with client.getRender(error.error.renderId).
    await queueFollowUp(error.error.renderId!);
  } else if (error.retryable) {
    // RATE_LIMITED, a 5xx, and similar: back off and retry with the same idempotency key.
  } else {
    // Not worth retrying as is: fix the request, template or key.
    console.error("PDF render failed:", error.code);
  }
}
```

Every code is in the [error reference](/clients/http/#errors).

## Render email and SMS text

`renderString` fills a template string and returns the text, with no PDF. See
[Render email and SMS text](/guides/string-rendering/).

```ts
import { StringEngine, StringFormat } from "@typefold/client";

const body = await client.renderString({
  template: "{{#if (isEqual Status 'paid')}}Paid{{else}}Due{{/if}}: {{Booking.Code}}",
  data: model,
  engine: StringEngine.Handlebars,
  helpers: "function isEqual(a, b) { return a === b; }",
  format: StringFormat.Html,
});
```

`StringFormat.Html` escapes values and `StringFormat.Text` (the default) does not. Without
`engine`, only `{{path}}` placeholders are filled.

## Reference

Everything is exported from `@typefold/client`, with types.

### Client options

`new TypefoldClient({ baseUrl, apiKey, ... })`:

| Option                | Default        | Meaning                                                                                                                      |
| --------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `baseUrl`             | Required       | The API's address, such as `https://pdf.example.com`. A base path such as `/pdf` is kept.                                    |
| `apiKey`              | Required       | Sent as `x-api-key` on each API request, never to download URLs.                                                             |
| `requestTimeoutMs`    | `120000`       | How long one HTTP request may take. Keep it above the [Reports API wait](/clients/limits/#renders) of 95 seconds.            |
| `maxRateLimitRetries` | `3`            | How many times a `429` is sent again, after its `Retry-After` (else 1, 2, 4… seconds, at most 30). `0` throws the first one. |
| `fetch`               | Global `fetch` | The `fetch` to send requests with, such as one with a proxy agent.                                                           |

### Methods

Every method also takes an `AbortSignal` as `{ signal }` in its last argument.

| Method                                           | Returns            | Scopes                                                       |
| ------------------------------------------------ | ------------------ | ------------------------------------------------------------ |
| `renderReport(request, { idempotencyKey })`      | `Uint8Array`       | `render:create`, `template:read`, plus `render:read` for PDF |
| `renderString(request)`                          | `string`           | `render:create`                                              |
| `listReports()`                                  | `ReportSummary[]`  | `template:read`                                              |
| `getReportDataSchema(format, template)`          | JSON Schema object | `template:read`                                              |
| `createRender(request, { idempotencyKey })`      | `Render`           | `render:create`                                              |
| `getRender(id)`                                  | `Render`           | `render:read`                                                |
| `waitForRender(render, { timeoutMs })`           | `Render`           | `render:read`                                                |
| `download(render)`                               | `Uint8Array`       | `render:read`, only when it refreshes the link               |
| `render(request, { idempotencyKey, timeoutMs })` | `Uint8Array`       | `render:create`, `render:read`                               |
| `cancelRender(id)`                               | Nothing            | `render:cancel`                                              |
| `createBatch(items, { idempotencyKey })`         | `RenderBatch`      | `render:create`                                              |
| `getBatch(id)`                                   | `RenderBatch`      | `render:read`                                                |
| `waitForBatch(batch, { timeoutMs })`             | `RenderBatch`      | `render:read`                                                |
| `downloadBatch(id)`                              | `Uint8Array`       | `render:read`                                                |

`waitForRender` and `waitForBatch` poll every 1 to 5 seconds and throw `RENDER_TIMEOUT` after
`timeoutMs`: two minutes for a render, 10 minutes for a batch. A dropped connection or a
retryable error such as `RATE_LIMITED` does not stop them. `download` re-reads the render first
when its download link is about to expire. Aborting a signal stops your code waiting, not the
render; call `cancelRender` for that.

### Request types

Requests are plain objects with the API's own field names, typed in the package.

| Type                           | Used for                                                                     |
| ------------------------------ | ---------------------------------------------------------------------------- |
| `RenderReportRequest`          | `renderReport`. Its `pdf` field is a `ReportPdfOptions`.                     |
| `DirectRenderRequest`          | Your own HTML, in `render`, `createRender` and `createBatch`.                |
| `TemplateVersionRenderRequest` | A published template version, in `render`, `createRender` and `createBatch`. |
| `RenderSettings`               | The `settings` of a `DirectRenderRequest`: paper, margins, PDF standard.     |
| `RenderStringRequest`          | `renderString`.                                                              |

Document properties, attachments, passwords, signatures, added pages and watermarks use
`PdfMetadata`, `PdfAttachment`, `PdfEncryption`, `PdfSignature`, `PdfOperation` and
`PdfWatermark`. `format: RenderFormat.Png`, `Jpeg` or `Webp` on a render or report request, with
`image` (`ImageOptions`), returns one page as an [image](/guides/rendering/#render-an-image).
`TemplateRef.byName`,
`byId` and `byShortid` pick the template; `byShortid` is for templates you
[migrated](/guides/jsreport-import/). `PageSize` has `A3`, `A4`, `A5`, `Letter` and `Legal`, or
use any `{ widthMm, heightMm }`. `test: true` on a render or report request makes a free,
watermarked [test render](/guides/rendering/#test-renders). What each field does is in
the [API reference](/reference/api/) and
[PDF standards and security](/guides/pdf-standards/).

### How data is sent

`data` is sent as `JSON.stringify` writes it, with its keys unchanged, so
`{ CustomerName: "Ada" }` is `{{CustomerName}}` in the template, and `null` is kept. A `Date` is
written in ISO 8601, and `undefined` values are left out. A template version or string render
without `data` sends `{}`.

### Errors

`TypefoldError` has `status` (`undefined` when the client raised the error itself), `code`,
`retryable` and `error`, the API's error with `code`, `message`, `retryable`, `details`,
`diagnostics` and `renderId`; see [the error envelope](/clients/http/#errors).
The client raises these codes itself:

| Code             | When                                                                                                                          |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `RENDER_TIMEOUT` | A wait ran out of time. Retryable. For a render, follow `renderId`.                                                           |
| `RENDER_FAILED`  | A render was cancelled while `render` waited. A failed render throws with the error it recorded instead.                      |
| `HTTP_ERROR`     | A response that was not the API's error format, such as a proxy's error page or a failed download. Retryable for 429 and 5xx. |

---

# Configuration reference

Source: https://docs.typefold.dev/self-hosting/configuration/

The settings of a self-hosted installation, with their defaults. You set them in `.env`, in the
installation directory next to `compose.yaml` (see [install](/self-hosting/install/#1-download-the-release-files)).

## How settings work

1. Edit `.env` on the server.
2. Run `docker compose up -d` in the same directory. Compose recreates only the services whose
   settings changed.

Rules that apply to every setting:

- **Empty means unset.** `RENDER_RETENTION_DAYS=` is the same as leaving the line out, so the
  default applies.
- **A bad value stops the service.** The API and worker check their settings at startup. A
  missing or invalid value stops them with a log line that names the settings, never their
  values, such as `Invalid environment variables: OBJECT_STORAGE_BUCKET.`
- **A few settings do not go in `.env`.** The [advanced settings](#advanced-settings) go in
  `compose.override.yaml` instead.

:::tip
`env.example` in each release lists the `.env` settings with comments. Compare it with your
`.env` after an upgrade to see what is new.
:::

## Required settings

The installation does not start until these are set.

| Setting               | Example                             | Description                                                                                                                                                                                                                                         |
| --------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PUBLIC_URL`          | `https://pdf.example.com`           | The address people and API clients use. Sign-in links and file URLs are built from it. Must be `https://` unless it is a localhost address.                                                                                                         |
| `POSTGRES_PASSWORD`   | output of `openssl rand -hex 32`    | The database password. Use hex: other characters can break the database connection.                                                                                                                                                                 |
| `BETTER_AUTH_SECRET`  | output of `openssl rand -hex 32`    | Signs sign-in sessions and file links. At least 32 characters.                                                                                                                                                                                      |
| `DATA_ENCRYPTION_KEY` | output of `openssl rand -base64 32` | Encrypts secrets stored in the database: webhook signing secrets, signing certificate keys, storage destination access keys, and the passwords of protected PDFs while they render. Exactly 32 random bytes in base64. Cannot be recreated if lost. |

Also set `LICENSE_KEY` to your license key. The installation starts without it, but renders
nothing; see [licensing](/self-hosting/licensing/).

:::caution
PostgreSQL reads `POSTGRES_PASSWORD` only when it creates its database, on the first start.
Changing it in `.env` later locks the API and worker out. To change it, change the password in
PostgreSQL first, then in `.env`.
:::

## Address, HTTPS and proxies

| Setting                | Default          | Description                                                                                                                                                                                                                      |
| ---------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CERTIFICATE_SOURCE`   | `automatic`      | Where the HTTPS certificate comes from. `automatic`: Let's Encrypt, or Caddy's own CA for an IP address or a `.internal`, `.home.arpa` or `.local` name. `internal`: Caddy's own CA for any name. `files`: your own certificate. |
| `CERTIFICATE_PATH`     | `./certificates` | The directory, relative to `compose.yaml`, holding `certificate.pem` and `key.pem` for `CERTIFICATE_SOURCE=files`.                                                                                                               |
| `HTTP_PORT`            | `80`             | The host port the proxy publishes for HTTP.                                                                                                                                                                                      |
| `HTTPS_PORT`           | `443`            | The host port the proxy publishes for HTTPS (TCP and UDP).                                                                                                                                                                       |
| `TRUSTED_PROXY_RANGES` | empty            | Address ranges of a CDN or load balancer in front of the server, separated by spaces, or `private_ranges`. Empty: the client is whoever connects.                                                                                |

Let's Encrypt must reach the server on ports 80 and 443, so change `HTTP_PORT` and `HTTPS_PORT`
only if something in front forwards those ports. How to use these settings:
[on a private network](/self-hosting/install/#on-a-private-network) and
[behind a CDN or load balancer](/self-hosting/install/#behind-a-cdn-or-load-balancer).

## Secrets and encryption

`POSTGRES_PASSWORD`, `BETTER_AUTH_SECRET` and `DATA_ENCRYPTION_KEY` are under
[required settings](#required-settings).

| Setting                        | Default | Description                                                                     |
| ------------------------------ | ------- | ------------------------------------------------------------------------------- |
| `DATA_ENCRYPTION_KEY_PREVIOUS` | empty   | The old key while you rotate `DATA_ENCRYPTION_KEY`. It is only used to decrypt. |

### Rotate the data encryption key

1. In `.env`, move the current value of `DATA_ENCRYPTION_KEY` to `DATA_ENCRYPTION_KEY_PREVIOUS`.
2. Set `DATA_ENCRYPTION_KEY` to a new value from `openssl rand -base64 32`, and store it with your
   other secrets.
3. Run `docker compose up -d`. The API encrypts the stored secrets again with the new key as it
   starts, and retries every hour.
4. Once `docker compose logs api` shows neither `Webhook secret encryption failed` nor
   `Signing key encryption failed`, remove `DATA_ENCRYPTION_KEY_PREVIOUS` and run
   `docker compose up -d` again.

Database backups taken before the rotation need the old key to restore; see
[the data encryption key](/self-hosting/install/#the-data-encryption-key).

## Sign-in

Password accounts need no settings. These turn on the other sign-in methods; how to set each one
up is in [users and sign-in](/self-hosting/users/#choose-sign-in-methods).

| Setting               | Default | Description                                                                                                     |
| --------------------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| `RESEND_API_KEY`      | empty   | A [Resend](https://resend.com) API key. With `AUTH_EMAIL_FROM`, turns on emailed sign-in codes and invitations. |
| `AUTH_EMAIL_FROM`     | empty   | The sender address for those emails, on a domain verified in Resend.                                            |
| `ENTRA_TENANT_ID`     | empty   | The directory (tenant) ID of your Microsoft Entra ID tenant. For **Sign in with Microsoft**.                    |
| `ENTRA_CLIENT_ID`     | empty   | The application (client) ID of the app registered in that tenant.                                               |
| `ENTRA_CLIENT_SECRET` | empty   | A client secret of that app.                                                                                    |

Email codes turn on only when both email settings are set. Set all three `ENTRA_*` settings or
none: the API refuses to start with only some of them.

## Templates from PDFs

| Setting             | Default | Description                                                                                                                                                  |
| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ANTHROPIC_API_KEY` | empty   | A [Claude API](https://platform.claude.com/) key. Turns on **Start with → PDF file, drafted with AI** in Studio, which sends each PDF to Anthropic's Claude. |

Anthropic bills your Claude API account for each PDF: about USD 0.20 on average, and at most USD 1.50,
where a conversion stops. Workspaces have no monthly limit unless a platform administrator sets one under
**Manage → Render limits**.

## Automated setup

These let a deployment tool set up an installation and deploy templates without anyone opening
Studio. [Set up from configuration](/self-hosting/users/#set-up-from-configuration) explains how
they behave on each start.

| Setting            | Default | Description                                                                                                                                                                                   |
| ------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ADMIN_EMAIL`      | empty   | This account becomes the first platform administrator, instead of someone using the setup token. Ignored once an administrator exists.                                                        |
| `DEPLOY_WORKSPACE` | empty   | On the first start with `ADMIN_EMAIL`: the name of the workspace to create. Otherwise: the name of the existing workspace to issue the first deploy key in. Ignored once a deploy key exists. |
| `DEPLOY_API_KEY`   | empty   | The secret of the [deploy key](/self-hosting/users/#the-deploy-key), an API key that can import and publish templates. You choose it: `pdf_` and at least 40 letters, digits, `-` or `_`.     |

## Rendering

| Setting                    | Default | Description                                                                                                                                                      |
| -------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RENDER_RETENTION_DAYS`    | `30`    | Days after creation that finished renders, their PDFs and webhook delivery records are deleted. At least `1`. Lowering it deletes older renders within the hour. |
| `RENDER_TIMEOUT_MS`        | `60000` | Milliseconds one render may run before it fails with `LIMIT_EXCEEDED`. From `1000` to `3600000`.                                                                 |
| `WORKER_CLOSE_GRACE_MS`    | `75000` | Milliseconds a stopping worker waits for its current render. Keep it at least 15000 above `RENDER_TIMEOUT_MS`.                                                   |
| `WORKER_STOP_GRACE_PERIOD` | `90s`   | How long Compose waits before it kills a stopping worker. Keep it at least 15 seconds above `WORKER_CLOSE_GRACE_MS`.                                             |
| `SCRIPT_ENV`               | empty   | Values that `beforeRender` scripts read as `process.env`, as comma-separated `NAME=value` pairs, such as `ADD_WATERMARK=true`.                                   |

When you raise `RENDER_TIMEOUT_MS`, raise both grace periods with it; see
[what happens to work in flight](/self-hosting/install/#what-happens-to-work-in-flight).

### `SCRIPT_ENV`

For example, to add a watermark outside production:

```sh
SCRIPT_ENV=ADD_WATERMARK=true,ENVIRONMENT_NAME=staging
```

Every workspace's scripts can read these values, so never put secrets in them. A malformed list
stops the API at startup. A new value applies once `docker compose up -d` has recreated the API;
templates need no new publish. How scripts read the values is in
[environment values](/templates/handlebars/#environment-values).

## Webhooks

| Setting                          | Default | Description                                                                                                                                                                      |
| -------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `WEBHOOK_ALLOW_PRIVATE_NETWORKS` | `false` | `true` lets [webhooks](/guides/webhooks/) reach addresses outside the [allowed destinations](/guides/webhooks/#allowed-destinations), such as private addresses and this server. |

Turn it on only when your webhook receivers run on your own network. While it is off, no workspace
member can use a webhook to reach services inside your network.

## Storage destinations

| Setting                              | Default | Description                                                                                                                                                                          |
| ------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `DESTINATION_ALLOW_PRIVATE_NETWORKS` | `false` | `true` lets [storage destinations](/guides/storage-destinations/) use private addresses, this server and plain `http://` endpoints, such as a MinIO server next to the installation. |

The API tests a destination when it is saved and the worker uploads to it, so both need the
setting; set it in `.env`. Turn it on only when your buckets are on your own network. While it is
off, no workspace member can use a destination to reach services inside your network.

## File storage

| Setting                            | Default     | Description                                                                                                                                                         |
| ---------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `STORAGE_DRIVER`                   | `local`     | Where PDFs and uploaded files live: `local` (the `storage-data` volume on the server), `s3` or `azure`.                                                             |
| `OBJECT_STORAGE_BUCKET`            | empty       | The S3 bucket, or the Azure container. Required for `s3` and `azure`.                                                                                               |
| `OBJECT_STORAGE_ENDPOINT`          | empty       | The S3 endpoint URL, such as `https://s3.eu-central-1.amazonaws.com`. Empty uses Amazon S3's default for the region.                                                |
| `OBJECT_STORAGE_REGION`            | `us-east-1` | The S3 region.                                                                                                                                                      |
| `OBJECT_STORAGE_ACCESS_KEY_ID`     | empty       | The S3 access key ID. Required for `s3`.                                                                                                                            |
| `OBJECT_STORAGE_SECRET_ACCESS_KEY` | empty       | The S3 secret access key. Required for `s3`.                                                                                                                        |
| `OBJECT_STORAGE_FORCE_PATH_STYLE`  | `true`      | Use path-style URLs (`https://host/bucket/key`). Set `false` for Amazon S3; keep `true` for MinIO and similar services.                                             |
| `OBJECT_STORAGE_PUBLIC_ENDPOINT`   | empty       | For `s3`: the endpoint browsers and API clients reach, when it differs from `OBJECT_STORAGE_ENDPOINT`. Download and upload links use it.                            |
| `AZURE_STORAGE_CONNECTION_STRING`  | empty       | The storage account's connection string, including its account key. Required for `azure`.                                                                           |
| `STUDIO_FILE_ORIGINS`              | empty       | Origins Studio may load files from, separated by spaces, when files are in `s3` or `azure`. Empty allows any `https://` origin; an `http://` origin must be listed. |

Step by step for each service: [file storage](/self-hosting/install/#file-storage).

## Memory and logs

Memory values use Docker's units, such as `512m` and `2g`. How to size them:
[memory limits](/self-hosting/install/#memory-limits).

| Setting                   | Default | Description                                         |
| ------------------------- | ------- | --------------------------------------------------- |
| `POSTGRES_MEMORY_LIMIT`   | `1g`    | Memory limit of the `postgres` container.           |
| `REDIS_MEMORY_LIMIT`      | `512m`  | Memory limit of the `redis` container.              |
| `API_MEMORY_LIMIT`        | `1536m` | Memory limit of the `api` container.                |
| `WORKER_MEMORY_LIMIT`     | `2g`    | Memory limit of each `worker` container.            |
| `SANDBOX_MEMORY_LIMIT`    | `1g`    | Memory limit of the `sandbox` container.            |
| `STUDIO_MEMORY_LIMIT`     | `512m`  | Memory limit of the `studio` container.             |
| `PROXY_MEMORY_LIMIT`      | `256m`  | Memory limit of the `proxy` container.              |
| `MONITORING_MEMORY_LIMIT` | `1g`    | Memory limit of the `prometheus` container.         |
| `LOG_MAX_SIZE`            | `10m`   | Size at which each container's log file is rotated. |
| `LOG_MAX_FILE`            | `5`     | Number of rotated log files each container keeps.   |

## Monitoring

| Setting                | Default | Description                                                                |
| ---------------------- | ------- | -------------------------------------------------------------------------- |
| `COMPOSE_PROFILES`     | empty   | `monitoring` also runs Prometheus with the bundled alert rules.            |
| `PROMETHEUS_PORT`      | `9090`  | The port of the Prometheus UI, published on the server's `127.0.0.1` only. |
| `PROMETHEUS_RETENTION` | `15d`   | How long Prometheus keeps metrics.                                         |

See [monitoring](/self-hosting/monitoring/).

## Advanced settings

The API and worker read a few settings that `compose.yaml` does not pass on, so `.env` cannot set
them. Most installations never need them. To set one, add it to `compose.override.yaml` next to
`compose.yaml` (Compose reads that file automatically), then run `docker compose up -d`:

```yaml
services:
  api:
    environment:
      API_RATE_LIMIT_PER_MINUTE: "3000"
  worker:
    environment:
      RENDER_MAX_PAGES: "100"
```

Keep `compose.override.yaml` when you upgrade.

### API

| Setting                     | Default | Description                                                                                                                                   |
| --------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `API_RATE_LIMIT_PER_MINUTE` | `1200`  | Requests to `/v1/*`, and separately to `/mcp`, each client address may send per minute, across all API replicas. Over it: `429 RATE_LIMITED`. |

When to raise it: [request rate limits](/self-hosting/limits/#request-rate-limits).

### Worker

These caps can only make the [document limits](/clients/limits/#renders) stricter. Values above
the defaults have no effect. A document over a cap fails with `LIMIT_EXCEEDED`.

| Setting                   | Default             | Range           | Description                                             |
| ------------------------- | ------------------- | --------------- | ------------------------------------------------------- |
| `RENDER_MAX_INPUT_BYTES`  | `10485760` (10 MiB) | 1 byte to 1 GiB | Cap on a render's resolved input, including its assets. |
| `RENDER_MAX_PAGES`        | `200`               | 1 to 10000      | Cap on the pages of one PDF.                            |
| `RENDER_MAX_OUTPUT_BYTES` | `52428800` (50 MiB) | 1 byte to 1 GiB | Cap on the size of one PDF.                             |

These set the memory one render may use, and you can raise them:

| Setting                 | Default               | Range            | Description                                                                             |
| ----------------------- | --------------------- | ---------------- | --------------------------------------------------------------------------------------- |
| `RENDER_MAX_WASM_BYTES` | `536870912` (512 MiB) | 64 MiB to 4 GiB  | Layout memory one render may use. A render that needs more fails with `LIMIT_EXCEEDED`. |
| `RENDER_MAX_HEAP_BYTES` | `268435456` (256 MiB) | 64 MiB to 16 GiB | JavaScript memory one render may use. A render that needs more fails.                   |

If a large document fails with a memory error, raise `RENDER_MAX_WASM_BYTES`, and raise
`WORKER_MEMORY_LIMIT` so it stays at least 512 MiB above the two render caps combined.

---

# Install and upgrade

Source: https://docs.typefold.dev/self-hosting/install/

Follow these steps to run Typefold on a Linux server with Docker Compose. At the end, Studio
and the API answer on one HTTPS address and you are signed in as the administrator.

## Before you start

- **A Linux server with an x86-64 (amd64) CPU.** The images are built for `linux/amd64` only.
- **Docker Engine with the Compose v2 plugin**, so that `docker compose` works. See
  [Docker's install guide](https://docs.docker.com/engine/install/).
- **`openssl` and `curl` on the server.**
- **Memory and CPU.** About 6.8 GiB of memory with one worker, plus 2 GiB for each extra worker
  (see [memory limits](#memory-limits)). One CPU for each worker, plus some for the other
  services.
- **A DNS name for the server.** The bundled proxy gets its certificate from Let's Encrypt, which
  must reach the server on ports 80 and 443. If the internet cannot reach the server, read
  [on a private network](#on-a-private-network) first.
- **A license key.** See [get a key](/self-hosting/licensing/#get-a-key).

## 1. Download the release files

Each release comes with two files: `compose.yaml` (the whole installation, which you do not edit)
and `env.example` (every setting, with comments). They and the images are in Typefold's image
registry, which you sign in to with your license key.

Sign in, paste your license key when asked for the password, then copy both files into a new
directory on the server, such as `/opt/typefold`, and copy `env.example` to `.env`:

```sh
docker login registry.typefold.dev -u license
mkdir -p /opt/typefold && cd /opt/typefold
docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/out" registry.typefold.dev/typefold-release:latest
cp env.example .env
chmod 600 .env
```

`latest` is the newest release; for another one, use its version, such as
`typefold-release:v1.4.0`. Docker keeps the sign-in, so `docker compose` pulls the images with
it. If your license ends or is revoked, the registry refuses it.

This is the **installation directory**. `.env` holds your settings and every secret, and every
`docker compose` command in these docs runs from here.

## 2. Generate the secrets

Run each command once and keep its output for the next step:

```sh
openssl rand -hex 32     # for POSTGRES_PASSWORD
openssl rand -hex 32     # for BETTER_AUTH_SECRET
openssl rand -base64 32  # for DATA_ENCRYPTION_KEY
```

## 3. Fill in `.env`

Open `.env` and set the address, the three secrets and your license key:

```sh
PUBLIC_URL=https://pdf.example.com
POSTGRES_PASSWORD=<first hex value>
BETTER_AUTH_SECRET=<second hex value>
DATA_ENCRYPTION_KEY=<base64 value>
LICENSE_KEY=<your trial or purchased key>
```

A first install needs nothing else. [Required settings](/self-hosting/configuration/#required-settings)
explains each value.

:::danger
Copy `.env` somewhere safe now. `DATA_ENCRYPTION_KEY` cannot be recreated; see
[the data encryption key](#the-data-encryption-key).
:::

## 4. Point DNS at the server

Create a DNS record for the host name in `PUBLIC_URL` that points at the server. Open TCP ports 80
and 443, and UDP port 443. The bundled proxy gets and renews the certificate.

## 5. Start it

```sh
docker compose up -d
docker compose ps
curl https://pdf.example.com/health
```

`docker compose ps` lists the services as running, and `curl` prints:

```json
{ "status": "ok" }
```

If not, see [if it does not start](#if-it-does-not-start).

## 6. Become the first platform administrator

A new installation has no administrator. You claim the role with a one-time **setup token** that
the API prints in its log.

1. Create a password account for yourself. The command prints a generated password.

   ```sh
   docker compose exec api node dist/password-account.js you@example.com
   ```

2. Read the setup token:

   ```sh
   docker compose logs api | grep setupToken
   ```

3. Open `PUBLIC_URL` in a browser and sign in with your email address and that password.
4. Studio opens **Set up your installation**. Paste the token into **Setup token** and choose
   **Complete setup**. You are now a platform administrator.
5. Studio opens **Set up your workspace**. Enter a **Workspace name** and choose
   **Create workspace**.

If the token does not work, see
[if the setup token does not work](/self-hosting/users/#if-the-setup-token-does-not-work).

:::tip[Installing from a deployment pipeline?]
`.env` can name the administrator, a workspace and a deploy key instead, so nobody needs the
setup token. See [set up from configuration](/self-hosting/users/#set-up-from-configuration).
:::

## If it does not start

- **`/health` answers `503`.** Its `unavailable` list names what the API cannot reach,
  `database` or `redis`. Run `docker compose logs api` to see why.
- **`docker compose` stops with `Set <setting> in .env`.** That required setting is empty in
  `.env`.
- **The API exits with `Unsafe production settings`.** It refuses an `http://` `PUBLIC_URL`
  (except a localhost address) and well-known example secrets. The log names the setting to fix;
  it calls `PUBLIC_URL` `BETTER_AUTH_URL`.
- **A setting is invalid.** The API and worker stop with a log line such as
  `Invalid environment variables: OBJECT_STORAGE_BUCKET.` See
  [how settings work](/self-hosting/configuration/#how-settings-work).
- **A service stays `created` or `starting`.** Each service waits until the ones it needs are
  healthy. Read the logs of the first service that is not healthy.

## On a private network

An installation only your own network can reach still needs an `https://` `PUBLIC_URL`, because
sign-in cookies only work over HTTPS. What you set depends on the address:

- **An IP address, or a name ending in `.internal`, `.home.arpa` or `.local`**, such as
  `https://10.0.0.5`: nothing. The proxy issues the certificate from its own certificate
  authority. Then [trust the proxy's certificate authority](#trust-the-proxys-certificate-authority).
- **Any other name**, such as `https://pdf.lan`: set `CERTIFICATE_SOURCE=internal` in `.env`,
  then [trust the proxy's certificate authority](#trust-the-proxys-certificate-authority).
- **A certificate from your company's certificate authority**:
  [use your own certificate](#use-your-own-certificate).

### Trust the proxy's certificate authority

Browsers and API clients reject the proxy's certificate until you install its root certificate.
After the first start, copy it out of the `proxy` container:

```sh
docker compose cp proxy:/data/caddy/pki/authorities/local/root.crt typefold-root.crt
```

Install `typefold-root.crt` as a trusted root on every computer and in every API client that
uses the installation. It is valid for ten years. It lives in the `caddy-data` volume: if you lose
that volume, the proxy makes a new root and every client must trust it again.

### Use your own certificate

1. Set `CERTIFICATE_SOURCE=files` in `.env`.
2. Put the certificate chain and its unencrypted private key, both PEM, in a `certificates`
   directory next to `compose.yaml` (`CERTIFICATE_PATH` changes the directory):

   ```text
   /opt/typefold/certificates/certificate.pem
   /opt/typefold/certificates/key.pem
   ```

3. Run `docker compose up -d`. When you replace the files later, run
   `docker compose restart proxy`.

## Behind a CDN or load balancer

The API rate-limits each client address, including sign-in attempts. Behind a CDN or load
balancer, every request arrives from its address, so all clients share one limit. To fix it, tell
the proxy which addresses belong to the CDN or load balancer:

1. In `.env`, set `TRUSTED_PROXY_RANGES` to its address ranges, separated by spaces:

   ```sh
   # A CDN: list every range it publishes.
   TRUSTED_PROXY_RANGES=203.0.113.0/24 198.51.100.0/24 2001:db8::/32
   # A load balancer on the server's private network:
   TRUSTED_PROXY_RANGES=private_ranges
   ```

2. Run `docker compose up -d proxy`.

For requests from those ranges, the proxy takes the client's address from the `X-Forwarded-For`
header.

:::caution
Keep the list exact. Anyone inside a listed range can choose the address the API sees, and so
avoid rate limits.
:::

## File storage

Rendered PDFs and uploaded files (images, fonts and other workspace files) live in file storage.
The default keeps them in the `storage-data` Docker volume on the server and needs no setup. To
keep them in a cloud service instead, set it up before you go live:

| `STORAGE_DRIVER`  | Files live in                                          |
| ----------------- | ------------------------------------------------------ |
| `local` (default) | The `storage-data` volume on the server                |
| `s3`              | Amazon S3 or another S3-compatible service, like MinIO |
| `azure`           | Azure Blob Storage                                     |

:::caution
Changing `STORAGE_DRIVER` does not move existing files. Copy them across yourself.
:::

### Amazon S3 and compatible services

1. Create a bucket, and an access key that can read, write, list and delete objects in it.
2. Add to `.env`:

   ```sh
   STORAGE_DRIVER=s3
   OBJECT_STORAGE_ENDPOINT=https://s3.eu-central-1.amazonaws.com
   OBJECT_STORAGE_REGION=eu-central-1
   OBJECT_STORAGE_BUCKET=my-typefold-bucket
   OBJECT_STORAGE_ACCESS_KEY_ID=...
   OBJECT_STORAGE_SECRET_ACCESS_KEY=...
   OBJECT_STORAGE_FORCE_PATH_STYLE=false   # false for Amazon S3; leave it out for MinIO
   ```

3. Set up [CORS](#bucket-cors-and-studio), then run `docker compose up -d`.

[File storage settings](/self-hosting/configuration/#file-storage) lists the rest, such as a
separate address for browsers.

### Azure Blob Storage

1. Create a storage account and a container.
2. Add to `.env`, with the connection string from the storage account's **Access keys** page (it
   must include the account key):

   ```sh
   STORAGE_DRIVER=azure
   AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;EndpointSuffix=core.windows.net
   OBJECT_STORAGE_BUCKET=pdf-results   # the container's name
   ```

3. Set up [CORS](#bucket-cors-and-studio), then run `docker compose up -d`.

### Bucket CORS and Studio

Studio loads files straight from the bucket or container. In its CORS rules, allow requests from
your `PUBLIC_URL` origin: `GET` for Azure, `GET` and `PUT` for S3, because Studio uploads to S3
directly.

Optionally, limit which file addresses Studio may load from with `STUDIO_FILE_ORIGINS` in
`.env`. A service on `http://`, such as MinIO on your network, must be listed there:

```sh
STUDIO_FILE_ORIGINS=https://my-bucket.s3.eu-central-1.amazonaws.com
```

If the browser console shows `Refused to ...` messages about the Content-Security-Policy, an
origin is missing from `STUDIO_FILE_ORIGINS`.

## Scaling and memory

### Add workers

Each worker renders one document at a time, so the number of workers is the number of documents
rendered in parallel. Run about one worker per CPU you want to spend on rendering.

1. Create `compose.override.yaml` next to `compose.yaml`:

   ```yaml
   services:
     worker:
       deploy:
         replicas: 3
   ```

2. Run `docker compose up -d`.

Compose reads `compose.override.yaml` automatically, so the count survives upgrades. Do not use
`docker compose up -d --scale worker=3`: the next `docker compose up -d` goes back to one worker.

Workspaces share the workers fairly; see
[how workspaces share workers](/self-hosting/limits/#how-workspaces-share-workers).

### Memory limits

Every service has a memory limit, so one runaway process cannot take the server down. With one
worker the limits add up to about 6.8 GiB, each extra worker adds 2 GiB, and the optional
Prometheus adds 1 GiB. They are ceilings, so an idle installation uses much less.

A container that reaches its limit is killed and restarted, and `docker inspect <container>`
shows `"OOMKilled": true`. Raise its `*_MEMORY_LIMIT` setting in `.env`; the
[memory settings](/self-hosting/configuration/#memory-and-logs) list each one with its default.
The ones most likely to need it:

- **Worker** (`WORKER_MEMORY_LIMIT`): large documents. If you raise the
  [render memory caps](/self-hosting/configuration/#worker), raise this with them.
- **API** (`API_MEMORY_LIMIT`): importing large exported folders.
- **Redis** (`REDIS_MEMORY_LIMIT`): holds every render waiting to run and never drops one, so
  size it for the largest backlog you expect.

## Upgrade

Run these in the installation directory:

1. Back up the [database and file storage](#where-your-data-lives).
2. Download the new release's files as in [step 1](#1-download-the-release-files), which
   replaces `compose.yaml` and `env.example`. Keep `.env` and any `compose.override.yaml`.
3. Apply it:

   ```sh
   docker compose up -d --remove-orphans
   ```

4. Check the release notes for [one-off steps](#one-off-steps-for-older-installations).

Compose runs the database migrations, replaces the worker, and starts the new API once the new
worker is healthy. The API is unavailable for a few seconds. `--remove-orphans` removes services
the new release dropped. Templates, files, API keys, users and renders stay where they are, so
there is nothing to export or import.

:::caution
Always use the whole `compose.yaml` of one release. Never run an API and a worker from different
releases.
:::

### One-off steps for older installations

- **Releases with a `backup` service** kept backups in the `pdf-renderer_backups` volume, or in
  the directory named by `BACKUP_PATH`. Nothing deletes them any more: copy any you still need,
  then run `docker volume rm pdf-renderer_backups`.
- **Releases before imported and spreadsheet reports became templates** set those reports aside,
  and they are unavailable until you merge them. Run once after the upgrade:

  ```sh
  docker compose run --rm --no-deps api node dist/merge-reports.js
  ```

  Each report becomes a template with the same ID, name and folder, so API calls keep working.
  Its saved revisions become drafts and its published revision becomes version 1. Running it
  again is safe. If it exits with code 1, fix the report it names and run it again.

### What happens to work in flight

On an upgrade or `docker compose stop`:

- **The API** gives open requests 30 seconds to finish. A request still waiting for its PDF
  fails; retry it with the same [idempotency key](/guides/rendering/#idempotency-keys).
- **The worker** finishes its current render first, for up to `WORKER_CLOSE_GRACE_MS`
  (75 seconds). Compose kills it after `WORKER_STOP_GRACE_PERIOD` (90 seconds). A render cut off
  this way starts over automatically.

If you raise `RENDER_TIMEOUT_MS`, raise both grace periods with it, each at least 15 seconds above
the one before:

```sh
RENDER_TIMEOUT_MS=120000
WORKER_CLOSE_GRACE_MS=135000
WORKER_STOP_GRACE_PERIOD=150s
```

## What gets installed

`compose.yaml` runs these services. Their names are the ones `docker compose ps` and
`docker compose logs` use.

| Service      | What it does                                                                                       |
| ------------ | -------------------------------------------------------------------------------------------------- |
| `proxy`      | Caddy, the only public entry point. Serves Studio and the API on one address, over HTTPS.          |
| `api`        | The API, sign-in and file downloads. It also sends webhooks.                                       |
| `worker`     | Renders documents, one at a time per worker.                                                       |
| `sandbox`    | Runs template scripts and helpers, with no secrets and no network access.                          |
| `studio`     | The web app.                                                                                       |
| `postgres`   | PostgreSQL 18. Accounts, workspaces, templates, render history and the license state.              |
| `redis`      | Redis 8. Renders waiting to run, and rate-limit counters.                                          |
| `migrate`    | Runs the database migrations on every start, then exits.                                           |
| `prometheus` | Optional. Collects metrics and evaluates alert rules; see [monitoring](/self-hosting/monitoring/). |

## Where your data lives

Back up these, and restore them together:

| What                                                                | Holds                                                                                                                               |
| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| The PostgreSQL database (`postgres-data` volume)                    | Accounts, workspaces, templates and their versions, render history, API keys, webhooks, signing certificates and the license state. |
| File storage: the `storage-data` volume, or your S3 or Azure bucket | Uploaded files and rendered PDFs.                                                                                                   |
| `.env` and `compose.override.yaml`, in the installation directory   | Every secret, including `DATA_ENCRYPTION_KEY`, and your settings.                                                                   |

The other volumes hold nothing you need to keep, with one exception: `caddy-data` when you use
[the proxy's own certificate authority](#trust-the-proxys-certificate-authority). Keep it, or
every client must trust a new root certificate.

When you restore:

- Restore the database and the files from the same moment. The database records which files
  exist.
- Restore into the same release or a newer one, never an older one. A newer release brings the
  database up to date as it starts.
- A restored database is the same installation for your license; see
  [installations per license](/self-hosting/licensing/#installations-per-license).

### The data encryption key

`DATA_ENCRYPTION_KEY` in `.env` encrypts the secrets stored in the database, such as webhook
signing secrets and signing certificate keys, and cannot be recreated. Keep the copy of `.env`
apart from database copies: anyone with both can read those secrets.

A database restored without the key it was encrypted with still works, except that every
webhook's secret must be [rotated](/guides/webhooks/#rotate-the-secret) and every signing
certificate uploaded again under **Manage → Signing certificates**. To restore a database from
before a [key rotation](/self-hosting/configuration/#rotate-the-data-encryption-key), set the old
key as `DATA_ENCRYPTION_KEY_PREVIOUS` next to the current one.

## Next steps

- Create an API key under **Manage → API keys** and follow the [quickstart](/start/quickstart/).
- [Invite people](/self-hosting/users/#invite-someone), and turn on
  [email or Microsoft sign-in](/self-hosting/users/#choose-sign-in-methods) for them.
- [Turn on monitoring](/self-hosting/monitoring/) so you hear when something breaks.

---

# Licensing

Source: https://docs.typefold.dev/self-hosting/licensing/

A self-hosted installation renders documents only while it has a valid license key. Studio, the
API, templates, files and finished renders keep working without one.

## Get a key

- **Trial:** sign in to the hosted Typefold Studio, open **Account → Self-hosted license**,
  enter your **Company** and choose **Email my trial key**. The key is emailed to your account
  address and lasts 30 days. Asking again sends the same key.
- **Paid license:** buy a subscription from the vendor. The key is emailed after the first
  payment, and renewals extend the same key.

If the installation can never reach the internet, ask the vendor for an offline key instead.

## Install a key

1. Put the key in `.env` in the installation directory, as one line:

   ```sh
   LICENSE_KEY=eyJpZCI6IjNmMmMuLi4iLCJjb21wYW55IjoiQWNtZSBDb3JwIiwic2VydmVyIjoi...
   ```

2. Run `docker compose up -d`. The API reads the key only when it starts.
3. Check that Studio shows no banner saying rendering is disabled, or that `license.state` in the
   response of `curl https://pdf.example.com/v1/instance` is `active` or `trial`.

The installation checks its key with the vendor's license server every hour. Allow outbound HTTPS
from the API server to the hosted Typefold address, and keep the server clock synchronized.
Offline keys need neither.

To move from a trial to a paid license, replace `LICENSE_KEY` the same way.

## When rendering stops

API clients get [`403 LICENSE_REQUIRED`](/clients/http/#errors) and Studio shows a
banner. The license state tells you what to do:

| State     | Meaning                                                                                        | What to do                                                                                      |
| --------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `missing` | `LICENSE_KEY` is not set                                                                       | Set it in `.env` and run `docker compose up -d`                                                 |
| `pending` | The installation has not reached the license server yet, or not in the last 7 days             | Allow outbound HTTPS. Rendering resumes by itself.                                              |
| `invalid` | The key is damaged or revoked, is used by too many installations, or the server clock is wrong | Paste the key again and run `docker compose up -d`, fix the clock, or stop unused installations |
| `expired` | The trial ended, or the license ended more than 14 days ago                                    | Buy or renew, then install the new key if you got one                                           |
| `grace`   | The license ended less than 14 days ago. Rendering still works.                                | Renew now                                                                                       |

Lost your key? Ask the vendor to send it again, or request the trial again.

## Installations per license

One license runs a limited number of installations at the same time, 3 by default.
API and worker replicas that share one database are one installation, and a restored database
stays the same installation. A new server with an empty database is another one. An installation that has not checked in for
7 days stops counting.

---

# Limits and usage

Source: https://docs.typefold.dev/self-hosting/limits/

You control three kinds of limits: how much each workspace may render, how big one document may
be, and how many requests one address may send. Every limit and its default is in
[limits](/clients/limits/).

## Change a workspace's allowances

Only [platform administrators](/self-hosting/users/#platform-administrators) can change
allowances. Everyone else sees them read-only.

1. In Studio, choose the workspace in the workspace switcher.
2. Open **Manage → Render limits**.
3. Change **Maximum outstanding renders**, **Renders per minute**, **Documents per month**,
   **File storage (MB)** or **Test renders per day**, then choose **Save limits**. Leave the last
   three empty for unlimited, which is the default.

The change applies to the next request, with no restart. Lowering a value lets renders already
accepted finish, and refuses new ones until the workspace is below the new value. Each change is
recorded in the workspace's [audit history](/self-hosting/users/#audit-history). To change
allowances over HTTP, see the endpoints under
[platform administrators](/self-hosting/users/#platform-administrators).

Allowances decide what is accepted, not how fast it runs. If a workspace often gets `429`, raise
its allowances. If renders wait long before they start, [add workers](/self-hosting/install/#add-workers).
Which requests count is in [render allowances](/clients/limits/#render-allowances).

[Test renders](/guides/rendering/#test-renders) don't use these allowances. Every workspace has a
separate test allowance of 10 outstanding and 10 per minute, or its own allowance if lower. It
can't be raised.

## Suspend a workspace

On the same page, turn on **Suspended** and choose **Save limits**. The workspace then renders
nothing and refuses its API keys, while its members can still sign in, read and export its data.
Turn it off to restore the workspace. Both are recorded in its audit history.

## How workspaces share workers

Workers take turns between workspaces: every workspace's first waiting render runs before any
workspace's second. A workspace with a long backlog does not make the others wait behind all of
it. No capacity is reserved per workspace, so when the others are idle, one workspace can use
every worker.

## Change document limits

These apply to every render in every workspace. A document over one fails with
[`LIMIT_EXCEEDED`](/clients/http/#errors), except one that needs more than
`RENDER_MAX_HEAP_BYTES`, which fails with `RENDER_FAILED`.

| Setting                                                                  | What you can do        | Where                   |
| ------------------------------------------------------------------------ | ---------------------- | ----------------------- |
| `RENDER_TIMEOUT_MS` (render time)                                        | Set 1 second to 1 hour | `.env`                  |
| `RENDER_MAX_PAGES`, `RENDER_MAX_OUTPUT_BYTES`, `RENDER_MAX_INPUT_BYTES`  | Only lower them        | `compose.override.yaml` |
| `RENDER_MAX_WASM_BYTES`, `RENDER_MAX_HEAP_BYTES` (memory for one render) | Raise or lower them    | `compose.override.yaml` |

How to use `compose.override.yaml` is in
[advanced settings](/self-hosting/configuration/#advanced-settings). Then run
`docker compose up -d`.

- If you raise `RENDER_TIMEOUT_MS`, raise the worker's shutdown grace periods with it; see
  [what happens to work in flight](/self-hosting/install/#what-happens-to-work-in-flight).
- If you raise the memory settings, raise `WORKER_MEMORY_LIMIT` in `.env` too; see
  [worker settings](/self-hosting/configuration/#worker).

## Request rate limits

The limit on requests each client address may send to `/v1/` is `API_RATE_LIMIT_PER_MINUTE`, set
in `compose.override.yaml` (see [API settings](/self-hosting/configuration/#api)). Raise it when
many clients share one address, such as servers behind one NAT gateway.

If a CDN or load balancer sits in front of the server, all clients appear to share its address
until you set [`TRUSTED_PROXY_RANGES`](/self-hosting/install/#behind-a-cdn-or-load-balancer).
The other [request rates](/clients/limits/#request-rates), such as sign-in, imports and template
previews, cannot be changed.

## Usage

Each workspace has a daily usage record. It is kept after old renders are deleted, so it is the
long-term history of how much a workspace rendered.

| Counter            | Counts                                       |
| ------------------ | -------------------------------------------- |
| `rendersSucceeded` | Renders that produced a PDF                  |
| `rendersFailed`    | Renders that failed, including timeouts      |
| `rendersCancelled` | Renders cancelled while queued or processing |
| `pages`            | Pages in the PDFs of succeeded renders       |
| `outputBytes`      | Bytes of the PDFs of succeeded renders       |

A render is counted once, on the UTC day it finishes, test renders included. XLSX reports and
string renders create no render and are not counted.

### Read a workspace's usage

In Studio, open **Manage → Render limits**: **This month’s usage** shows the current month. Over
HTTP, call `GET /v1/usage` with an API key that has the `usage:read` scope:

```sh
curl "https://pdf.example.com/v1/usage?from=2026-09-01&to=2026-09-30" \
  -H "x-api-key: $API_KEY"
```

`from` and `to` are `YYYY-MM-DD` days, both included, and default to the current UTC month. A
range can span at most 366 days. The response has `totals` for the range and a `days` list that
leaves out days with no usage; see the [API reference](/reference/api/).

### Read every workspace's usage

Platform administrators can call `GET /v1/platform/usage` with their Studio session. It takes the
same `from` and `to`, and returns one page of workspaces with usage in the range, each with the
same counters. Paging is in the [API reference](/reference/api/).

---

# Monitoring

Source: https://docs.typefold.dev/self-hosting/monitoring/

Each release ships an optional [Prometheus](https://prometheus.io/docs/introduction/overview/)
with alert rules for a stopped service, renders that are not starting, an expiring license and
more.

## Turn on Prometheus

1. Add this line to `.env` in the installation directory:

   ```sh
   COMPOSE_PROFILES=monitoring
   ```

2. Run `docker compose up -d`.
3. The Prometheus UI listens only on the server's own `127.0.0.1`, port 9090. From your computer,
   open an SSH tunnel to the server, then browse to `http://localhost:9090/alerts`:

   ```sh
   ssh -L 9090:127.0.0.1:9090 you@pdf-server
   ```

The port and how long metrics are kept are
[monitoring settings](/self-hosting/configuration/#monitoring). Prometheus's memory limit is
[`MONITORING_MEMORY_LIMIT`](/self-hosting/configuration/#memory-and-logs).

## Get notified

The bundled Prometheus shows alerts only in its UI. To receive them, add
[Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/) as below, or
[use your own monitoring stack](#use-your-own-monitoring-stack). Put every file below in the
installation directory, next to `compose.yaml`.

1. Copy the bundled Prometheus configuration out of its container:

   ```sh
   docker compose cp prometheus:/etc/prometheus/prometheus.yml prometheus.yml
   ```

2. Add this block to the end of your copy of `prometheus.yml`:

   ```yaml
   alerting:
     alertmanagers:
       - static_configs:
           - targets: [alertmanager:9093]
   ```

3. Create `alertmanager.yml` to say where alerts go (email, chat, webhook). See
   [Alertmanager's configuration](https://prometheus.io/docs/alerting/latest/configuration/).
4. Add both to `compose.override.yaml` (create it if you do not have one). Pin the Alertmanager
   image to its current release, and mount any file `alertmanager.yml` reads, such as a password
   file.

   ```yaml
   services:
     prometheus:
       volumes:
         - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro

     alertmanager:
       image: prom/alertmanager:v0.34.1
       profiles: [monitoring]
       restart: unless-stopped
       volumes:
         - ./alertmanager.yml:/etc/alertmanager/alertmanager.yml:ro
       mem_limit: 256m
   ```

5. Run `docker compose up -d`, then send a test alert and check that it arrives:

   ```sh
   docker compose exec alertmanager amtool alert add TypefoldTest \
     --alertmanager.url=http://127.0.0.1:9093
   ```

:::caution
Your `prometheus.yml` replaces the bundled one. After each upgrade, compare it with the new
release's file and copy over anything new. To print the new file, use the `prometheus` image
named in the new `compose.yaml`:

```sh
docker run --rm --entrypoint cat <the prometheus image in compose.yaml> /etc/prometheus/prometheus.yml
```

:::

## Use your own monitoring stack

If you already run Prometheus elsewhere:

1. Scrape `/metrics` on port `9464` of every `api` replica and port `8081` of every `worker`
   replica. Name the scrape jobs `api` and `worker`: the "down" alerts look for those names.
2. Copy the alert rules out of the `prometheus` image named in `compose.yaml` (the bundled
   Prometheus does not need to run), and load them into your Prometheus:

   ```sh
   docker run --rm --entrypoint cat <the prometheus image in compose.yaml> /etc/prometheus/alerts.yml > alerts.yml
   ```

Neither port is published outside the Compose network, so your Prometheus must join that network,
or you publish the ports in `compose.override.yaml`.

## Health checks

The bundled Compose file already health-checks the `api` and `worker` services. You need these endpoints only for
a load balancer or orchestrator of your own. None needs a credential.

| Endpoint           | Service  | Answers `200` when                                | Use it for                              |
| ------------------ | -------- | ------------------------------------------------- | --------------------------------------- |
| `GET /health`      | `api`    | PostgreSQL and Redis both answer within 2 seconds | Readiness and load balancer checks      |
| `GET /health/live` | `api`    | The process can answer HTTP                       | Restart (liveness) checks               |
| `GET /health`      | `worker` | It is ready to render and Redis is connected      | The worker container's own health check |

Use `/health/live`, not `/health`, for restarts, or a database outage restarts every API replica
at once. The public address serves only the API's `/health`. The API's `/health/live` (port
`3000`) and the worker's `/health` (port `8081`) are reachable only inside the Compose network;
publish the ports in `compose.override.yaml` if your checks run elsewhere.

When the API cannot reach a dependency, `/health` answers `503` and names it (`database` or
`redis`):

```json
{ "status": "unavailable", "unavailable": ["database"] }
```

## Alert rules

| Alert                                 | Severity | Fires when                                                                                                                        |
| ------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `TypefoldApiDown`                     | critical | An `api` replica cannot be scraped for 2 minutes                                                                                  |
| `TypefoldNoApi`                       | critical | No `api` replica is up for 2 minutes                                                                                              |
| `TypefoldWorkerDown`                  | critical | A `worker` replica cannot be scraped for 2 minutes                                                                                |
| `TypefoldNoWorkers`                   | critical | No `worker` replica is up for 2 minutes                                                                                           |
| `TypefoldDependencyUnavailable`       | critical | The API cannot read PostgreSQL or Redis for 2 minutes                                                                             |
| `TypefoldRenderProcessCold`           | critical | A worker has not been ready to render for 5 minutes                                                                               |
| `TypefoldWarmUpFailing`               | warning  | A worker's render process failed to start 3 or more times in an hour                                                              |
| `TypefoldApiErrorRate`                | warning  | More than 5% of API requests return 5xx for 10 minutes                                                                            |
| `TypefoldApiSlow`                     | warning  | API p95 latency is above 2 seconds for 15 minutes, not counting requests that wait for a document                                 |
| `TypefoldQueueBacklog`                | warning  | The next render to start has waited more than 5 minutes                                                                           |
| `TypefoldRendersStuckQueued`          | critical | A render has been `queued` for more than 15 minutes                                                                               |
| `TypefoldRendersStuckProcessing`      | warning  | A render has been `processing` for more than 15 minutes                                                                           |
| `TypefoldRenderFailureRate`           | warning  | More than 10% of render attempts fail for 15 minutes with a retryable error or a timeout                                          |
| `TypefoldRenderProcessRestarts`       | warning  | A worker restarted its render process more than 10 times in 15 minutes after failures or timeouts                                 |
| `TypefoldBackgroundJobStale`          | warning  | Render repair, file cleanup, workspace cleanup or webhook delivery has not succeeded for 15 minutes, or render expiry for 3 hours |
| `TypefoldBackgroundJobNeverSucceeded` | warning  | A background job keeps failing and has not succeeded since the API started                                                        |
| `TypefoldWorkspaceCleanupStuck`       | warning  | A deleted workspace's data has not been purged after an hour                                                                      |
| `TypefoldLicenseRefusingRenders`      | critical | The license has refused renders for 5 minutes                                                                                     |
| `TypefoldLicenseCheckInFailing`       | warning  | The installation has not reached its license server for about 2 days; rendering stops within 5 days                               |
| `TypefoldLicenseExpiring`             | warning  | The license expires within 14 days                                                                                                |
| `TypefoldLicenseInGrace`              | warning  | The license has expired and is in its grace period                                                                                |

### What to do when an alert fires

| Alert                                                                         | First things to check                                                                   |
| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `TypefoldApiDown`, `TypefoldWorkerDown`, `TypefoldNoApi`, `TypefoldNoWorkers` | `docker compose ps`, then the logs of the service that is not running                   |
| `TypefoldQueueBacklog`                                                        | Workers are up; if they are all busy, [add workers](/self-hosting/install/#add-workers) |
| `TypefoldRendersStuckQueued`                                                  | The `api` logs for `Render queue operation failed.`                                     |
| `TypefoldRenderProcessCold`, `TypefoldWarmUpFailing`                          | The `worker` logs for `Render process warm-up failed.`                                  |
| `TypefoldBackgroundJobStale`, `TypefoldBackgroundJobNeverSucceeded`           | The `api` logs for the failing job's error                                              |
| `TypefoldWorkspaceCleanupStuck`                                               | Storage permissions, Object Lock or legal holds that block deleting files               |
| License alerts                                                                | [When rendering stops](/self-hosting/licensing/#when-rendering-stops)                   |

## Logs

Read a service's log with `docker compose logs`, such as `docker compose logs api --since 1h`.
[`LOG_MAX_SIZE` and `LOG_MAX_FILE`](/self-hosting/configuration/#memory-and-logs) set how much
Docker keeps. To send logs elsewhere, set `logging` for each service in `compose.override.yaml`.

Lines worth knowing:

| Log line                                             | Service  | Meaning                                                                                                |
| ---------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `Self-hosted setup required.`                        | `api`    | No platform administrator yet; the line carries the `setupToken`                                       |
| `Made ADMIN_EMAIL the first platform administrator.` | `api`    | First start with `ADMIN_EMAIL`; the line carries the address                                           |
| `DEPLOY_API_KEY created the deploy key.`             | `api`    | The deploy key was created, or `replaced` after its value changed                                      |
| `Neither email nor Microsoft sign-in is configured`  | `api`    | Only password accounts can sign in; see [sign-in methods](/self-hosting/users/#choose-sign-in-methods) |
| `Self-hosted license loaded.`                        | `api`    | The license state at startup                                                                           |
| `Self-hosted license state changed.`                 | `api`    | The license state changed after a check-in                                                             |
| `License check-in failed`                            | `api`    | The installation could not reach its license server                                                    |
| `Webhook secret encryption failed`                   | `api`    | Stored webhook secrets could not be encrypted with the current key                                     |
| `Signing key encryption failed`                      | `api`    | Stored signing certificate keys could not be encrypted with the current key                            |
| `Render process warm-up failed.`                     | `worker` | A worker could not get ready to render                                                                 |

## Metrics

The API serves `GET /metrics` on port `9464` and the worker on port `8081`. Neither is reachable
from outside the Compose network. Both also export the standard Node.js process metrics
(`process_*`, `nodejs_*`).

### API metrics

| Metric                                                   | Labels                           | Meaning                                                                                     |
| -------------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------- |
| `typefold_http_request_duration_seconds`                 | `method`, `route`, `status_code` | Request durations. `route` is the route pattern, such as `/v1/renders/:id`, or `unmatched`. |
| `typefold_background_job_runs_total`                     | `task`, `outcome`                | Background job runs. `outcome` is `succeeded` or `failed`.                                  |
| `typefold_background_job_last_success_timestamp_seconds` | `task`                           | When each background job last succeeded on this replica.                                    |

The background jobs (`task`) are `asset_cleanup`, `render_repair`, `render_retention`,
`workspace_cleanup`, `webhook_dispatch`, `webhook_retention`, `webhook_secret_encryption`,
`signing_key_encryption` and `license_check_in`.

These gauges describe the whole installation, so every API replica reports the same value.
Combine replicas with `max()`, not `sum()`.

| Metric                                           | Labels   | Meaning                                                                            |
| ------------------------------------------------ | -------- | ---------------------------------------------------------------------------------- |
| `typefold_monitoring_source_up`                  | `source` | `1` if the scrape could read the `database` or the `queue` (Redis)                 |
| `typefold_queue_jobs`                            | `state`  | Render jobs in Redis by state: `waiting`, `active`, `delayed`, `failed`            |
| `typefold_queue_oldest_waiting_age_seconds`      |          | How long the next render to start has waited                                       |
| `typefold_renders_unfinished`                    | `state`  | Renders that are `queued` or `processing`                                          |
| `typefold_render_oldest_queued_age_seconds`      |          | Age of the oldest queued render                                                    |
| `typefold_render_oldest_processing_age_seconds`  |          | Time since the longest-running processing render last changed                      |
| `typefold_workspace_deletions_pending`           |          | Workspace cleanups not yet finished                                                |
| `typefold_workspace_deletion_oldest_age_seconds` |          | Age of the oldest unfinished workspace cleanup                                     |
| `typefold_license_state`                         | `state`  | `1` for the current [license state](/self-hosting/licensing/#when-rendering-stops) |
| `typefold_license_renew_by_timestamp_seconds`    |          | When rendering stops unless a license check-in succeeds (`0` if unset)             |
| `typefold_license_expires_timestamp_seconds`     |          | When the license expires (`0` if unset)                                            |

### Worker metrics

| Metric                                         | Labels    | Meaning                                                  |
| ---------------------------------------------- | --------- | -------------------------------------------------------- |
| `typefold_worker_job_duration_seconds`         | `outcome` | Render durations, by outcome (below)                     |
| `typefold_worker_child_replacements_total`     | `reason`  | Render process restarts: `recycle`, `failure`, `timeout` |
| `typefold_worker_child_warm_up_failures_total` |           | Render processes that failed to start                    |
| `typefold_worker_child_warm`                   |           | `1` while the worker is ready to render                  |

`outcome` is `succeeded`, `ignored` (cancelled or already finished), `retryable` (a failure that
may succeed on retry), `final` (a failure retrying cannot fix, usually an invalid document or a
limit) or `timeout` (longer than [`RENDER_TIMEOUT_MS`](/self-hosting/configuration/#rendering)).

A `recycle` restart is routine: the worker restarts its render process after a large document to
free memory. `failure` and `timeout` restarts point to problems.

---

# Users and sign-in

Source: https://docs.typefold.dev/self-hosting/users/

Sign-in settings go in `.env` next to `compose.yaml`. Everything else on this page is done in
Studio.

## Choose sign-in methods

Studio offers every method you turn on, and you can combine them. Without email codes or
Microsoft, only password accounts can sign in.

| Method      | What people get                                                           |
| ----------- | ------------------------------------------------------------------------- |
| Email codes | A one-time code by email. Invitations are emailed too.                    |
| Microsoft   | **Sign in with Microsoft** for one Microsoft Entra ID tenant.             |
| Passwords   | A password a platform administrator sets for them. Always on, no sign-up. |

The settings themselves are listed under [configuration](/self-hosting/configuration/#sign-in).

### Email codes

Emails are sent through [Resend](https://resend.com).

1. In Resend, verify a sending domain and create an API key.
2. In `.env`, set `RESEND_API_KEY` to that key and `AUTH_EMAIL_FROM` to a sender address on that
   domain.
3. Run `docker compose up -d`.

A code is valid for five minutes and allows three wrong attempts. If Resend cannot send it,
requesting a code answers `503 EMAIL_DELIVERY_UNAVAILABLE`.

### Microsoft Entra ID

Someone allowed to register applications in your Entra tenant does this:

1. In the Microsoft Entra admin center, open **App registrations** and choose
   **New registration**.
2. Pick **Accounts in this organizational directory only**.
3. Add a **Web** redirect URI of `<PUBLIC_URL>/api/auth/callback/microsoft-entra-id`, such as
   `https://pdf.example.com/api/auth/callback/microsoft-entra-id`.
4. Under **Certificates & secrets**, create a client secret.
5. In `.env`, set `ENTRA_TENANT_ID` to the directory (tenant) ID, `ENTRA_CLIENT_ID` to the
   application (client) ID and `ENTRA_CLIENT_SECRET` to the secret's value.
6. Run `docker compose up -d`.

The default `openid`, `profile` and `email` permissions are enough. The server needs outbound
HTTPS to `login.microsoftonline.com` and `graph.microsoft.com`.

Anyone in the tenant can sign in, but sees only the workspaces they are invited to. An existing
account with the same email address is reused. Entra's own MFA and conditional access apply;
Studio's two-factor authentication does not.

:::caution
Entra client secrets expire. Create a new one and update `ENTRA_CLIENT_SECRET` before the old one
expires, or Microsoft sign-in stops working.
:::

### Passwords

Only a platform administrator can give someone a password:

1. In Studio, open **Manage → Team** and click **Set password**.
2. Enter the person's email address and click **Set password**. Studio shows a generated password
   once. Send it to the person over a channel you trust.
3. [Invite](#invite-someone) the person to a workspace.

**Set password** creates the account if needed and signs the person out everywhere. Setting it
again is how you reset a password: there is no "forgot password" email. People change their own
password under **Account → Account security**. Passwords are at least 12 characters.

## Invite someone

Owners and admins invite people in Studio:

1. Open **Manage → Team** and click **Invite teammate**.
2. Enter the person's email and a role: `member`, `editor` (**Content editor**), `admin` or
   `owner`. Only owners can invite an owner.
3. Click **Send invitation**, or **Add invitation** when email codes are off.

The person must sign in with exactly the invited address. Without [email codes](#email-codes), no
email is sent: tell the person to sign in and accept under **Account → Your invitations**.
Someone with no way to sign in yet needs a [password](#passwords) first.

On the **Team** page, select people to **Change role**, **Cancel invitation** or **Remove from
workspace**. With email codes on, **Resend** sends a pending invitation again.

## Workspaces and roles

Access has two separate layers:

- **Workspace roles** (`owner`, `admin`, `member`, `editor`) decide what someone can do in one workspace. A
  workspace holds its own templates, files, renders, API keys, webhooks, [signing
  certificates](/guides/pdf-standards/#digital-signatures), render limits and audit log. A person
  can be in several workspaces with a different role in each. What each role can do is in
  [roles](/clients/http/#roles).
- **Platform administrators** run the installation: they create workspaces, set
  [render limits](/self-hosting/limits/), set passwords and grant platform access. Being a
  workspace owner does not make someone a platform administrator.

Installations are invite-only: signing in gives someone no workspace until they are invited.
Whoever creates a workspace becomes its owner, and a workspace always keeps at least one owner.
Workspaces cannot be deleted.

## Platform administrators

Platform administrators use the same Studio, with more reach:

- The workspace switcher lists every workspace. Choosing one gives full access to it without
  joining it. **Create workspace** at the bottom of the switcher adds a new one.
- **Manage → Render limits** lets them change the workspace's
  [allowances](/self-hosting/limits/#change-a-workspaces-allowances).
- **Manage → Team** shows who has platform access. There they set passwords, and select a person
  to **Grant platform admin** or **Revoke platform admin**.

The person must already have an account: they have signed in once, or you set them a password.
The last platform administrator cannot be revoked; grant another one first.

The same actions are available over HTTP with a platform administrator's Studio session. API keys
are refused, whatever their scopes. Request and response schemas are in the
[API reference](/reference/api/).

| Method   | Endpoint                        | What it does                                                        |
| -------- | ------------------------------- | ------------------------------------------------------------------- |
| `GET`    | `/v1/platform-admins`           | List platform administrators                                        |
| `POST`   | `/v1/platform-admins`           | Grant access: `{ "email": "..." }` or `{ "userId": "..." }`         |
| `DELETE` | `/v1/platform-admins/{id}`      | Revoke access, by user ID                                           |
| `POST`   | `/v1/password-accounts`         | Set a generated password: `{ "email": "..." }`                      |
| `GET`    | `/v1/platform/workspaces`       | List workspaces with their allowances                               |
| `GET`    | `/v1/platform/workspaces/{id}`  | Read one workspace and its allowances                               |
| `PUT`    | `/v1/companies/{id}/allowances` | Replace a workspace's allowances; `{id}` is the workspace ID        |
| `GET`    | `/v1/platform/usage`            | Usage of every workspace (see [usage](/self-hosting/limits/#usage)) |

## Set up from configuration

A deployment tool can set up a new installation instead of a person, so it can deploy templates
as soon as it starts. Add these to `.env` before the first start (each is described under
[automated setup](/self-hosting/configuration/#automated-setup)):

```sh
ADMIN_EMAIL=ops@example.com
DEPLOY_WORKSPACE=Templates
DEPLOY_API_KEY=pdf_…   # generate with: echo "pdf_$(openssl rand -hex 32)"
```

On a start while the installation has no platform administrator:

- The `ADMIN_EMAIL` account becomes the first platform administrator, and no setup token is
  printed. The account is created if needed. That person signs in with an email code, Microsoft,
  or a password from [`password-account.js`](#recover-a-locked-out-administrator).
- A workspace named `DEPLOY_WORKSPACE` is created, owned by that account.

After that, `ADMIN_EMAIL` is ignored. The API logs the address it made administrator. If it was
mistyped, give that account a password with `password-account.js`, sign in as it, grant the right
address platform access, then revoke the wrong one.

### The deploy key

The **deploy key** is an API key the server creates from `DEPLOY_API_KEY`, so your deployment
tool can import and publish templates (see [deploy across environments](/guides/environments/)).
Studio lists it as **Deploy key (DEPLOY_API_KEY)**. Its scopes and lifetime are in
[deploy key](/clients/http/#deploy-key). The tool sends the value as its `x-api-key` header.

An installation has at most one deploy key. On every start the API compares `DEPLOY_API_KEY`
with it:

| `DEPLOY_API_KEY` is      | What happens                                                                                                                     |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| Set, no deploy key yet   | The key is created in the workspace named by `DEPLOY_WORKSPACE`. The API refuses to start unless it names exactly one workspace. |
| The same value as before | Nothing changes, even if the key was revoked.                                                                                    |
| A new value              | The key is replaced in the same workspace and the old value stops working.                                                       |
| Removed                  | The key keeps working. Revoke it in Studio if it should stop.                                                                    |

To add a deploy key to an installation that is already set up, set `DEPLOY_API_KEY`, and set
`DEPLOY_WORKSPACE` to the name of an existing workspace.

If the key leaks, revoke it under **Manage → API keys**. It stays revoked until you set a new
value in `.env`. Give each environment its own value.

## If the setup token does not work

The first person to enter the **setup token** from the API's log becomes the first platform
administrator, as in
[step 6 of the install guide](/self-hosting/install/#6-become-the-first-platform-administrator).

- **The token scrolled out of the log.** It stays the same until setup is done. Run
  `docker compose restart api`, then `docker compose logs api | grep setupToken`.
- **The token stopped working.** It is derived from `BETTER_AUTH_SECRET`, so changing that
  setting changes the token. Read it from the log again.

Once any platform administrator exists, setup closes for good and the token is no longer printed.
Treat the token as a secret until then.

## Recover a locked-out administrator

On the server, in the installation directory, give the account a new generated password:

```sh
docker compose exec api node dist/password-account.js admin@example.com
```

When another platform administrator can sign in, use [**Set password**](#passwords) in Studio
instead.

## Audit history

Each workspace has its own append-only audit log of security-relevant changes. Read it in Studio
under **Manage → Audit log**, where you can filter it and click **Export CSV**, or with
`GET /v1/audit-events` and the `audit:read` scope:

```sh
curl "https://pdf.example.com/v1/audit-events?action=template.published&limit=1" \
  -H "x-api-key: $API_KEY"
```

```json
{
  "items": [
    {
      "id": "0b6a3c1e-5d2f-4c1a-9a3e-2f1d7c8b9e01",
      "actorType": "user",
      "actorName": "Ada Lovelace",
      "action": "template.published",
      "resourceType": "template",
      "resourceName": "Invoice",
      "metadata": { "number": 7 },
      "createdAt": "2026-10-07T14:21:08.512Z"
    }
  ],
  "nextCursor": "0b6a3c1e-5d2f-4c1a-9a3e-2f1d7c8b9e01"
}
```

Each event also has `actorId`, `actorEmail`, `resourceId` and `requestId`. `metadata` differs per
action. `GET /v1/audit-events/{id}` reads one event. The list is newest first and
[paged](/clients/http/#pagination) with `limit` and `cursor`. It also takes these filters:

| Query parameter | Description                                         |
| --------------- | --------------------------------------------------- |
| `action`        | One action, such as `api_key.revoked`               |
| `actorType`     | `user`, `api_key` or `system`                       |
| `actorId`       | The user or API key that acted                      |
| `resourceType`  | Such as `template`, `api_key` or `webhook_endpoint` |
| `resourceId`    | One resource                                        |
| `from`, `to`    | ISO 8601 date-times bounding `createdAt`            |

### Recorded actions

| Area                        | Recorded actions                                                                                                                                                                                                                                                                                                                                               |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Templates                   | `template.created`, `template.draft_saved`, `template.content_updated`, `template.published`, `template.renamed`, `template.moved`, `template.imported`, `template.deleted`                                                                                                                                                                                    |
| Workspace files and folders | `workspace_entity.created`, `workspace_entity.saved`, `workspace_entity.renamed`, `workspace_entity.moved`, `workspace_entity.scoped`, `workspace_entity.imported`, `workspace_folder.created`, `workspace_folder.renamed`, `workspace_folder.moved`, `workspace_folder.copied`, `workspace_folder.deleted`, `workspace_folder.imported`, `workspace.imported` |
| Assets                      | `asset.created`, `asset.deleted`                                                                                                                                                                                                                                                                                                                               |
| API keys                    | `api_key.created`, `api_key.rotated`, `api_key.revoked`, `api_key.deleted`                                                                                                                                                                                                                                                                                     |
| Webhooks                    | `webhook_endpoint.created`, `webhook_endpoint.updated`, `webhook_endpoint.secret_rotated`, `webhook_endpoint.deleted`                                                                                                                                                                                                                                          |
| Signing certificates        | `signing_certificate.created`, `signing_certificate.deleted`                                                                                                                                                                                                                                                                                                   |
| Team                        | `invitation.created`, `invitation.accepted`, `invitation.rejected`, `invitation.canceled`, `member.role_updated`, `member.removed`, `member.left`                                                                                                                                                                                                              |
| Limits                      | `company.allowances.updated`, with the values before and after; `company.suspended` and `company.unsuspended`                                                                                                                                                                                                                                                  |

Changes the server makes from `DEPLOY_API_KEY` appear with the actor type `system`. Renders are
not audit events. Granting and revoking platform administrators and setting passwords belong to no
workspace, so they appear in no workspace's log.

---

# Data Processing Terms

Source: https://docs.typefold.dev/legal/dpa/

_Last updated: 20 October 2026_

These terms are part of the [Terms of Service](/legal/terms/) and form the data processing
agreement required by Article 28 of the GDPR. They apply when your content in the hosted
service contains personal data, such as names and addresses on invoices. You accept them by
accepting the Terms of Service; nothing needs to be signed.

## Roles

You (the customer) are the controller of personal data in your content. Runecode OÜ is the
processor. Our own account and log data is covered by the [Privacy Policy](/legal/privacy/),
where we are the controller.

## What we process

- **Data:** whatever your templates, assets and render data contain. You decide what that is.
  If it includes special categories of personal data (such as health or genetic data), you make
  sure you have a legal basis for it.
- **People:** typically your customers, employees and business contacts.
- **Purpose:** storing your content and rendering documents from it, as you instruct through
  Studio and the API.
- **Duration:** as long as you use the service, then until deletion as described below.

## Our commitments

We:

- process the data only on your documented instructions, which are your use of the service and
  these terms; if the law requires other processing, we tell you first unless that law forbids
  it; we tell you if an instruction seems unlawful;
- make sure everyone with access to it is bound to confidentiality;
- protect it with the measures listed below;
- use only the subprocessors listed below, under contracts with the same protections, and
  remain responsible for them;
- help you answer requests from people exercising their rights, and with security, breach
  notification, impact assessments and consultations, as far as our part allows;
- tell you without undue delay, and within 48 hours where we can, after we become aware of a
  breach affecting your data;
- when you stop using the service, return or delete the data, as you choose, as described below;
- give you the information needed to show these terms are met, and allow audits by you or an
  auditor you appoint, with reasonable notice, at your cost, and no more than once a year unless
  there has been a breach.

## Security measures

- Encrypted connections (HTTPS) for all access to the service.
- Each workspace's data kept apart from every other workspace's, enforced on every request.
- Access by role within a workspace; API keys scoped to one workspace.
- Templates' scripts run in an isolated sandbox for each render.
- Optional two-factor sign-in.
- Encrypted, off-server database backups, with off-site copies at a second provider, and
  versioned file storage.
- Operating system security updates applied automatically, and application security fixes
  deployed promptly; access to servers limited to named administrators with SSH keys.

## Subprocessors

| Subprocessor                 | What for                                                                | Where            |
| ---------------------------- | ----------------------------------------------------------------------- | ---------------- |
| netcup GmbH                  | The servers that run the service and its database                       | Austria          |
| Hetzner Online GmbH          | File storage and backups                                                | Germany          |
| Backblaze, Inc.              | Off-site copies of the backups (the database encrypted) and of files    | EU (Netherlands) |
| Cloudflare, Inc.             | Passing connections to the service on to our servers; stores no content | Global network   |
| Resend                       | Email delivery (invitations only, not your content)                     | EU (Ireland)     |
| Anthropic                    | Only when you use an AI feature: the file you give it                   | United States    |
| Functional Software (Sentry) | Error tracking: error messages and stack traces, without your content   | EU (Germany)     |

Billing and payment data is handled by Polar Software, Inc., which sells paid plans as merchant
of record. It is not part of your content, and Polar is not a subprocessor of it: Polar receives
only the ID of the workspace a purchase is for. Billing data is covered by the
[Privacy Policy](/legal/privacy/).

We tell you at least 30 days before adding or replacing a subprocessor. If you object on
reasonable data protection grounds and we can't resolve it, you can end your use of the service.

Transfers outside the EU rely on the EU–US Data Privacy Framework or the European Commission's
Standard Contractual Clauses.

## Deletion

Finished renders, with their input data and documents, are deleted 30 days after they are
created.
Assets are deleted when you delete them. A deleted template disappears from Studio and the API,
and its published versions are deleted 30 days later; its draft history stays until you shut
the workspace down. When
you shut down a workspace, its content is removed from the database at once and its files
shortly after. Copies in backups and earlier file versions expire within 30 days. If a backup is
ever restored, deleted workspaces and accounts are deleted again.

When you stop using the service, you choose whether we return or delete your data. To get it
back, export your templates and download your documents in Studio or through the API, or ask us
at privacy@runecode.ee and we send you an export. Shutting down the workspace is your choice
to delete it.

## Contact

Runecode OÜ, Iirise tn 3-3, Tartu linn, Tartu maakond, 51011, Estonia, privacy@runecode.ee

---

# Privacy Policy

Source: https://docs.typefold.dev/legal/privacy/

_Last updated: 20 October 2026_

This policy covers the hosted Typefold service at `app.typefold.dev` and this website. If you
run Typefold on your own servers, your installation sends us nothing beyond license checks, and
this policy covers only those.

## Who we are

Runecode OÜ (registry code 17627039), Iirise tn 3-3, Tartu linn, Tartu maakond, 51011, Estonia, is the controller for the personal data described here. Contact us
at privacy@runecode.ee.

For the content you put into the service, such as templates and the data you render, your
organization is the controller and we process it on its behalf, under our
[Data Processing Terms](/legal/dpa/).

## What we collect and why

| Data                                                                    | Why                                                                                            | Legal basis                   |
| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------- |
| Email address, name, and your workspace memberships and roles           | To create your account, sign you in with email codes, and send invitations and service notices | Contract                      |
| Two-factor secrets and recovery codes, if you turn them on              | To protect your account                                                                        | Contract                      |
| Sessions, with the IP address and browser they came from                | To keep you signed in and protect your account                                                 | Contract                      |
| A record of actions in your workspace (who did what, when)              | So workspace owners can see changes, and to investigate problems                               | Legitimate interest           |
| Usage counts per workspace (documents rendered, storage used)           | To apply plan limits                                                                           | Contract                      |
| Server logs, with IP addresses and request details                      | To run, secure and fix the service, and to stop abuse                                          | Legitimate interest           |
| Company name and email, if you start a self-hosted license or trial     | To issue and check the license                                                                 | Contract                      |
| Your workspace's plan, and the ID Polar gives its subscription          | To give a paid plan its limits                                                                 | Contract                      |
| Your content: templates, assets, render data and the documents produced | To provide the service                                                                         | On your organization's behalf |

We do not sell personal data, do not use it for advertising, and do not use your content to
train AI models.

## Cookies

Studio uses cookies only for signing in: one keeps you signed in, and short-lived ones protect
two-factor and Microsoft sign-in. They are needed for the service to work, so we don't ask for
consent. Studio also saves your theme and editor layout in your browser's local storage.
We use no analytics or advertising cookies.

## Who else processes it

We use these providers to run the service. Each processes data only on our instructions.

| Provider                     | What for                                                                                              | Where            |
| ---------------------------- | ----------------------------------------------------------------------------------------------------- | ---------------- |
| netcup GmbH                  | The servers that run the service and its database                                                     | Austria          |
| Hetzner Online GmbH          | File storage and backups                                                                              | Germany          |
| Backblaze, Inc.              | Off-site copies of the backups (the database encrypted) and of files                                  | EU (Netherlands) |
| Resend                       | Sending sign-in codes, invitations and notices                                                        | EU (Ireland)     |
| Cloudflare                   | Serving this website, and passing connections to the service on to our servers, without storing them  | Global network   |
| Anthropic                    | Only when you use an AI feature, such as creating a template from a PDF: the file you give it         | United States    |
| Functional Software (Sentry) | Error tracking: error messages, stack traces and page paths, without user details or request contents | EU (Germany)     |

Where a provider is outside the EU, we rely on the EU–US Data Privacy Framework or the European
Commission's Standard Contractual Clauses. We may also disclose data when the law requires it.

**Payments.** Paid plans and self-hosted licenses are sold by Polar Software, Inc. (United
States) as merchant of record. When you buy, you give your name, email, billing address, tax ID
and card details to Polar. Polar processes them on our behalf to complete and bill the sale,
under a data processing agreement with the European Commission's Standard Contractual Clauses,
and for its own purposes, such as fraud prevention and its tax and legal obligations, under
[its own privacy policy](https://polar.sh/legal/privacy). We see your name, email, billing
address and what you bought, and we never see your card details. We tell Polar which workspace a
purchase is for, by an ID; Polar gets none of your content.

## How long we keep it

- **Account data:** until you delete your account.
- **Workspace content:** until you delete it or shut down the workspace. A deleted template's
  published versions are deleted 30 days after the template; its draft history stays until the
  workspace is shut down.
- **Renders:** once a render has finished, its input data and the document produced are deleted
  30 days after the render was created.
- **Server logs:** 30 days.
- **Emails we send you:** our email provider keeps them for 30 days, also after you delete your
  account.
- **Self-hosted licenses:** the company name and email stay with the license after you delete
  your account, for as long as the license can be used. Ask us to delete them sooner.
- **Purchases:** Polar keeps invoices and payment records for as long as tax law requires.
- **Backups:** database backups and earlier versions of files are kept for 30 days. Data you
  delete stays in them until they expire. If a backup is ever restored, deleted accounts and
  workspaces are deleted again.

## Your rights

You can ask us to access, correct, delete, restrict or port your personal data, and you can
object to processing based on legitimate interest. You can delete your account yourself in
Studio under Account security. For anything else, email privacy@runecode.ee. We answer within
one month.

If your data is in a customer's workspace content, contact that customer first; we help them
answer.

You can also complain to a data protection authority, such as the Estonian Data Protection Inspectorate (Andmekaitse Inspektsioon, [www.aki.ee](https://www.aki.ee)) or the one
where you live.

## Security

Connections to the service use HTTPS. Database backups are encrypted. Access keys you save for a
storage destination are encrypted at rest, used only to upload your workspace's renders to it,
never shown again, and deleted with the destination or the workspace. Each workspace's data is kept apart from
other workspaces'. If a breach affects your personal data, we tell you and the authorities as
the law requires.

## Changes

We tell you by email or in Studio before a change to this policy that affects you.

---

# Security

Source: https://docs.typefold.dev/legal/security/

This page covers the hosted service at `app.typefold.dev`, run by Runecode OÜ in Estonia. If
you run Typefold on your own servers, your data stays there and your own measures apply.

Typefold has no SOC 2, ISO 27001 or HIPAA certification. For a security review, use the
[filled-in security questionnaire](/trust/typefold-security-questionnaire.csv) and the
[Data Processing Terms](/legal/dpa/).

## Where your data is

| What                                                 | Where                                                                     |
| ---------------------------------------------------- | ------------------------------------------------------------------------- |
| The service and its database                         | netcup, Austria                                                           |
| Your files                                           | Hetzner, Germany                                                          |
| Backups                                              | Hetzner, Germany, at a different provider than the servers                |
| Off-site copies of the backups and files             | Backblaze, EU                                                             |
| A file you give an AI feature, only when you use one | Anthropic, United States                                                  |
| Connections to the service                           | Cloudflare passes them on to the servers and stores none of their content |
| This website                                         | Cloudflare. It holds no customer data.                                    |

Every provider that processes your data is in the
[subprocessor list](/legal/dpa/#subprocessors). We tell you at least 30 days before adding or
replacing one.

## Encryption

- All connections to the service use HTTPS, and browsers are told to use nothing else.
- Signing certificates' private keys, PDF passwords and webhook signing secrets are encrypted
  in the database with AES-256-GCM.
- Storage destination access keys you save are encrypted in the database the same way, used only
  to upload your workspace's renders, never shown again, and deleted with the destination or the
  workspace.
- API keys are stored only as hashes; nobody can read a key back after it is created.
- Database backups are encrypted before they leave the server.
- Templates, render data and documents are not encrypted by the application. Access control
  protects them, as below.

## Access

- Each workspace's data is kept apart from every other workspace's, checked on every request.
- Members have roles within a workspace, and each API key works in one workspace only.
- You sign in with a code sent to your email. Two-factor sign-in with an authenticator app is
  available to every account.
- Template scripts run in an isolated sandbox without network access, a new one for each
  render.
- Our servers accept SSH keys only, with password and root sign-in turned off, behind a
  firewall that allows only SSH and web traffic.
- Our administrators can open any workspace, with a workspace admin's rights, to run and
  support the service. Two-factor sign-in is not yet required for their accounts. That is in
  progress.

## Backups

- Every change to the database is backed up within five minutes, and a full backup is taken
  every night and before every upgrade.
- The database can be restored to any moment of the last 24 days.
- Every week, the latest backup is restored automatically to check that it works.
- Every night, the backups and your files are copied to a second provider, where nobody can
  delete them for 25 days, us included.
- Files keep their earlier versions, so a deleted or overwritten file can be restored.

## How long we keep data

- **Renders:** the input data and the document are deleted 30 days after the render was created.
- **Deleted templates:** their published versions are deleted 30 days later.
- **Workspaces you shut down:** their content is removed from the database at once, and their
  files shortly after.
- **Server logs:** 30 days.
- **Backups and earlier file versions:** 30 days at most. If a backup is ever restored, accounts
  and workspaces deleted after it was taken are deleted again.

The [Privacy Policy](/legal/privacy/#how-long-we-keep-it) has the full list.

## Running the service

- Operating system security updates install automatically.
- Errors are tracked in Sentry's EU region, without user details or request contents.
- Alerts reach us when the service, its disk or memory, or a backup fails.
- Service availability is shown on the [status page](https://status.typefold.dev), and paid
  plans have an [uptime commitment](/legal/sla/).

## Incidents and reports

If a breach affects your data, we tell you without undue delay, and within 48 hours where we
can, as the [Data Processing Terms](/legal/dpa/#our-commitments) state.

To report a security problem, email privacy@runecode.ee.

---

# Service Level Agreement

Source: https://docs.typefold.dev/legal/sla/

_Last updated: 20 October 2026_

This agreement is part of the [Terms of Service](/legal/terms/). It applies to workspaces on a
paid plan of the hosted service. It does not cover the Free plan or self-hosted installations.

## Uptime commitment

The service will be available at least **99.5%** of each calendar month.

The service counts as available when the API at `app.typefold.dev` answers requests. Our
external monitoring checks it every 3 minutes from more than one region, and the public status
page at [status.typefold.dev](https://status.typefold.dev) records every outage. Downtime runs
from the first failed check to the first successful one after it.

Monthly uptime is the minutes in the month, minus the minutes of downtime, as a percentage of
the minutes in the month. Excluded time, below, does not count as downtime.

## What is excluded

- Maintenance announced on the status page at least 48 hours in advance.
- Outages caused by you, your content or your systems, or by use that breaks the Terms of
  Service.
- A workspace that is suspended, or that has reached a plan limit.
- Failures of third-party providers outside our direct control, such as content delivery,
  DNS, network and cloud providers, and general internet or ISP problems.
- Third-party services you connect to the service, such as your own storage destinations or
  webhook endpoints.
- Events beyond our reasonable control, such as natural disasters, war, or the failure of a
  public utility.
- Features we label as preview or beta.

## Service credits

If monthly uptime falls below the commitment, you can claim a credit on that month's plan fee:

| Monthly uptime | Credit |
| -------------- | ------ |
| Below 99.5%    | 10%    |
| Below 99.0%    | 25%    |

For a yearly plan, the month's fee is one twelfth of the yearly price.

Credits for a month add up to at most 25% of that month's plan fee.

To claim, email legal@runecode.ee within 30 days after the end of the month, with your
workspace name, the month, and the times of the downtime you saw. We confirm the downtime
against our monitoring and the status page. We pay the credit as a partial refund of that month's
payment, through Polar, our merchant of record, to the payment method you used. Your plan must
be paid up to date to claim.

Service credits are your only remedy for downtime, except where the law does not allow this to
be limited, such as for gross negligence or wilful misconduct.

---

# Terms of Service

Source: https://docs.typefold.dev/legal/terms/

_Last updated: 20 October 2026_

These terms are an agreement between you and Runecode OÜ, registry code 17627039, Iirise tn 3-3, Tartu linn, Tartu maakond, 51011, Estonia ("Typefold", "we"). They
cover the hosted service at `app.typefold.dev`, its API and Studio (the "service"). By creating
an account or using the service, you accept them. If you use it for a company, you accept them
for that company and confirm you may do so.

The service is for businesses and professionals, not consumers. You must be at least 18.

## Your account

- Keep your sign-in details and API keys secret. You are responsible for what happens under your
  account and your workspace's API keys.
- Give us a working email address. We send sign-in codes and service notices to it.
- One person, one account. Workspace owners decide who joins their workspace and with which role.

## Your content

Your templates, assets, data you send for rendering, and the documents we produce for you are
your content. You keep all rights to it. You give us the rights we need to store, process and
render it, only to run the service for you.

You are responsible for your content and for having the right to use it, including fonts,
images and any personal data in it. When your content contains personal data, our
[Data Processing Terms](/legal/dpa/) apply.

## Acceptable use

Do not use the service to:

- break the law, or infringe anyone's rights;
- create documents meant to deceive, such as forged invoices, certificates or identity papers;
- send spam or malware, or attack the service or other customers;
- get around plan limits, for example by opening several Free workspaces;
- probe, scan or load-test the service without our written permission;
- resell the service as a document rendering service of your own without our agreement.

We may suspend a workspace that breaks these rules or puts the service at risk. Where we can,
we tell you first and give you a chance to fix it.

## Plans and limits

The Free plan currently includes 100 documents a month and 100 MB of storage. Studio shows how
much you have used. When you reach the monthly document limit, rendering stops until the next month. When
you reach the storage limit, uploads stop until you delete files. Moving to a plan with more room
lifts either limit. Test renders are free and carry a watermark.

We may change what the Free plan includes. We tell you before a change that takes something
away.

## Paid plans

- **Who sells them:** paid plans are sold by our reseller, Polar Software, Inc. ("Polar"),
  as merchant of record. You buy from Polar under [Polar's terms of purchase](https://polar.sh/legal/checkout-buyer-terms), and Polar charges
  you, adds VAT where it applies, and sends your invoices and receipts. These terms still govern
  your use of the service.
- **Price and renewal:** the price is shown in Studio, and with any VAT at checkout. A plan
  renews automatically at the end of each billing period until you cancel it.
- **Limits:** a paid plan's limits apply as soon as it is paid for. When you reach a limit,
  rendering or uploads stop, as on the Free plan, until the next month, a larger plan or
  deleted files.
- **Overage:** a workspace owner or administrator can turn on overage in Studio. Documents past
  the plan's monthly limit are then rendered and charged per 1,000 documents at the price shown in
  Studio, with the plan's next invoice. Rendering stops when the month's overage reaches the spend
  cap you set. Overage is off until you turn it on, and on the Free plan rendering always stops
  at the limit.
- **Changing plans:** you change plans in the billing portal linked from Studio. A larger plan
  applies at once, and Polar charges or credits the difference for the rest of the period. A smaller plan
  applies at once too; files above its storage limit are kept, but you can't upload more until
  you are under it.
- **Cancelling:** you can cancel at any time in the billing portal. The plan keeps working until
  the end of the period you paid for, and the workspace then returns to the Free plan. We don't
  refund the rest of a period, unless the law requires it.
- **Failed payments:** if a payment fails, Polar retries it for a while and the plan keeps
  working. If it still can't be paid, the workspace returns to the Free plan.
- **Price changes:** we tell you at least 30 days before a price change takes effect. It applies
  from your next renewal, and you can cancel before then.

## Availability and changes

We work to keep the service running, but we do not promise it is always available or free of
errors. Paid plans also come with our [Service Level Agreement](/legal/sla/): a monthly uptime
commitment, with service credits if we miss it. We may change or remove features. If we remove a feature you rely on, we give
reasonable notice where we can.

## Ending

You can delete your account or shut down your workspace in Studio at any time. We may end your
access with 30 days' notice, or right away if you seriously break these terms. When a workspace
is shut down, we delete its content as described in the [Privacy Policy](/legal/privacy/).
Download anything you want to keep before you shut it down.

## Disclaimer

The service is provided "as is". To the extent the law allows, we give no warranties, including
fitness for a particular purpose. You are responsible for checking that the documents you
produce are correct and meet the rules that apply to you.

## Liability

To the extent the law allows, neither side is liable for indirect or consequential losses, such
as lost profits or lost data. Our total liability in any 12 months is limited to the greater of
what you paid us in those 12 months and EUR 100. These limits do not apply to liability that
cannot be limited by law, such as for intent or gross negligence.

## Changes to these terms

We may update these terms. We tell you by email or in Studio at least 30 days before a change
that affects you takes effect. If you keep using the service after that, you accept the new
terms. If you don't, you can stop using it and delete your account.

## Law and disputes

These terms are governed by the laws of Estonia. Harju County Court in Tallinn decides any
dispute, unless the law requires otherwise.

## Contact

Runecode OÜ, Iirise tn 3-3, Tartu linn, Tartu maakond, 51011, Estonia, legal@runecode.ee