Rendering API

The Rendering API turns a Bannx page (from a template) into an image. You can either reference a published page by ID (GET or POST) or send full page data in the request body (POST).

Endpoints

GET `/api/render/:pageId`

Render a published page by ID. The page must exist and its template must be published so the page is available in the publish cache.

Authentication: Required (Authorization: Bearer <token>).

Query parameters:

Parameter	Type	Description
`format`	`png` \| `svg` \| `webp`	Output format. Default: `png`.
`tweaks`	string (JSON)	JSON object of variable overrides by name, e.g. `{"title":"Hello","count":5}`.
`tweak:<name>`	string/number/boolean	Alternative: per-variable overrides, e.g. `tweak:title=Hello` and `tweak:count=5`.

Response: Binary image (image/png, image/svg+xml, or image/webp).

Example:

# PNG (default)
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://your-app.bannx.app/api/render/PAGE_ID" -o out.png

# WebP with variable overrides (JSON)
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://your-app.bannx.app/api/render/PAGE_ID?format=webp&tweaks=%7B%22title%22%3A%22Hello%22%7D" -o out.webp

# SVG with query tweaks
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://your-app.bannx.app/api/render/PAGE_ID?format=svg&tweak:title=Hello" -o out.svg

POST `/api/render`

Render using either a page ID (published) or inline page data. Use inline data for one-off renders or when the page is not yet published.

Authentication: Required (Authorization: Bearer <token>).

Request body (JSON):

Field	Type	Description
`pageId`	string	If set: fetch this published page (and its template) from cache. Mutually exclusive with full inline `page`.
`page`	object	Inline page: `width`, `height`, `layers`, `variables`, `bindings`, etc. Use when not using `pageId`.
`draft`	boolean	If `pageId` is set and `draft: true`, load page (and template) from database instead of cache. Default: `false`.
`format`	`png` \| `svg` \| `webp`	Output format. Default: `png`.
`tweaks`	object	Variable overrides by name (applied to page, template, and global variables).
`globalVariables`	array or object	Optional; used with inline `page`.
`templateVariables`	array or object	Optional; used with inline `page`.
`emojiType`	string	Optional; e.g. `twemoji`, `openmoji`. Default from template/space.

Response: Binary image (same as GET).

Example (by page ID):

curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pageId":"PAGE_ID","format":"webp","tweaks":{"title":"Hello"}}' \
  "https://your-app.bannx.app/api/render" -o out.webp

Example (inline page):

{
  "page": {
    "width": 1200,
    "height": 630,
    "backgroundColor": "#ffffff",
    "layers": [ ... ],
    "variables": [ ... ],
    "bindings": [ ... ]
  },
  "format": "png",
  "tweaks": { "title": "My Banner" }
}

Code-to-image (POST `/api/code-to-image`)

Separate endpoint to render code snippets as images (syntax highlighting). No API token required for this endpoint.

Request body:

Field	Type	Description
`code`	string	Required. Source code to render.
`lang`	string	Language for highlighting (e.g. `js`, `ts`). Default: `js`.
`theme`	string	Shiki theme. Default: `github-dark`.
`format`	`png` \| `webp` \| `jpeg`	Default: `webp`.
`width`, `height`, `quality`, `style`	optional	Layout and style options.

Response: Image (e.g. data URL or binary depending on implementation).

Errors

Status	Meaning
`400 Bad Request`	Invalid body or query (e.g. missing both `pageId` and `page`).
`401 Unauthorized`	Missing or invalid API token.
`404 Not Found`	Page or template not found (or not in cache when not using `draft`).
`500 Internal Server Error`	Rendering failed.

Webhooks

Render requests can trigger webhooks (e.g. upload result, update log). See Webhooks for configuration and behavior.