Rendering API

The Rendering API turns a Bannx page (from a template) into an image. Use a page ID with GET or POST: by default the page is loaded from the publish cache; set draft: true on POST to load from the database (unpublished).

Endpoints

GET /api/render/:pageId

Render a page by ID using query parameters. By default loads from the publish cache; set draft=true to load from the database (same as POST).

Authentication depends on the template setting Require token for GET render (editor → Settings → Template):

• On (default): Send Authorization: Bearer <API key> or add the space GET render URL secret as query param gt (create it under Settings → Space → Developers). The API key must belong to the same space as the template. Useful for <img src="..."> without request headers.
• Off: No auth; anyone with the page ID can call GET for that template’s pages.

Query parameters:

Response: Binary image/PDF, or application/json with file metadata when output is not binary.

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

# Same request using GET URL secret (no Bearer)
curl "https://your-app.bannx.app/api/render/PAGE_ID?format=png&gt=YOUR_GET_SECRET" -o out.png

POST /api/render

Render using a page ID. Loads the page and template from the publish cache by default, or from the database when draft: true (e.g. before publish).

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

Request body (JSON):

Response (default): application/json with pageId, templateId, draft, format, mimeType, width, height, emojiType, renderMs, uploadMs, and file (id, url, sizeBytes). The render is uploaded to temporary storage for your space; use file.url to display or download the image.

Response (with "output": "binary" or "binary": true in the body): Raw body — image types as GET, or application/pdf when format is pdf.

Example (JSON default — save response and inspect file.url):

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 response.json

Example (raw image body):

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

Example (draft / unpublished page):

{
  "pageId": "PAGE_ID",
  "draft": true,
  "format": "png",
  "tweaks": { "title": "My Banner" }
}

Example (single-page PDF):

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

Example (merged multi-page PDF):

{
  "pageIds": ["PAGE_A", "PAGE_B"],
  "format": "pdf",
  "output": "binary",
  "tweaksPerPage": [{ "title": "Page A" }, { "title": "Page B" }]
}

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:

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

Errors

Webhooks

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