Documentation

API reference

Create template IDs, publish immutable versions, and render PDFs.

Set a base URL and admin token for the examples:

base=http://127.0.0.1:8080
admin_token='replace-with-your-admin-token'

Create a template ID

curl --fail-with-body -X POST "$base/v1/admin/templates" \
  -H 'content-type: application/json' \
  -H "x-admin-token: $admin_token" \
  --data '{"id":"invoice"}'

IDs and versions start with an alphanumeric character. They can contain letters, numbers, periods, underscores, and hyphens.

Publish a version

A publish request carries everything the version needs to render, so a render never depends on host files.

Inside Typst, request data is sys.inputs.at("data") and request asset paths are sys.inputs.at("assets"). This example publishes the invoice template shipped in the repository, which uses both.

main=$(base64 < templates/invoice-v1.typ | tr -d '\n')
font=$(base64 < assets/fonts/NotoSans-Regular.ttf | tr -d '\n')

jq -n --arg main "$main" --arg font "$font" '
  {
    schema: {
      type: "object",
      additionalProperties: false,
      required: ["number", "customer", "amount"],
      properties: {
        number:   {type: "string"},
        customer: {type: "string"},
        amount:   {type: "string"}
      }
    },
    source: {"main.typ": $main},
    fonts: {"NotoSans-Regular.ttf": $font},
    request_assets: ["logo.png"]
  }
' > invoice-v1.json

curl --fail-with-body -X POST "$base/v1/admin/templates/invoice/versions/v1" \
  -H 'content-type: application/json' \
  -H "x-admin-token: $admin_token" \
  --data-binary @invoice-v1.json

Published content cannot change or be deleted. Publishing over an existing version returns 409; publish a new version name instead.

Retire and restore a version

Retirement is an administrative lifecycle change. It keeps the immutable version and its objects durable, but stops rendering it and frees an active-version slot.

curl --fail-with-body -X POST \
  -H "x-admin-token: $admin_token" \
  "$base/v1/admin/templates/invoice/versions/v1/retire"

curl --fail-with-body -X POST \
  -H "x-admin-token: $admin_token" \
  "$base/v1/admin/templates/invoice/versions/v1/unretire"

Both successful calls return 204 No Content. A retired version stays in PostgreSQL and S3 but its render request returns 410 Gone. Unretirement checksum-verifies the stored pack and can return 503 when an active-version limit would be exceeded. Retirement does not free retained-byte capacity.

Render a PDF

GET /metrics is not a public API route. It is served only by the dedicated metrics listener (default METRICS_ADDR=0.0.0.0:9090); the API listener returns 404 for /metrics. The metrics listener is private only when deployment networking keeps it internal.

Request assets are sent base64 under the names declared in request_assets. Any other name is rejected with 400, so a caller cannot introduce arbitrary Typst file names.

jq -n --arg logo "$(base64 < assets/testdata/logo.png | tr -d '\n')" '
  {
    data: {number: "INV-001", customer: "Ada Lovelace", amount: "1,240.00"},
    assets: {"logo.png": $logo}
  }
' > invoice-render.json

curl --fail-with-body -X POST "$base/v1/templates/invoice/versions/v1/render" \
  -H 'content-type: application/json' \
  --data-binary @invoice-render.json \
  --output invoice.pdf

The default response is application/pdf. assets may be omitted entirely for a template that declares no request assets. To persist a result instead of returning bytes, enable ALLOW_PERSISTED_RESULTS and send {"output":{"persist":true}}; the response is then a JSON storage key and SHA-256 checksum.

Status codes