Stencilry API (v1)

Stencilry turns a Liquid template and a JSON payload into a PDF. You author the template once, then post payloads against it.

Everything below calls https://api.stencilry.dev and uses $STENCILRY_KEY for your API key.

1. Get an API key

Two credentials open this API, and they are interchangeable — every secured operation accepts either:

POST /api-keys needs a credential itself, so your first key comes from the studio: sign in, open API keys, and create one.

The token is returned once, by the call that creates the key. It is never readable again — the list only carries prefix, the first 12 characters, so one key can be told from another. Store it before you close the dialog.

2. Check that it works

curl -s "https://api.stencilry.dev/templates" -H "X-Api-Key: $STENCILRY_KEY"

A 200 with a JSON array — [] on a new account — means the key is live:

[
  {
    "id": "0d6b9a5e-1f3c-4a7d-9c2b-5f8e1a0b7c34",
    "name": "Invoice",
    "description": "Monthly invoice",
    "version": 3,
    "createdAt": "2026-09-01T09:14:22.104Z",
    "updatedAt": "2026-09-18T16:02:47.881Z"
  }
]

A 401 means the header is missing or the key was revoked.

3. Mint further keys from the API

Once you hold one key you can mint more without the studio:

curl -s -X POST "https://api.stencilry.dev/api-keys" \
  -H "X-Api-Key: $STENCILRY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"billing-worker","description":"Nightly invoice run"}'

{
  "key": {
    "id": "8f2c1b44-7a90-4d16-b3e8-2c5d90ab1f77",
    "name": "billing-worker",
    "description": "Nightly invoice run",
    "prefix": "stcl_xvfb8Gx",
    "createdAt": "2026-09-21T11:40:03.221Z",
    "revokedAt": null
  },
  "token": "stcl_xvfb8GxK3mQ7pT2aL9dR4wN6yB1cE8sV"
}

Names are unique across the keys you hold that are not revoked — reusing a live name is a 409. Revoking a key frees its name.

Next

Generate a PDF posts a payload against a stored template. Preview and diagnostics renders template and payload together without storing anything, which is the loop to use while authoring.

A stored template plus a payload gives you a PDF. This is the call your server makes in production.

1. Create the template

curl -s -X POST "https://api.stencilry.dev/templates" \
  -H "X-Api-Key: $STENCILRY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Invoice",
        "description": "Monthly invoice",
        "body": "<h1>Invoice {{ number }}</h1><p>Due {{ due }}</p><p>Total {{ total }}</p>",
        "payload": "{\"number\":\"INV-001\",\"due\":\"2026-10-01\",\"total\":\"R 1 240.00\"}"
      }'

body is the Liquid template. payload is a sample payload stored beside it — the studio uses it for previews, and it documents the shape the template expects. Both are optional at creation and can be filled in later with PUT /templates/{id}.

The response carries the template's id. Keep it; it is the only handle to the template.

2. Generate

curl -s -X POST "https://api.stencilry.dev/templates/$TEMPLATE_ID/generate" \
  -H "X-Api-Key: $STENCILRY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payloadJson":"{\"number\":\"INV-042\",\"due\":\"2026-11-01\",\"total\":\"R 3 980.00\"}"}'

Note that payloadJson is a string holding JSON, not a nested object. It is the payload the template renders against.

{
  "document": "JVBERi0xLjcKJcfsj6IKNSAwIG9iago8PC9MZW5ndGgg...",
  "warnings": []
}

document is the PDF, base64. Decode it to bytes and write the file:

curl -s -X POST "https://api.stencilry.dev/templates/$TEMPLATE_ID/generate" \
  -H "X-Api-Key: $STENCILRY_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"payloadJson\":$(jq -Rs . < payload.json)}" \
| jq -r .document | base64 -d > invoice.pdf

3. Read the warnings

warnings is almost always empty and is never a reason to fail the call — the PDF in document is complete either way. A warning names something the renderer could not honour:

{
  "document": "JVBERi0xLjcK...",
  "warnings": [
    {
      "code": "template.undefined_field",
      "message": "The template refers to 'customer.vatNumber', which the payload does not contain. It rendered as empty text.",
      "location": { "line": null, "column": null, "jsonPath": "$.customer.vatNumber" }
    }
  ]
}

The codes:

