# Craftkit

> Design document templates, then render PDFs from a REST API.

## Docs

- [Provision an org](https://docs.craftkit.dev/api-reference/admin/provision-an-org.md): Idempotently provision a Craftkit project + API key + embed partner for an external org id. The first call returns the plaintext API key (store it — it cannot be recovered later); subsequent calls decrypt and return the same key. Authenticated by the deployment admin key.
- [Update provisioned org settings](https://docs.craftkit.dev/api-reference/admin/update-provisioned-org-settings.md): Update mutable partner settings (currently `emailFrom`) for an existing provisioned org.
- [Cancel a signature request](https://docs.craftkit.dev/api-reference/cancel-signature.md): POST /v1/signatures/:id/cancel — cancel an in-flight signature request.
- [Create a builder template](https://docs.craftkit.dev/api-reference/create-builder-template.md): POST /v1/embed/builder/templates — create a template in a partner project from a builder draft. Accepts a partner API key or an embed session JWT.
- [Publish a catalog](https://docs.craftkit.dev/api-reference/create-catalog.md): POST /v1/embed/catalogs — publish a named, versioned variable catalog for the embed picker.
- [Create an embed session](https://docs.craftkit.dev/api-reference/create-session.md): POST /v1/embed/sessions — mint a signed, short-lived session your front-end mounts in an iframe.
- [Create a share](https://docs.craftkit.dev/api-reference/create-share.md): POST /v1/renders/:id/shares — mint a durable, revokable share link for a succeeded render.
- [Create a signature request](https://docs.craftkit.dev/api-reference/create-signature.md): POST /v1/signatures — send a succeeded render out for digital signature.
- [Create a template](https://docs.craftkit.dev/api-reference/create-template.md): POST /v1/templates — create a published template from a variable manifest, no builder or hand-written layout required.
- [Delete a template](https://docs.craftkit.dev/api-reference/delete-template.md): DELETE /v1/templates/:slug — soft-delete a template and free its slug for recreation.
- [Download a render (private)](https://docs.craftkit.dev/api-reference/download-render.md): GET /v1/embed/renders/:id/download — stream a render's PDF from private storage with your project key.
- [Download the signed PDF](https://docs.craftkit.dev/api-reference/download-signature.md): GET /v1/signatures/:id/download — stream the archived, signed PDF (authenticated only).
- [Email a render](https://docs.craftkit.dev/api-reference/email-render.md): POST /v1/renders/:id/email — create an email share and deliver the document via Resend.
- [Create a builder template](https://docs.craftkit.dev/api-reference/embed/create-a-builder-template.md): Create a template in the partner's project from the builder's CanvasDocument draft. Accepts **either** a partner API key (full rights) **or** an embed session token (rights from session claims).
- [List builder templates](https://docs.craftkit.dev/api-reference/embed/list-builder-templates.md): List non-deleted templates for the partner's project. Partner API key only.
- [List embed renders](https://docs.craftkit.dev/api-reference/embed/list-embed-renders.md): List renders (form submissions / PDF instances) for the partner's project, excluding internal preview/dashboard renders. Partner secret key. Offset-paginated.
- [Mint an embed session](https://docs.craftkit.dev/api-reference/embed/mint-an-embed-session.md): Mint a short-lived embed session for the iframe builder/form, using the partner secret key. Returns the session token (JWT), the iframe URL, and a single-use renew token. Note the snake_case response keys.
- [Publish a variable catalog version](https://docs.craftkit.dev/api-reference/embed/publish-a-variable-catalog-version.md): Publish a named variable catalog version using the partner secret key. Calling with the same name creates the next version and marks it current; previous versions are archived, never deleted.
- [Refresh an embed session](https://docs.craftkit.dev/api-reference/embed/refresh-an-embed-session.md): Rotate a session token using a single-use renew token. Authenticated by the partner secret.
- [Submit an embed form](https://docs.craftkit.dev/api-reference/embed/submit-an-embed-form.md): Submit form-fill data for a `fill`-mode embed session. Authenticated by the embed session JWT (which must match the path `sessionId` and carry the `submitForm` permission). Validates against the template manifest, merges JWT prefill under user data, and enqueues a render. The returned `pollUrl` poin…
- [Upload a form image](https://docs.craftkit.dev/api-reference/embed/upload-a-form-image.md): Upload a single image (multipart `file` field) for a `fill`-mode embed session, returning its public URL so the form payload can carry a URL instead of a raw file. Authenticated by the embed session JWT. Max 10 MB, `image/*` only.
- [Errors](https://docs.craftkit.dev/api-reference/errors.md): The error envelope, the codes you'll encounter, and retry semantics.
- [Submit a form](https://docs.craftkit.dev/api-reference/form-submit.md): POST /v1/embed/form-submit/:sessionId — validate filled form data and enqueue a render. Embed session JWT only.
- [Download the completion certificate](https://docs.craftkit.dev/api-reference/get-certificate.md): GET /v1/signatures/:id/certificate — stream the signing completion certificate (authenticated only).
- [Get engagement](https://docs.craftkit.dev/api-reference/get-engagement.md): GET /v1/renders/:id/engagement — aggregate engagement counts plus the most recent events for a render.
- [Get a render](https://docs.craftkit.dev/api-reference/get-render.md): GET /v1/renders/:id — poll a render's status and retrieve the download URL when ready.
- [Get a signature request](https://docs.craftkit.dev/api-reference/get-signature.md): GET /v1/signatures/:id — poll status, signed-document URL, and certificate for one request.
- [Get a template](https://docs.craftkit.dev/api-reference/get-template.md): GET /v1/templates/:slug — template metadata, the published variable manifest, and a generated JSON Schema.
- [Health check](https://docs.craftkit.dev/api-reference/health.md): GET /v1/health — public liveness/readiness probe; 200 when healthy, 503 when degraded.
- [Inbound webhook](https://docs.craftkit.dev/api-reference/inbound-webhook.md): POST /v1/hooks/:token — trigger a render from any system that can POST JSON, with optional HMAC signing.
- [List builder templates](https://docs.craftkit.dev/api-reference/list-builder-templates.md): GET /v1/embed/builder/templates — list a partner project's templates. Partner API key only.
- [List embed renders](https://docs.craftkit.dev/api-reference/list-embed-renders.md): GET /v1/embed/renders — list a partner project's renders for an embedding host. Partner API key only.
- [List shares](https://docs.craftkit.dev/api-reference/list-shares.md): GET /v1/renders/:id/shares — list every share for a render, newest first, revoked included.
- [List signature requests](https://docs.craftkit.dev/api-reference/list-signatures.md): GET /v1/signatures — list a project's signature requests, newest first, cursor-paginated.
- [List templates](https://docs.craftkit.dev/api-reference/list-templates.md): GET /v1/templates — list the templates in your project with publish state.
- [Refresh an embed session](https://docs.craftkit.dev/api-reference/refresh-session.md): POST /v1/embed/sessions/refresh — rotate a session token with its single-use renew token.
- [Render a template](https://docs.craftkit.dev/api-reference/render-template.md): POST /v1/templates/:slug/render — validate data against the manifest and enqueue an async render.
- [Create a share link](https://docs.craftkit.dev/api-reference/renders/create-a-share-link.md): Create a new share link for a succeeded render. `channel="email"` requires `recipientEmail`; to actually send, use `POST /v1/renders/{id}/email`.
- [Download the rendered PDF](https://docs.craftkit.dev/api-reference/renders/download-the-rendered-pdf.md): Stream the rendered PDF straight from storage (authenticated).
- [Email a render to a recipient](https://docs.craftkit.dev/api-reference/renders/email-a-render-to-a-recipient.md): Create an email-channel share, render the email via Resend, and send it. Records `share_created` + `email_sent` engagement events.
- [Get engagement summary](https://docs.craftkit.dev/api-reference/renders/get-engagement-summary.md): Aggregate engagement counts plus the most recent events for a render.
- [Get render status](https://docs.craftkit.dev/api-reference/renders/get-render-status.md): Poll a render's status and retrieve its asset URL once ready. When a public bucket URL is configured the `downloadUrl` is a direct link; otherwise it points at the authenticated `/download` route.
- [List share links](https://docs.craftkit.dev/api-reference/renders/list-share-links.md): List all share links for a render (revoked shares included).
- [Record a partner-side engagement event](https://docs.craftkit.dev/api-reference/renders/record-a-partner-side-engagement-event.md): Record a partner-side print/download/view event (e.g. from a dashboard viewer UI). Recipient-side events are recorded server-side from the public share pages.
- [Revoke a share link](https://docs.craftkit.dev/api-reference/renders/revoke-a-share-link.md): Revoke (soft-delete) a share link.
- [Revoke a share](https://docs.craftkit.dev/api-reference/revoke-share.md): DELETE /v1/renders/:id/shares/:shareId — soft-delete a share so its public link stops resolving.
- [Cancel a signature request](https://docs.craftkit.dev/api-reference/signatures/cancel-a-signature-request.md): Cancel an in-flight signature request. Terminal requests cannot be cancelled.
- [Download the completion certificate](https://docs.craftkit.dev/api-reference/signatures/download-the-completion-certificate.md): Stream the signing completion certificate (audit-trail PDF, a sensitive legal artifact, always served through the authenticated API — never a public URL).
- [Download the signed PDF](https://docs.craftkit.dev/api-reference/signatures/download-the-signed-pdf.md): Stream the archived signed PDF (a sensitive legal artifact, always served through the authenticated API — never a public URL).
- [Get a signature request](https://docs.craftkit.dev/api-reference/signatures/get-a-signature-request.md): Poll a signature request's status and signed-document URL.
- [List signature requests](https://docs.craftkit.dev/api-reference/signatures/list-signature-requests.md): List signature requests for the project, newest first. Keyset-paginated via `cursor` (ISO timestamp) — pass the returned `nextCursor` to fetch the next page.
- [Send a render out for signature](https://docs.craftkit.dev/api-reference/signatures/send-a-render-out-for-signature.md): Push a succeeded render's PDF to the signature service as an atomic create-and-send signing request. Provide field placements via explicit `fields` (page + percentage coordinates) or `anchorTags` (text anchors). Pass an `Idempotency-Key` header to make retries safe.
- [Health check](https://docs.craftkit.dev/api-reference/system/health-check.md): Reports overall status and dependency checks. Returns 503 when degraded. No auth.
- [Create a template](https://docs.craftkit.dev/api-reference/templates/create-a-template.md): Create a template from a variable manifest (and optional layout). When `layout` is omitted a CanvasDocument layout is synthesized from the manifest. Publishes version 1.
- [Create or republish a template at a slug](https://docs.craftkit.dev/api-reference/templates/create-or-republish-a-template-at-a-slug.md): Idempotent companion to `POST /v1/templates`. The URL slug is canonical (any `slug` in the body is ignored). If the template does not exist it is created and version 1 published (`201`). If it exists, a new version (n+1) is published and becomes current (`200`). Existing renders pin their own versio…
- [Get a template](https://docs.craftkit.dev/api-reference/templates/get-a-template.md): Fetch a single template's metadata, its published variable manifest, and the auto-generated JSON Schema for client-side validation. Returns `manifest: null` / `published: false` when the template exists but has no published version (distinct from a 404).
- [List templates](https://docs.craftkit.dev/api-reference/templates/list-templates.md): List the templates in the authenticated key's project, newest-updated first.
- [Render a template](https://docs.craftkit.dev/api-reference/templates/render-a-template.md): Validate request `data` against the template's variable manifest and enqueue an async render job. Returns `202` with a poll URL for a freshly queued render, or `200` when an `Idempotency-Key` (or body `jobId`) replays an existing render.
- [Soft-delete a template](https://docs.craftkit.dev/api-reference/templates/soft-delete-a-template.md): Soft-delete a template and free its canonical slug for recreation. The original slug is echoed back. Existing renders are untouched. A second DELETE of the same slug returns `404`.
- [Track an event](https://docs.craftkit.dev/api-reference/track-event.md): POST /v1/renders/:id/events — record a partner-side engagement event from your own viewer UI.
- [Update a template](https://docs.craftkit.dev/api-reference/update-template.md): PUT /v1/templates/:slug — create-or-republish a template from a manifest. Idempotent provisioning + in-place regeneration.
- [Upload a form image](https://docs.craftkit.dev/api-reference/upload-form-image.md): POST /v1/embed/form-submit/:sessionId/upload-image — upload an image and get back a public URL. Embed session JWT only.
- [Inbound render trigger](https://docs.craftkit.dev/api-reference/webhooks/inbound-render-trigger.md): Inbound webhook trigger authenticated by the per-template token in the URL. The JSON body becomes the variable input for a render. Optional HMAC verification: if the `x-craftkit-signature` header is present it must be the hex HMAC-SHA256 of the raw body using the template's `inboundSecret`. Not bear…
- [Concepts](https://docs.craftkit.dev/concepts.md): Templates, versions, variables, manifests, and the render pipelines — the mental model behind every API call.
- [Authentication](https://docs.craftkit.dev/guides/authentication.md): What one project API key can do, how key scope works today, and how the admin key differs.
- [Server-to-server integration](https://docs.craftkit.dev/guides/headless-integration.md): The complete playbook for a backend integration that auto-renders a PDF with no human at render time — and a coverage map for every requirement.
- [Hosts & environments](https://docs.craftkit.dev/guides/hosts-and-environments.md): Which host and namespace a headless integration uses for create, poll, download, and shares — and why environment-specific keys matter.
- [Idempotency](https://docs.craftkit.dev/guides/idempotency.md): Dedupe retried renders so an offline-replay reconnect or a flaky network never produces two copies of the same document.
- [Images & signatures](https://docs.craftkit.dev/guides/images-and-signatures.md): How to bind a dynamic image or a signature image into a render — the validation rule that rejects base64, and which pipelines actually render a data-bound image.
- [Render lifecycle](https://docs.craftkit.dev/guides/render-lifecycle.md): What actually happens after you POST a render: async-only behavior, the authoritative status enum, and how durable the download URL really is.
- [Render pipelines](https://docs.craftkit.dev/guides/render-pipelines.md): The worker renders with one of three pipelines, chosen from the template's content. They differ in loop and dynamic-image support — pick the right one before authoring.
- [Sharing](https://docs.craftkit.dev/guides/sharing.md): Mint a durable, revisitable, revokable share link for a rendered PDF — a better artifact to hand a guest than the raw download URL.
- [Variables & loops](https://docs.craftkit.dev/guides/variables-and-loops.md): How dot-path scalar keys nest, how loops bind arrays of objects, and the one binding rule that silently empties a loop if you get it wrong.
- [Verify before you render](https://docs.craftkit.dev/guides/verify-before-render.md): List templates and read a template's manifest with your project key, so you fail fast instead of hitting a 404 or invalid-data error at render time.
- [Webhooks](https://docs.craftkit.dev/guides/webhooks.md): Receive a callback when a render completes so you can drop polling — configured in the dashboard, signed with HMAC-SHA256.
- [Craftkit](https://docs.craftkit.dev/index.md): Design document templates in a visual editor, then render PDFs from a REST API — asynchronously, at scale.
- [Quickstart](https://docs.craftkit.dev/quickstart.md): Authenticate, render a PDF, poll to completion, and download — in five minutes.

## OpenAPI Specs

- [openapi](https://docs.craftkit.dev/openapi.yaml)