API

The Automette REST API lets you generate documents from your own code — no dashboard required. 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

Go to Settings → API Keys to create a key. Keys are team-scoped — they see 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 an available_fields array with each field's key, type, and default value.

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": "tmpl_abc123",
    "data": {
      "name": "Alice Johnson",
      "course": "Advanced TypeScript",
      "date": "24 June 2026"
    }
  }'

Any field omitted from data uses the default value set in the template.

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.

{ "id": "rnd_xyz", "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": "tmpl_abc123",
  "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 async. A timeout is not an error.

Webhooks

Set webhook_url to receive a POST callback when the render completes — no polling needed:

{
  "template_id": "tmpl_abc123",
  "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": "tmpl_abc123",
  "data": { ... },
  "formats": ["pdf", "png"]
}

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

Visibility

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

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

You can also set a default filename pattern on the template itself via the Settings tab in the template editor. 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}.

Template Sets (Collections)

To generate one document per template in a set, use the Collections endpoint:

curl -X POST https://automette.com/api/v1/collections \
  -H "Authorization: Bearer dg_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_set_id": "set_abc123",
    "data": { "name": "Alice Johnson" }
  }'

Returns 202 Accepted with a collection ID. Poll GET /api/v1/collections/{id} for status and per-document URLs.

Listing renders

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

Supports template_id, status, limit, and cursor for pagination. All renders — from any source (API, CSV, form, dashboard) — appear here.

Last updated on