location is nullable, and so is each of its three fields.

Log warnings.

Status codes

Errors and retries covers 500 and 503 in full.

POST /render/preview renders a template and a payload together and stores nothing. Use it while authoring: no template has to exist, and nothing you send is kept.

The call

curl -s -X POST "https://api.stencilry.dev/render/preview" \
  -H "X-Api-Key: $STENCILRY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "templateHtml": "<h1>Invoice {{ number }}</h1><p>Total {{ total }}</p>",
        "payloadJson": "{\"number\":\"INV-042\",\"total\":\"R 3 980.00\"}",
        "page": { "size": "A4", "orientation": "Portrait" }
      }' \
  -o preview.multipart -D headers.txt

page is optional and defaults to A4 portrait.

The success body is multipart, not JSON

A 200 is multipart/form-data with two parts:

Multipart rather than a base64 envelope because base64 adds a third to the size of every render, and an authoring loop renders constantly. The boundary is generated per response and is in the Content-Type header — read it from there, never assume it.

The parts arrive in that order. The sample beside this operation shows the read in each language.

A failed render is 422, not 400

422 is the one to handle, and it is wider than it looks: a payloadJson that is not well-formed JSON lands here too, not on 400. This differs from POST /templates/{id}/generate, where malformed payloadJson is a 400.

The body is the same diagnostics object, without a PDF:

{
  "pageCount": 0,
  "errors": [
    {
      "code": "TemplateSyntax",
      "message": "End of tag '}}' was expected at (1:14)",
      "location": { "line": 1, "column": 14, "jsonPath": null }
    }
  ],
  "warnings": []
}

code is one of JsonParse, TemplateSyntax, TemplateRuntime, Render, Timeout. They cross the wire as names, never as numbers. Malformed payloadJson gives JsonParse.

A clean render is not a correct document

The renderer reports nothing when it ignores something — no exception, no warning, no log entry. CSS it does not support is parsed and then dropped, and the page comes back looking finished.

So 200 with errors: [] and warnings: [] means the render completed. It does not mean the document is right. Open the PDF and look at the pages before you ship a template.

Every failure that carries a body uses RFC 9457 problem details, served as application/problem+json. The two render endpoints are the exception on some codes, and return diagnostics instead — those are listed below.

The problem shape

POST /templates with no name:

{
  "type": "https://www.rfc-editor.org/rfc/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "instance": "/templates",
  "traceId": "0HNONU92PQJJV:00000001",
  "detail": "A name is required.",
  "errors": [
    { "name": "name", "reason": "A name is required." }
  ]
}

errors[].name is the request field that caused it, or generalErrors when the failure is not about a field — a 404 reads {"name":"generalErrors","reason":"No Template exists with that id."}.

Quote traceId when you report a problem. It identifies the single request in our logs.

What to do with each code

500 is retryable here, and that is deliberate

On POST /templates/{id}/generate and POST /render/preview, a 500 has a specific meaning: the PDF rendered, and the service could not record the run. The document is withheld rather than returned unrecorded.

Nothing was charged and nothing was kept. Retry the identical request.

503 and backoff

Renders run in a fixed number of slots. When none comes free within the wait, the request is refused without being attempted — 503, with a diagnostics body whose errors is empty and pageCount is 0. Nothing rendered.

Retry with exponential backoff and jitter. Three attempts at 1s, 2s and 4s, each ±20%, clears ordinary contention:

for attempt in 1 2 3; do
  code=$(curl -s -o out.json -w '%{http_code}' -X POST "https://api.stencilry.dev/templates/$TEMPLATE_ID/generate" \
    -H "X-Api-Key: $STENCILRY_KEY" -H "Content-Type: application/json" \
    -d "{\"payloadJson\":$(jq -Rs . < payload.json)}")

  [ "$code" = "200" ] && break
  [ "$code" = "500" ] || [ "$code" = "503" ] || break

  sleep $(( 2 ** (attempt - 1) ))
done

What never to retry

A 400, 401, 404, 409 or 422 will fail identically however many times you send it.

Idempotency

POST /templates/{id}/generate and POST /render/preview have no side effect you can observe beyond a recorded run, so a retry is safe. POST /templates and POST /api-keys create things — a blind retry after a timeout can leave you with two. Check with GET /templates or GET /api-keys before sending again.