Variables

Templates and pages use variables to make content dynamic (e.g. title, count, date). When rendering, you can override variable values with tweaks so the same template produces different output.

Variable scopes

Scope	Where defined	When used
Page variables	On each page in the editor	For that page only
Template variables	On the template	Shared by all pages of the template
Global variables	Space settings (global variables)	Available to all templates in the space

The same name in different scopes can have different values; overrides are applied by name when you pass tweaks.

Variable shape

Variables can be in two forms:

Array form (legacy): [{ id, name, schema, value }, ...]
Object form (JSON Schema style): { schema: { type: "object", properties: { ... } }, values: { key: value } }

The Rendering API accepts both for inline page / templateVariables / globalVariables and normalizes internally.

Overriding with tweaks

tweaks is a flat object: keys are variable names (or IDs), values are the override values. Tweaks apply to page, template, and global variables (by name).

GET `/api/render/:pageId`

Query: tweaks as a JSON string, or multiple tweak:<name>=<value> query params.

Example (JSON):

/api/render/PAGE_ID?format=png&tweaks={"title":"Hello","count":5}

Example (per-param):

/api/render/PAGE_ID?format=png&tweak:title=Hello&tweak:count=5

POST `/api/render`

Body: tweaks object, e.g. "tweaks": { "title": "Hello", "count": 5 }.

Tweaks are applied after loading the page (and template/global variables), so they override any existing value for that name.

Example

Template has a template variable title (default "Welcome") and a page variable count (default 10). To render with custom values:

GET:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://your-app.bannx.app/api/render/PAGE_ID?format=png&tweak:title=Summer%20Sale&tweak:count=3" -o out.png

POST:

{
  "pageId": "PAGE_ID",
  "format": "png",
  "tweaks": {
    "title": "Summer Sale",
    "count": 3
  }
}

Bindings

Bindings link layer properties (e.g. text content, image URL) to variables. They are stored on the page (and sometimes derived from the template). You don't send bindings in the render request; you only send tweaks (variable overrides). The renderer resolves bindings using the final variable values (after tweaks).

Bulk generation

For many variants (e.g. one image per row of a sheet), use bulk generation:

POST /api/bulk-generate with a page and a list of contents (each content has its own variable set). Each content's data is applied like tweaks for that variant. Requires authentication (session/user). See dashboard or server schema for exact body shape.