Skip to main content
These endpoints are served by the self-hosted server — the same engine behind npm install, packaged as a Docker image:
Base URL below is http://localhost:3000 (substitute your deployment). Authentication is optional: set the FORME_API_KEY environment variable on the container and pass it as a Bearer token; with no key set, endpoints are open. See Self-Hosting for full setup.
Forme also runs a hosted API at https://api.formepdf.com, in the same /v1 route family. It adds saved JSX and HTML + Liquid templates, POST /v1/render/html, async jobs with webhooks, S3 upload, document storage, and POST /v1/extract. Its request bodies differ in places: see Hosted API — Render. If you’d rather not run a server at all, every operation here is also a function call in @formepdf/core.

Render PDF (inline)

POST /v1/render Renders a compiled template sent in the request. Fully stateless. Body:
Response: 200 OK with Content-Type: application/pdf body.

Render PDF (template by slug)

POST /v1/render/:slug Renders a pre-compiled JSON template from the directory set by FORME_TEMPLATES_DIR ({slug}.json). See Self-Hosting — Template render. Path params: slug — the template file name without .json. Body:
Response: 200 OK with Content-Type: application/pdf body. An unknown slug returns 404.

Flatten Forms

POST /v1/render?flattenForms=true or POST /v1/render/:slug?flattenForms=true Render a PDF with all form fields flattened — interactive fields are converted to static content. Useful for filling a form template with data and sending a non-editable PDF.

Embedded Data

The self-hosted server has no /v1/extract endpoint. To read data embedded with embedData, call extractData() from @formepdf/core, or use POST /v1/extract on the hosted API. See Embedded Data.

Error Format

All errors return JSON:
Common HTTP status codes:
  • 400 — Invalid request, or the render failed (code: BAD_REQUEST, RENDER_FAILED). Hosted-only fields such as certificateId and a redaction template also return 400.
  • 401 — Missing or wrong API key, when FORME_API_KEY is set
  • 404 — Template not found
  • 501 — Resource listing (GET /v1/templates, /v1/documents, …), which is hosted-only
  • 500 — Internal server error