API

The Automette REST API lets you generate documents from your own code. Use it to automate certificate creation, send personalised invoices, populate PDFs from form data, or integrate with any backend that can make an HTTP request.

For the full endpoint reference, see the API Reference section.

Authentication

All requests require a Bearer token:

Authorization: Bearer dg_your_api_key

Open API Keys in the menu to create a key. A key belongs to one team and sees only the templates and renders belonging to that team. See Authentication for details.

Step 1: Find your template ID and fields

List templates in your team:

curl https://automette.com/api/v1/templates \
  -H "Authorization: Bearer dg_your_api_key"

Fetch a single template to see its available fields and default values:

curl https://automette.com/api/v1/templates/{id} \
  -H "Authorization: Bearer dg_your_api_key"

The response includes a fields array with each field's key, type, and default value. Every field carries primary: true for content, false for styling such as colour or font. Canvas fields also carry tier (content, styling or advanced), and canvas templates return layers, the same fields grouped by the layer they sit on.

Position, size, rotation, opacity and font size are set in the template editor and cannot be changed through the API.

Step 2: Generate a document

curl -X POST https://automette.com/api/v1/renders \
  -H "Authorization: Bearer dg_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "cm4tpl8e20001js04xq2v9k3m",
    "data": {
      "name": "Alice Johnson",
      "course": "Advanced TypeScript",
      "date": "24 June 2026"
    }
  }'

A field left out of data is blank in a Typst template, and keeps the template's own value in a visual editor or Word template. See Blank values.

Async vs sync

Async (default)

The request returns 202 Accepted immediately with a render ID and status: "pending". The document is generated in the background. A render that has not finished within 10 minutes is marked failed, and your webhook hears about it, so a request never stays pending for good.

{ "id": "cm8r2k9x10003js08a1b2c3d4", "status": "pending" }

Use a webhook (see below) or poll until status is "completed":

curl https://automette.com/api/v1/renders/{id} \
  -H "Authorization: Bearer dg_your_api_key"

Sync

Add "async": false to wait for the result in the same response (up to 30 seconds):

{
  "template_id": "cm4tpl8e20001js04xq2v9k3m",
  "data": { ... },
  "async": false
}

Returns 200 OK with the completed render if it finishes in time. If it takes longer, falls back to 202 with status: "pending"; poll as you would for an async request. A timeout is not an error.

Webhooks

Set webhook_url to receive a POST callback when the render completes, instead of polling:

{
  "template_id": "cm4tpl8e20001js04xq2v9k3m",
  "data": { ... },
  "webhook_url": "https://your-app.com/hooks/automette"
}

The payload sent to your URL is the same JSON as GET /api/v1/renders/{id}.

Output formats

All engines support multiple formats in one request. Use formats (array) or format (single string):

{
  "template_id": "cm4tpl8e20001js04xq2v9k3m",
  "data": { ... },
  "formats": ["pdf", "png"]
}

The response always includes a files array, with one entry per output format.

Visibility

In both cases the url in the response is a link you can hand to anyone, such as an email recipient or a Zap step, without sharing your API key. The difference is how long it lasts.

Default is secure. Set "visibility": "public" in the request body to override.

Because a secure url expires, store the render's self link rather than its url. Fetching self with your API key returns the render again with a freshly signed url, so you can always get a working link:

curl https://automette.com/api/v1/renders/{id} \
  -H "Authorization: Bearer dg_your_api_key"

Filename patterns

Control the output filename using filename_pattern. Field values and built-in tokens are supported:

{
  "filename_pattern": "{name}_{date}"
}

Built-in tokens: {template}, {date}, {time}, {datetime}, {random}, and {index} for the row number in a batch.

You can also set a default filename pattern on the template itself in the Settings tab of the template editor (Manage template for a Word template). When no filename_pattern is passed in the API call, the template's saved pattern is used. If neither is set, the default is {template}-{datetime}-{random}.

Rate limits

Each API key can make 600 requests and 120 renders a minute. Over that, the API answers 429 with a Retry-After header saying how many seconds to wait. See Rate limits.

Listing renders

curl "https://automette.com/api/v1/renders?template_id=cm4tpl8e20001js04xq2v9k3m&limit=20" \
  -H "Authorization: Bearer dg_your_api_key"

Supports template_id, status, limit, and cursor for pagination. Renders from every source (API, CSV, forms, the dashboard) appear here.

Last updated on