Core concepts
A handful of nouns cover the whole product. Once they make sense, the API reference reads like a list of things you already know.
Organisation and workspace
An organisation is the billing and membership boundary: one plan, one invoice, one member list. It also holds what every document shares across workspaces: the fonts, the brand kit and the shared partials.
Every member has one of four roles in the organisation:
| Role | May |
|---|---|
| Viewer | read templates, renders and files |
| Editor | everything a viewer may, plus edit, save and publish templates, render, and upload files |
| Admin | everything an editor may, plus create and revoke API keys, manage webhooks, invite members, delete templates |
| Owner | everything an admin may, plus the plan and billing |
A workspace is where the work lives: templates, API keys, renders, webhook endpoints and the file library. Each workspace has its own region and output retention. Keep production and staging apart with two workspaces; agencies usually create one workspace per client. How many workspaces an organisation may have depends on its plan (1 on Free, 3 on Starter, 10 on Pro).
An API key belongs to exactly one workspace and works only there: it renders that workspace's templates and lists that workspace's renders. The one exception is the workspace:delete scope, which may delete another workspace of the same organisation.
Template and version
A template is a named document definition with a slug (invoice, certificate-en) that your code refers to. The API also gives every template an id (tpl_ followed by 32 hexadecimal characters); a render accepts either. A template has a kind (pdf, image, or docx and pptx for Word and PowerPoint templates), a template language (jinja2, liquid or handlebars, see Template languages), and these parts:
| Part | What it holds |
|---|---|
Template (html) | The body: HTML with template tags |
| CSS, Head | Stylesheet, and extra <head> content such as font links |
| Header, Footer | Running header and footer for every PDF page |
| Settings | Paper, margins, image size, locale, timezone, currency, Tailwind |
| Sample data | Named JSON data sets for the preview, autocomplete and tests; never used by an API render |
| Data schema | A JSON Schema of the expected data, inferred from the sample data unless you provide one |
| Translations | Per-locale dictionaries for the t() helper |
| Partials | Fragments the template includes by name, saved with the version (from the CLI project's partials/ folder) |
A Word or PowerPoint template keeps its document file in place of the HTML, CSS, head, header and footer; its settings, sample data, schema and translations work the same way.
A version is an immutable snapshot of all of those parts. Saving in the editor or running formfeed templates push creates a new draft version. Publishing a version makes it the one the API renders; the previously published one is archived. Exactly one version is published at a time, so you can keep editing drafts without touching production. Restoring an old version saves a new draft with its content. Besides published, a template can have named release channels such as staging that point at other versions; a render picks one with version.
A render's version field takes:
| Value | Renders |
|---|---|
published | The published version (the default) |
| a channel name | The version the release channel points at |
a number, e.g. 3 | That version |
latest | The newest saved version, published or not; test keys only |
The API renders the published version unless a render names a version or a channel, and picks up a newly published one within a minute. The editor's preview and its True render work on what is open in the editor, unsaved changes included, with the sample data set you picked.
Render and job
A render is one execution: a source (a template, ad-hoc html, or a url), plus data, plus options, producing one output file. Every render has an id (rnd_ followed by 32 hexadecimal characters), a status (queued → rendering → succeeded or failed), timings, the units it cost, and checksums that make it reproducible. See Rendering.
A job is a batch of up to 1,000 renders submitted in one request (POST /v1/renders/batch), always processed asynchronously, optionally zipped. A job has its own id (job_…) and status: queued, processing, then completed, partially_failed or failed. See Async and batch.
API keys and environments
API keys come in two environments, and the prefix tells you which. Owners and admins create them on the API keys page of a workspace.
Live (ff_live_…) | Test (ff_test_…) | |
|---|---|---|
| Metered | Yes, units in the answer | No, units is 0 |
| Counts against the quota | Yes | No |
| Output kept | The plan's retention, or the workspace's shorter one | At most 24 hours |
| Test mark on the file | Never | On the Free plan; on every plan for an e-invoice |
| Deduplicated | Yes | No |
version: "latest" | Refused | Allowed |
| Rate limit | The plan's requests per second on renders and PDF tools | Same, plus 30 per minute on the Free plan |
Use test keys for development, CI and the dev kit, and switch to a live key in production. Each key also carries scopes that decide what it may do. How long each plan keeps outputs and its other limits are in Limits and usage.
Units
Formfeed meters in units:
- a PDF of up to 5 pages is 1 unit, and every further 5 pages (or part of them) add 1: 6–10 pages cost 2 units, 11–15 pages cost 3;
- an image (PNG, JPG or WebP) is 1 unit, and so is a filled Word or PowerPoint file; a PDF from a Word or PowerPoint template, and one from
/pdf/convert, follow the PDF rule; - each post-processing step (merging PDFs, adding a password, stamping a watermark) is 0.5 units, on a render's
postas with the PDF tools; reading a PDF's information is free; - an e-invoice adds 1 unit to its render;
- renders with a test key, previews in the editor and offline validation are free;
- a deduplicated render costs 0 units.
Every render response reports the units in its body (units) and in the X-Units-Charged header, and X-Units-Remaining tells you what is left in the billing period. Plans include an amount per billing period. Paid plans continue with overage, up to a hard cap unless you switch on auto top-up; the Free plan stops with 402 quota_exceeded. Details in Limits and usage.
Region
The region is where rendering and output storage happen. Today every render runs in eu: rendering in Frankfurt, storage in the EU. us and apac are names the API contract reserves for regions that have no render worker yet, so leave the region field of a render out; it defaults to the workspace's region. See Data residency.
Webhook endpoint
A webhook endpoint is an HTTPS URL in your application that receives signed events such as render.completed or job.completed. It is how asynchronous work reports back. See Webhooks.