Core concepts

Imprime has a small, predictable model. Once you know these five words, the editor, the API and the MCP tools all make sense.

Template ─┬─ Page ─── Shape (text · rectangle · ellipse · image · group)
          ├─ Page ─── Shape …
          └─ Variables (name, type, default, required)
                   │
     variable values (JSON) ──► Export ──► PDF (one PDF page per page)

Template

A template is the document you design once and fill many times. It has a title, an ordered list of pages and a set of variables. Each template belongs to the user who created it; only its owner (or an API key belonging to that owner) can read, edit or export it.

Its ID — visible in the editor URL /editor/<id> — is what you pass to the API and to MCP.

Page

A page becomes one page of the final PDF, in order. Every page of a template shares the template’s size, chosen at creation: A4 portrait (1240 × 1754), A4 landscape (1754 × 1240) or 16:9 (1920 × 1080).

Note

A page can also carry a condition (shown only when a boolean variable is true) or a repeat (one copy per item of a list). See Variables.

Shape

Everything you place on a page is a shape, positioned with x, y, width and height in canvas pixels:

Shape	What it holds
Text	Paragraphs of rich text (font, size, color, bold, italic, underline) and variables
Rectangle	Fill, stroke (color, width, solid / dashed / dotted) and corner radius
Ellipse	Fill and stroke
Image	An uploaded PNG or JPEG, or an image variable
Group	Other shapes, laid out as a row, a column or a stack

Shapes are stacked: later shapes are drawn on top of earlier ones. Use the layering toolbar to change the order.

Variable

A variable is a named placeholder that lives at the template level and can be inserted in any text box, as many times as you like.

Property	Meaning
name	Unique within the template. Letters, digits and _, not starting with a digit.
required	Export fails if no value is provided.
default	Used when no value is provided (only for non-required variables).
type	string, boolean, image or object-list.

When exporting, values are matched by variable name:

{ "customerName": "Ada Lovelace", "total": "€1,250.00" }

For each variable, Imprime uses the value you sent; if it’s missing or empty, the default; and if there’s no default, an empty string. If a required variable is missing, the export is rejected with a 400 error.

Export

An export renders a template plus a set of variable values into a PDF. You can trigger it three ways — they all run the same renderer:

• the Imprime button in the editor (guide),
• POST /api/export/{id}/pdf (API),
• the preview_template MCP tool (MCP).

API key

An API key authenticates scripts and tools as you, outside the browser. Send it in the x-api-key header. Create and revoke keys in Settings → API Keys (guide).