Render a template

POST https://api.craftkit.dev/v1/templates/:slug/render

Validates data against the template’s published manifest and enqueues a render job. Returns 202 with a poll URL. Rendering is asynchronous — there is no synchronous mode (see Render lifecycle).

Authorization

string

required

Bearer ck_live_… — a project API key.

string

Optional. Retrying with the same key returns the original render instead of creating a duplicate. Takes precedence over the body jobId. See Idempotency.

Path parameters

string

required

The template slug.

Body

object

required

Variable values. Scalars nest by dot-path ({ "customer": { "name": "…" } }); loops are keyed by their dot-free top-level key. Keys absent from the manifest are stripped. Loop arrays are capped at 10,000 items. See Variables & loops.

string

Optional idempotency key (fallback when no Idempotency-Key header is sent).

object

Show options

boolean

default:"false"

Accepted by the schema but not honored — every render is async. Poll the result.

number

Pin to a specific published version. Defaults to current.

string

Override the asset filename (max 120 chars).

Response

202 when a new render is queued, or 200 when an idempotency key matched an existing render.

string

queued for a fresh render; the existing render’s current status on an idempotent replay.

string

GET this to poll the render.

string | null

null until the render succeeds.

string | null

string

Errors

Status	code	Meaning
400	`invalid_json`	Body is not valid JSON.
400	`invalid_request`	Body failed schema validation (`issues` included).
400	`invalid_input_data`	`data` did not match the manifest (`issues` included).
401	`unauthorized`	Missing/invalid/revoked key.
404	`template_not_found`	No such template in this key’s project.
404	`version_not_found`	Pinned `versionNumber` does not exist.
409	`no_published_version`	Template has no published version.
503	`queue_unavailable`	Render queue is temporarily unreachable — retry.

cURL

curl -X POST https://api.craftkit.dev/v1/templates/charter-handover/render \
  -H "Authorization: Bearer $CRAFTKIT_API_KEY" \
  -H "Idempotency-Key: handover-BK-12345-checkout" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "booking": { "code": "BK-12345" },
      "handover": { "kind": "checkout", "date": "2026-06-04", "signedBy": "Jane Doe" },
      "areas": [ { "areaKey": "hull", "condition": "damage" } ]
    },
    "options": { "filename": "charter-handover-BK-12345.pdf" }
  }'

202

{
  "id": "…",
  "status": "queued",
  "pollUrl": "https://api.craftkit.dev/v1/renders/…",
  "downloadUrl": null,
  "errorMessage": null,
  "createdAt": "2026-06-05T10:00:00.000Z"
}

Projects

Templates

Renders

Signatures

Webhooks

Embed

Reference

Projects

Templates

Renders

Signatures

Webhooks

Embed

Admin

System

Render a template

Authorization

Path parameters

Body

Response

Errors

​Authorization

​Path parameters

​Body

​Response

​Errors

Authorization

Path parameters

Body

Response

Errors