API reference

The service exposes an HTTP API for converting and rendering templates programmatically. This page covers authentication, the output formats, the hash‑first workflow, and where to get the machine‑readable OpenAPI document. For the conceptual walkthrough of the render pipeline itself, see Rendering documents.

Authentication

All API endpoints (except the stateless POST /convert) require an API key passed as a Bearer token:

Authorization: Bearer dc_live_xxxxxxxxxxxxxxxxxxxx

Each organization has exactly one key pair: a live key (dc_live_…) and a test key (dc_test_…). An owner or admin generates the pair once under Account → API Keys; after that the only change is to regenerate either key independently, which immediately invalidates the previous secret. The secret is shown only at generate/regenerate time. Each key is pinned to one organization for life (see Organizations).

Today the test key differs from the live key only in which usage bucket its requests count under — both render identically. The environment is a filter on the usage stats (see below), not a sandbox.

Managing keys and usage

Keys and usage are managed with session (cookie) auth from the dashboard; the generate and regenerate actions require an organization owner or admin.

Both usage endpoints accept an optional ?env=live or ?env=test to scope the numbers to one environment; omit it to count all requests. Usage is reported per organization to every member.

Output formats

The format parameter selects the rendered output. It accepts five values:

format=csv is rejected with HTTP 400. See Output formats for the full behaviour, including the single‑page vs. multi‑page ZIP rules.

Template data

Pass a JSON object as data_json. Placeholders in the template use the {d.field} syntax, with inline conditionals and DOCX loops. The full syntax is documented under Template data substitution.

curl -X POST https://your-instance.example.com/api/render/<hash> \
  -H "Authorization: Bearer dc_live_xxxxxxxxxxxxxxxxxxxx" \
  -F "format=pdf" \
  -F 'data_json={"company":"Acme Corp","invoice_no":"INV-001"}' \
  -o invoice.pdf

Endpoints

Auth levels: public (none), session (cookie or API key), api‑key (API key only).

This is the high‑traffic subset; the OpenAPI document below is the complete, authoritative list of every endpoint, parameter, and response schema.

Hash‑first workflow

The recommended integration contract for machine clients uses the SHA‑256 hash of the template file as a stable identifier:

1. Upload a template once → receive its hash.
2. Reference it forever by hash — no IDs to track.
3. Use HEAD /api/render/{hash} to check whether a version is already registered before uploading again.

The hash is resolved within the API key's organization, so the same hash can map to different templates in different orgs.

The OpenAPI spec

The complete API is described in an OpenAPI 3.0 document, served as a static file you can download and feed to any OpenAPI tooling:

GET /openapi.yaml

Inspecting it in Postman

1. Download the spec from https://your-instance.example.com/openapi.yaml (or use the download link above).
2. In Postman, Import → drop in the openapi.yaml file (or paste the URL). Postman generates a collection with every endpoint, example bodies, and the format / data_json parameters pre‑filled.
3. Set the collection's baseUrl variable to your instance and add your API key as a Bearer token (Authorization: Bearer dc_live_…).

From there you can fire real requests against your instance and tweak the generated examples. The same file imports cleanly into other OpenAPI tooling (Swagger UI, Insomnia, code generators).