Bannx
Render on-brand images, PDFs and videos from templates, and create and edit templates and brands, from any AI agent. Remote MCP server at https://bannx.com/mcp with a Bearer API key.
Hosted MCP Server
npx add-mcp 'https://bannx.com/mcp'Installs into Claude Code, Codex, Cursor and more
Documentation
Copy page
MCP Server
Connect Cursor, the Cursor CLI, Claude Desktop, Claude Code, or any other MCP client to your space. The agent acts with your API key.
It can:
- Create, edit and render creatives — build a still or an animation from scratch as a scene of nodes, edit it with batched operations, and render it to a file. Edits land in open editors live.
- Manage brands — read, create and update brand tokens, or resolve a brand from a website URL.
- Manage content — create collections and entries the templates can pull from.
- Find icons — search the Iconify sets and drop an icon straight into a creative.
Unlike the AWS S3 integration, MCP is not a connection you save under Settings → Space → Integrations. Create a key under Settings → Space → Developers, then copy the client config from Settings → Space → MCP into your agent.
Authentication
The MCP server uses the same API keys as the REST API. Create one under Settings → Space → Developers, then pass it as a Bearer token on every MCP request.
No separate MCP credential is required.
The key acts with its creator's current access to the space: if they leave the space or are removed, every tool that touches the space answers with an error, and tools whose dashboard twin needs a permission (reading templates, versions or social posts, and every write) need the same permission here. The guides, the public gallery, icon search and the built-in shader presets stay available.
If the key can't be checked, /mcp answers by status: 401 (with WWW-Authenticate: Bearer) means the key itself is missing, unknown or expired — fix the key. 503 (with Retry-After) means bannx couldn't check it right now — retry the same key after the delay; don't discard it.
Endpoint
POST https://bannx.com/mcp
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Stateless Streamable HTTP: one POST per JSON-RPC message, no session to resume. GET (the SSE stream) and DELETE return 405.
Protocol revision 2026-07-28 (per-request envelope, server/discover, cache hints on tools/list and prompts/list). Clients from 2024-11-05 through 2025-11-25 keep working on the same endpoint, unchanged.
Client configuration
Cursor
Add to your MCP settings (.cursor/mcp.json or Cursor Settings → MCP):
{
"mcpServers": {
"bannx": {
"url": "https://bannx.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
Cursor CLI agent
The Cursor CLI agent reads the same config files as the IDE: a global ~/.cursor/mcp.json and an optional project-level .cursor/mcp.json. Add bannx under mcpServers (use type: "http" for the remote transport):
{
"mcpServers": {
"bannx": {
"type": "http",
"url": "https://bannx.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
Start a new CLI session so the config reloads, then run /mcp to confirm bannx and its tools are listed.
Claude Desktop (remote HTTP)
Use the same url and headers shape if your client supports remote Streamable HTTP MCP servers.
Codex
Codex reads ~/.codex/config.toml (or .codex/config.toml in a trusted project). Name the environment variable that holds the key. Codex sends it as Authorization: Bearer, and the key itself stays out of the file:
[mcp_servers.bannx]
url = "https://bannx.com/mcp"
bearer_token_env_var = "BANNX_API_KEY"
The same table is what codex mcp add bannx --url https://bannx.com/mcp --bearer-token-env-var BANNX_API_KEY writes. Start a new session so it reloads. The snippets on Settings → Space → MCP use your deployment's URL.
Start here
Install the bannx agent skills (npx skills add https://bannx.com) and your agent follows this workflow on its own. By hand, a first session, creative-first:
whoami— confirm the space, and see which tools this key may call (allowedTools).get_guide{ "topic": "creative-authoring" }— the document model: scenes, the scene frame, node types, coordinates, keyframes. Read it before the firsttemplate_create.template_create—{ "name": "Launch banner", "width": 1200, "height": 630, "brand": "Coca Cola" }. Take thetemplateIdfrom the result.brandbinds{{ brand.* }}to that brand (omit it to follow the space default;set_template_brandchanges it later). You can seed the first scene withoperationshere too.template_get— read the snapshot. The scene'smainIdis the scene frame; node ids are opaque 8-character strings and are only valid when they came from a snapshot. Never guess one.template_apply_ops— add and style nodes in one batch (example below). Use thenodeIds the result returns for later edits.template_render—{ "templateId": "…", "format": "png", "variables": { "headline": "Ship faster" }, "brandVariant": ["xmas"] }.- Open the returned
url. The result also carries aresource_linkso clients that render links can open it without parsing the JSON. When a script downloads it, send a User-Agent: Python's bareurllib(Python-urllib/3.x) is refused with403/error code: 1010, whilerequests,httpx,curlandfetchwork as-is (see Rendering).
An operations batch for step 5 — a background, a headline bound to a variable (with a marker-pen highlights box behind each line — a stack of solid or gradient layers with padX/padY/radius; put highlights on a spans entry, or <mark color> in the text, to highlight only some words) and an icon placed by Iconify name. Omitting parentId parents a node into the scene frame; x/y are the node's top-left corner (CSS box model).
{
"templateId": "66f1…",
"operations": [
{ "op": "updateScene", "sceneIndex": 0, "patch": { "fill": "#0f172a" } },
{
"op": "addNode",
"type": "text",
"props": {
"text": "{{ use(headline, 'Your headline here') }}",
"x": 600, "y": 280, "w": 900, "h": 120,
"fontSize": 72, "fontFamily": "{{ use(brand.typography.heading, 'Inter') }}",
"fill": "#ffffff", "align": "center",
"highlights": [{ "type": "solid", "color": "#fde047", "padX": 8, "radius": 6 }]
}
},
{
"op": "addNode",
"type": "svg",
"props": {
"icon": "ph:rocket-launch",
"x": 600, "y": 160, "w": 64, "h": 64,
"svgColors": { "*": "{{ brand.colors.primary }}" }
}
}
]
}
Tools
Every tool carries MCP annotations, so a client that confirms destructive calls only asks before template_delete and delete_template. The Access column reflects those annotations: Reads never change the space, Writes create or update, Destructive removes data that cannot be recovered from the tool. Reads marked (network) contact something beyond the space, such as a website.
Identity & guides
| Tool | Description | Access |
|---|---|---|
whoami | The space, user and credit balance this key acts as. Call it first to confirm you are in the right space. | Reads |
get_guide | Read one long-form guide by topic: creative-authoring, template-expressions, brand-tokens, icons. | Reads |
Templates
| Tool | Description | Access |
|---|---|---|
list_public_templates | Browse the public template gallery, or search it with a plain-words brief (search — ranked semantically over name, description and each template's design digest: format, palette, fonts, layout traits), filter by category (featured for the curated set), format (creative, video, doc, html-ad, mockups, backgrounds), page, perPage. Rows include designDigest / designDigestText. | Reads |
get_public_template | The compact layer tree of a public gallery template from any space (templateId, detail: "active" or "all") — same snapshot shape as template_get. Use it as a design reference: borrow structure, proportions, type scale and timing; never copy its copy or imagery. | Reads |
list_templates | Templates in the space, newest first: templateId, name, size, fps and whether there is a document to render. | Reads |
get_template | A template's summary plus what you can vary when rendering: its variables (name, type, default), saved variations (id, name, group, enabled, override count) and variation groups — and motion { animated, detected, setting, durationSeconds }: whether it plays (video export) and for how long. pageView (single or carousel) says how the template page shows a still's scenes, and pageGap the pixels between them (0 = seamless carousel); pageFlow / variationFlow (row or column) say how pages (vertical unless row), and variation instances in the editor (horizontal unless column), stack. | Reads |
Creatives
| Tool | Description | Access |
|---|---|---|
template_create | Create a creative template (still or animated) at a given width / height / fps, optionally seeding the first scene with operations and attaching a brand (name, brandId or URL). The seed batch is all-or-nothing: if any op fails, no template is created and the error names the op. Returns the templateId and a snapshot with node ids. | Writes |
template_get | The document as a compact snapshot: artboard, scenes, and each scene's node tree with ids (detail: "all" or "active"). If someone is editing live you see their current state. | Reads |
template_apply_ops | Apply a batch of operations in order and persist. All or nothing: the batch is validated first (schema, refs, node ids), and if any op fails nothing is written; the error names the op (op 3 (addNode) props.w: …). dryRun: true returns the would-be results without writing. New nodes and scenes can carry a ref that later ops in the same batch use as "$ref", and addNode takes nested children (see Building in one call). Also takes settings (name, description, plus the download, size and page view options described on the Templates page). Returns a per-operation result and a fresh snapshot. Live editors receive the change as it lands: anyone with the template open sees the agent listed as a participant (named after the API key) with the layers it just changed outlined and briefly tinted, for a few seconds after each write. The editor also says what the agent's last write added, changed or removed, and offers Follow (the view moves to each write's layers) and Undo (restores the version saved right before that write). The agent's cursor moves across the layers the write added or changed, with a short title such as "Added Headline"; pass an optional note (a few words, for example "Tightening the headline", shown cut to 48 characters) to title the cursor yourself. Between writes, template_get, a dryRun, template_render and template_version_save on the same template show as what the agent is doing ("Reading the design", "Trying changes", "Rendering a preview", "Saving a version"). Includes setVariables — declare the template's variables ({ variables: [{ name, type, label, default }] }) and bind them with {{ name }}; a bound name you never declared is auto-declared as a string (the result lists autoDeclaredVariables). And setVariations — alternate looks such as dark mode, in single- or multi-select groups (see Variations). Every write (and template_create) also reports unboundVariables with a warnings line when a declared variable is read by no layer — bind it or remove it, callers' values for it are ignored; an addNode whose coordinates fall outside the scene frame returns a warning too, since renders print only the scene frame. | Writes |
template_delete | Remove nodes (nodeIds) and/or whole scenes (sceneIndexes) from a creative. Cannot be undone from here. | Destructive |
delete_template | Permanently delete a whole template — its record, document and published snapshot, so the public page and API stop serving it. Pass templateId and confirmName (the template's current name). A missing or mismatched confirmName deletes nothing, and the error states the exact name expected. The key's owner must still be a member of the space with a role that may delete templates (owner, admin or editor by default). | Destructive |
template_render | Render a creative to a file and return its URL. Accepts variables, variation, brand (another brand of your space — id, name or website URL — for this render only; the template keeps its own), brandVariant, brandVariantMode, brandTokens and draft (render your latest edits instead of the published version). pages: "all" renders every page of a still template (a carousel's slides, a repeated scene's items) as one still each: the result's pageUrls lists { index, name, url, fileId } in order (fileId is the page's media library file, what social_create_post takes as fileIds), pages is their count and zipUrl is a ZIP of them, one credit per page. A single still also returns its fileId. The result reports creditsCharged and balanceAfter. format: "html5" exports a standalone HTML5 ad ZIP: pass clickUrl (required), optional loops and a network preset; the result carries adReport with sizes and warnings judged against that network. | Writes (idempotent) |
template_sign_urls | Mint keyless signed image URLs (/r/:id?…&sig=…) for a published template — variables for one, rows (≤ 500) for one per recipient; options sets format (png/webp), scale ≤ 2, scene (one page), exp; pages: "all" signs one URL per page for every row (each result row carries scene and page). Each URL renders once on first open. See Signed image URLs. | Reads |
template_versions | A template's version history, newest first: versionId, reason (auto, publish, manual, before-api, pre-restore, restore, wipe-guard), label, createdOn, author, extra and isCurrent. page / perPage (≤ 100). Metadata only. | Reads |
template_version_save | Save the template as it is now as a version, with an optional label (named versions are never pruned; at most 100 per template). Save one before a large or experimental template_apply_ops batch. | Writes |
template_restore | Restore versionId from template_versions: design, name, variables, size, frame rate and variations. The current state is saved as a pre-restore version first (the restore aborts if that fails), open editors receive the restored design live, and what is published does not change. See Version history. | Writes |
set_template_brand | Attach a brand to a template by name, brandId or website URL, so {{ brand.* }} resolves against it — or pass null to detach and follow the space default. | Writes (idempotent) |
Media
| Tool | Description | Access |
|---|---|---|
media_upload | Put an image, video, audio file or PDF into the media library (from a public url or dataBase64) and get a hosted URL to use as a node's src, plus the library fileId (what social_create_post takes as fileIds). Counts toward the space's storage quota: a space at or over it gets a "Storage quota exceeded" error and nothing is stored. | Writes |
mockup_prepare | Turn a product photo (fileId or imageUrl) into a mockup: segments the printable surface (maskPrompt, points), places the print for the surface (fabric, screen, paper, rigid, label), optionally derives wrinkles from depth, and stores the mask and wrinkle maps in the media library. scene ({ preset?, prompt? }) relights the photo or places the product in a new setting first (+3 credits by default). Returns warpNode and mockup to add with template_apply_ops (set mockup.baseId to the photo layer, "$base" in the same batch). Costs credits: segment 1 + depth 1 by default, reported as creditsCharged; nothing is charged if a step fails. See Mockups. | Writes (spends credits) |
Social publishing
Post to the accounts connected under Publish — see From an agent (MCP). social_create_post and social_cancel_post speak publicly for you, so they are opt-in: a key can use them only when its tool scopes list them (see Opt-in tools).
| Tool | Description | Access |
|---|---|---|
social_list_accounts | The connected social accounts: accountId, platform, label, handle, status and media (maxCount: how many images one post takes on that platform, plus whether it takes images, GIFs and video). Never credentials. | Reads |
social_list_posts | Posts newest first (status filter, limit ≤ 50) with each channel's delivery status, live URL and error. A post under approval also carries approval: { state, note? }; filter on pending_approval, changes_requested or expired to find them. | Reads |
social_create_post | Post text and optional media to one or more targets (account ids). You must pass exactly one of scheduledAt (future ISO datetime) or publishNow: true. Media: fileIds (media library) and/or mediaUrls (URLs of files already in the library, such as a template_render or media_upload url — any other URL is refused and nothing is fetched). Each channel is validated against its platform's limits first. Max 30 calls a minute per key. Returns postId, status, scheduledOn, targets. When the space requires approval for API keys, status is pending_approval, the result adds approval and a message, and nothing is scheduled until a person approves it (see Approvals). Opt-in; the key's owner must be an owner, admin or editor. | Writes (publishes externally) |
social_cancel_post | Cancel a scheduled post by postId. Anything already live stays live and the post is kept as history marked cancelled. Opt-in; owner, admin or editor. | Destructive |
Post a carousel. Render every page of a still template, then post the pages as one multi-image post, in slide order:
template_render { templateId, pages: "all", format: "png" }— one credit per page; eachpageUrls[]entry carries afileId.social_create_post { targets, text, fileIds: pageUrls.map(p => p.fileId), scheduledAt }— or pass the pageurls asmediaUrls.
A post takes at most 10 files, and each platform its own media.maxCount from social_list_accounts (X 4, LinkedIn 9, most others 10). A channel that takes fewer can get its own targets[].fileIds. In the app, the Post button on a template page does the same — see Post a carousel.
Approvals for agent posts
A space can require a person to approve posts before they go out. When approvals are on for API keys (the default once a space turns approvals on), every social_create_post call lands as pending_approval, even when the key belongs to an owner: an agent always waits for a person. The approvers are emailed; nothing is queued until one of them approves the post in Publish. There is no MCP tool to approve a post, so an agent cannot approve its own (or anyone's) work.
- Tell the user the post is waiting for approval;
social_list_posts { status: "pending_approval" }shows what is still waiting. changes_requestedmeans an approver sent it back: the result'sapproval.notesays why. Create a new post with the changes (the agent cannot edit the old one).- A post still unapproved at its time becomes
expiredand is never published. social_cancel_postwithdraws a waiting post.
Brands
| Tool | Description | Access |
|---|---|---|
list_brands | Brands in the space: id, name, and whether live or draft tokens exist. | Reads |
get_brand | A brand with all its token groups (draftTokens, liveTokens, tokens) and campaign variants. | Reads |
resolve_brand | Turn a brand name, brandId or website URL into a brandId with render-ready tokens. With createFromUrl (the default) an unknown URL is fetched and a brand is created from it. | Writes (network) |
create_brand | Create a brand with its token groups. | Writes |
update_brand | Change a brand's name, tokens or campaign variants. Each token group you pass replaces the stored one whole. | Writes (idempotent) |
Content
| Tool | Description | Access |
|---|---|---|
list_collections | Content collections in the space and their fields. | Reads |
create_collection | Create a collection, or update one by collectionId. fields adds entry fields; existing fields are never changed or removed. | Writes |
list_contents | Entries in one collection, paginated. | Reads |
create_content | Create an entry, or update one by contentId. publish: true publishes instead of saving a draft. | Writes |
Shaders
| Tool | What it does | Access |
|---|---|---|
list_shader_presets | The built-in shaders — backgrounds (grid, mesh gradient, dot matrix, film grain) and the text-effect pack tagged text (outlined, sticker, long shadow, 3D extruded, chrome, neon, inset, glitch, reveal, marching ants) — with full WGSL source and inputs. Read one of a similar kind before writing your own. | Reads |
list_shaders | The space's shaders: id, name, status, declared inputs, cost. Find a shaderId here; never invent one. | Reads |
get_shader | One shader's author source and input manifest, for editing. | Reads |
create_shader | Author a WGSL fragment shader. It is vetted in a sandbox first — forbidden constructs, loop bounds, a cost budget, a real compile and a fuzz render. If rejected, nothing is stored and the result carries the failing stage and log to fix and retry. | Writes |
update_shader | Change a shader's source, inputs, name or description. A source or input change is re-vetted; if rejected the stored shader is unchanged. | Writes (idempotent) |
Place a shader on a canvas with template_apply_ops:
{ "op": "addNode", "type": "shader", "props": { "shaderId": "…", "x": 0, "y": 0, "w": 1200, "h": 630, "shaderUniforms": { "speed": 0.2 } } }
The compiled body, uniform defaults and texture bindings are derived on the server from the vetted record. shaderUniforms tunes numeric inputs. An image picker belongs to the shader when its manifest declares an input with type: "texture"; the shader samples it with textureSample(photo, photoSampler, uv) for an input named photo. Set or replace its image on a canvas node with shaderTextures: { "photo": "<media-library URL>" } in addNode props or an updateNode patch. A type: "text" input takes its string through shaderTexts: { "label": "Summer sale" } (up to 200 characters, cut to the input's maxLength); the platform draws it into a distance field the shader reads with labelSd(uv), so the text never becomes code. See Shaders → Text. To style a text layer with a text shader instead, pass effects: [{ "type": "shaderText", "shaderId": "…", "pad": 32 }] in its props: the shader's text input reads the layer's own letters, shaderUniforms on the effect tunes the rest, and pad is the room in pixels outside the box for outlines and shadows (see Shader effect on a text layer). The shader code itself is never taken from the caller. Only approved shaders in your space or published shaders can be placed.
Icons
| Tool | Description | Access |
|---|---|---|
list_icon_collections | The Iconify icon sets available (prefix, name, size, samples). Phosphor (ph) is the house default. | Reads |
search_icons | Find icon names by keyword (query, optional prefix / prefixes). Returns names like ph:house. | Reads |
list_icon_collection | Icon names within one set (prefix, optional search), paginated. | Reads |
Building a document
Building in one call: refs and nested children
A node's id is only known once it exists. Without refs, every op that touches a new node has to wait for the next call. Give addNode a ref instead, and write "$<ref>" wherever a node id goes later in the same batch. That covers parentId, nodeId, targetId, nodeIds, an instance's componentId, instance override keys, a mockup warp's mockup.baseId and variation keys such as "$card.fill".
{
"templateId": "66f1…",
"operations": [
{ "op": "addNode", "type": "frame", "ref": "card", "props": { "x": 80, "y": 80, "w": 480, "h": 160, "fill": "#111827" },
"children": [
{ "type": "text", "ref": "label", "props": { "text": "Ship faster", "x": 24, "y": 24, "fill": "#ffffff" } },
{ "type": "rect", "ref": "bar", "props": { "x": 24, "y": 120, "w": 0, "h": 8, "fill": "#22c55e" } }
] },
{ "op": "setKeyframes", "nodeId": "$label", "tracks": { "opacity": [{ "t": 0, "v": 0 }, { "t": 0.6, "v": 1, "ease": "out" }] } },
{ "op": "setKeyframes", "nodeId": "$bar", "tracks": { "w": [{ "t": 0, "v": 0 }, { "t": 1.2, "v": 432, "ease": "inOut" }] } }
]
}
- The result's
refsmaps each ref to the real node id ({ "card": "ab12cd34", … }). Refs last for one batch; use the returned ids in later calls. - A ref is letters, digits,
_or-, written without the$where it is declared. It must be unique in the batch and declared by an earlier op. An unknown or duplicate ref refuses the whole batch before anything runs. childrenis a list of{ type, props, ref?, children? }. A parent must be a frame or board. Childx/yare relative to the parent. The result'schildIdslists the new descendants depth-first.w/hmay be0, as with the bar above, which grows from nothing.originX/originYtake any finite number, so-3.2scales a layer about a point beside it.- The batch is all-or-nothing, so a failed build never leaves a half-built template. Pass
dryRun: trueto check a large batch first: it returns the results, refs and snapshot without writing anything.
Scene refs: several scenes and their content in one call
addScene takes a ref too. After it, "$<ref>" is the new scene's scene frame (its mainId) wherever a node id goes, so addNode { parentId: "$intro" } builds inside that scene and updateNode { nodeId: "$intro", patch: { fill } } sets its background. updateScene and setActiveScene take scene: "$<ref>" in place of sceneIndex — pass exactly one of the two.
{
"templateId": "66f1…",
"operations": [
{ "op": "addScene", "ref": "intro", "duration": 2 },
{ "op": "updateNode", "nodeId": "$intro", "patch": { "fill": "#0f172a" } },
{ "op": "addNode", "type": "text", "ref": "hello", "parentId": "$intro", "props": { "text": "Hello", "x": 80, "y": 80, "fill": "#ffffff" } },
{ "op": "addScene", "ref": "outro", "duration": 3 },
{ "op": "addNode", "type": "text", "parentId": "$outro", "props": { "text": "Goodbye", "x": 80, "y": 80 } },
{ "op": "updateScene", "scene": "$intro", "patch": { "transition": { "type": "fade", "duration": 0.4 } } },
{ "op": "setKeyframes", "nodeId": "$hello", "tracks": { "opacity": [{ "t": 0, "v": 0 }, { "t": 0.6, "v": 1, "ease": "out" }] } }
]
}
- Each
addSceneresult carriessceneIndexandmainId. The batch result'srefsmaps a scene ref to itsmainId, andsceneRefsmaps it to its index ({ "intro": 1, "outro": 2 }), fortemplate_render { scene }and later calls. addScenemakes the new scene the active one, so a lateraddNodewithout aparentIdlands in it. PreferparentId: "$<ref>", which is explicit and works for any scene in the batch.- Node and scene refs share one namespace. A scene ref follows the same rules as a node ref (unique, declared earlier);
sceneonly accepts a scene ref — one fromaddScene, or a built-in one below. template_create's seedoperationsaccept scene refs as well.
Built-in refs for scenes that already exist
The scenes a template has before the batch runs need no ref: "$scene0", "$scene1", … is that scene's frame, and "$main" is the frame of the active scene. They work everywhere a scene ref does: in node-id slots and as scene on updateScene and setActiveScene. A new template has one scene, so template_create can style its first scene, fill it and add the rest of the video in a single call:
{
"name": "Launch video",
"width": 1080, "height": 1920,
"operations": [
{ "op": "updateNode", "nodeId": "$scene0", "patch": { "fill": "#101216" } },
{ "op": "updateScene", "scene": "$scene0", "patch": { "duration": 3 } },
{ "op": "addNode", "type": "text", "parentId": "$scene0", "props": { "text": "Paste a website", "x": 80, "y": 160, "fill": "#ffffff" } },
{ "op": "addScene", "ref": "kit", "duration": 4 },
{ "op": "addNode", "type": "text", "parentId": "$kit", "props": { "text": "Your brand kit", "x": 80, "y": 160 } }
]
}
- They are fixed when the batch starts: a later
addSceneorsetActiveScenein the same batch does not move$mainor renumber$sceneN. Scenes the batch adds are reached through their ownaddSceneref. mainandscene<N>are reserved: declaring them as arefrefuses the batch, and so does$sceneNpast the template's last scene.- They are not echoed in the result's
refs/sceneRefs, which list only the refs the batch declared.
Stacking order: zIndex
Siblings paint in list order: a later layer sits on top. zIndex (an integer from -9999 to 9999; unset counts as 0) lifts one layer over its siblings, or tucks it under them, without reordering the list. Higher paints over, equal values keep the list order, and null clears it. It changes paint and click order only: an auto-layout frame still places its children in list order, and a mask frame's mask is still its first child. Bind it so the stacking follows your data:
{ "op": "updateNode", "nodeId": "<card id>", "patch": { "bindings": { "zIndex": "featured === 'b' ? 10 : 0" } } }
setKeyframes takes a zIndex track too (it steps between whole numbers). zIndex is not z, the scene camera's depth.
blendMode sets how a layer mixes with what is behind it, as in the editor's Blend control: normal, multiply, screen, overlay, darken, lighten, difference, exclusion, soft-light or hard-light. "normal" or null clears it. The same patch takes the Effects values: blur and backdropBlur (px; 0 or null clears), brightness and saturation (1 = neutral) and the shadowX / shadowY / shadowBlur / shadowColor / shadowOpacity set. locked: true keeps a layer out of canvas selection and drags in the editor, the same as its lock in the Layers panel; it has no effect on renders, so use it for backgrounds and guides (false unlocks).
Kinetic type: per-letter, word and line animation
Stagger a headline's letters, words or lines with textAnimate on the text layer instead of building one layer per glyph:
{ "op": "updateNode", "nodeId": "ab12cd34", "patch": { "textAnimate": {
"unit": "char", "duration": 0.6, "stagger": 0.04,
"from": { "opacity": 0, "blur": 12, "y": 0.15 }
} } }
unitischar,wordorline. Unit i starts atstart + i × staggerseconds and animates fromfromto its resting place overduration.fromtakesopacity,x,y(multiples of the font size),scale,rot(degrees) andblur(px). It defaults to{ "opacity": 0, "y": 0.4 }.easetakes any keyframe ease (backfor a pop),orderisforward,reverse,centerorrandom, andout: { "at": 4 }plays it backwards as an exit."mask": trueclips each unit to its own resting box while it moves. That is the line reveal:{ "unit": "line", "mask": true, "from": { "y": 1.1 }, "ease": "back", "stagger": 0.12 }."spaces": "count"(letters only) gives each space a stagger slot, so the timing matches a CSS letter split of the same string. The default,"skip", gives spaces no slot."textAnimate": nullremoves it. Text layers only; HTML5 ad export refuses it. See Templates for the full contract.- Snapshots from
template_getgive every text layer read-onlylines: [{ x, y, w, h }](layer-local px), so you can place a layer right after the last line.
Variations: dark mode and other alternate looks
A variation is a named set of overrides over the same design — a dark theme, a seasonal palette, a compact layout, a hidden badge. Create and edit them with the setVariations operation:
{ "op": "setVariations",
"groups": [{ "name": "Theme", "type": "single-select" }],
"variations": [
{ "id": "dark", "name": "Dark", "group": "Theme",
"overrides": { "<frameId>.fill": "#0B0B0F", "<titleId>.fill": "#F5F5F5" } },
{ "id": "promo", "name": "Promo", "group": "Extras",
"overrides": { "<titleId>.text": "Promo: 30% off" } }
] }
- Keys are
"<nodeId>.<property path>", with node ids fromtemplate_get; nested paths go into arrays and objects that already exist ("<id>.fills.0.color"). A value may be a{{ }}binding, which resolves at render time like any other. - A variation can have its own camera shot:
"scene:<sceneId>.camera.<prop>"sets one camera value of that scene (x,y,zoom,rotX,rotY,persp,focus,apertureas numbers,enabledastrue/false; scene ids are intemplate_get). A scene without a camera starts from the defaults, and the value replaces that prop's camera keyframes while the variation applies. The editor's live copies beside the artboard show the design only, without the variation's camera; renders apply it. overridesmerge into the variation's existing ones;nulldeletes a key andreplaceOverrides: truestarts over. Omitidto create (the result returns it); pass it to edit.removeandremoveGroupsdelete.- Single-select groups hold mutually exclusive looks (Light / Dark): enabling one turns its siblings off, and a render cannot combine two of them (
VARIATION_CONFLICT). Multi-select groups stack. A group named on a variation that does not exist yet is created as multi-select. - The whole op fails, writing nothing, when an override names a layer or a nested path that does not exist.
- Render one with
template_render { variation: "dark" }or stack them with{ variation: ["dark", "promo"] }— later ones win on the same property. On a published template, adddraft: trueuntil the owner republishes: renders read the published version, which does not have a variation added since. The Render API, bulk renders and signed URLs take the same list (comma-separated in query strings). - Variations show as live copies beside the artboard in the editor, and the in-editor assistant uses the same operation.
Operations available to template_create and template_apply_ops: addNode, updateNode, moveNode, addScene, updateScene, setActiveScene, setArtboard, setKeyframes, clearKeyframes, setMainFrame, extractFrameToScene, groupIntoBoard, stageNode, selectNodes, setTime, setPlayback. The creative-authoring guide describes each.
Both tools refuse an argument they do not take, and nothing is written: the error names it and, for the usual guesses, where it belongs. For example, variables on template_create points you to a setVariables operation inside operations, and name on template_apply_ops points you to settings.
A few defaults differ from the editor's tools:
- A frame added by an operation starts with no padding and no clipping. Set
padX,padYandclipwhen you want them. Auto layout keeps agapof 12. - Gradient stops take
posfrom 0 to 1. Anoffsetis stored aspos, and a stop with neither is refused. - Shadows go in
effectsas{ "type": "dropShadow", "x", "y", "blur", "color", "opacity" }. - A shader layer's
shaderUniformstake a colour as"#rrggbb"and a choice by option name. An input the shader does not have, or an option it does not offer, fails the call and lists what it has. moveNodetakespositionbeforeorafterto reorder siblings (the order an auto-layout row or column lays them out in).aboveandbeloware the layer stack, sobelowputs a layer before its target in a row.- A colour written as an expression (
fill,stroke, …) takes up to 200 characters. Put a longer one inbindings, which takes 500.
template_create, template_apply_ops and template_delete return a short snapshot by default: every layer's id, type and name, nested, plus the scenes. Pass "snapshot": "full" for every property (what template_get returns) or "none" to leave it out.
Master layers
A master layer plays over every scene on the master clock — cross-scene music, a logo that stays put through the whole video. addNode { type, dest: "master", props } creates one (it is always top-level, so parentId is refused; without x/y it sits at the artboard's top-left). stageNode { nodeId, dest: "master" } promotes an existing scene layer, keeping its position, and stageNode { nodeId, dest: "scene" } moves a master layer back into the active scene's frame. Scene frames and layers inside a composition or component cannot be promoted. Snapshots list master layers under master. In the editor they appear in the Master view and under Master · every scene in each scene's layer tree, where Move to Master / Move to this scene do the same as stageNode.
Components
Anything that repeats — a lower third, a caption bar, a button, a product card, an end card — is one component and many instances. Build the parts first, then assemble the design or the video from instances:
addNode { type: "frame", dest: "scratch", props: { name, w, h, isComponent: true } }makes the master and parks it beside the artboard, so it never exports by itself.updateNode { isComponent: true }promotes a frame you already built.- Add its children with
parentIdset to the master. addNode { type: "instance", props: { componentId, x, y } }places it in any scene. Size defaults to the master's; withoutx/yit is centred in the scene frame.overrides: { "<master child id>": { text, fill, src, visible } }varies one instance. OnupdateNodethe map merges into the stored one: anullprop drops that override, anullchild drops all of that child's, andreplaceOverrides: truestarts from empty. A child id the master doesn't have is refused.
Editing the master updates every instance in every scene. Keyframes inside the master play in each instance on that scene's clock. timeOffset (seconds) delays one instance's copy of that animation, so three cards with 0, 0.15 and 0.3 animate in one after another. Keyframes on the instance move it as a whole. Detaching an instance keeps its timing: the copied keyframes are shifted by its offset. Snapshots list masters under components with their instance counts. A master can't contain an instance of itself, and it can't go back to a plain frame while instances use it. In the editor, components are listed in the Components panel on the left.
Lists and multi-page PDFs
A row that repeats per data item is a layer with repeat (a collection expression such as {{ items }}) and repeatAs (the per-item name, default item); {{ item.name }} and {{ index }} resolve per clone, and if drops a layer when its expression is falsy. Inside a column auto-layout frame the clones stack. repeatStagger (seconds) starts each clone's animation that much after the one before it, so a list animates in row by row; 0 or null clears it.
A whole page can repeat too: updateScene takes the same keys on a scene. repeat turns the one scene into a page per item — a carousel with a slide per entry, a deck with a page per product — repeatAs names the item, and if drops a scene (on a repeated scene, per item) when it is falsy. "" clears any of them. The scene name may be templated:
[
{ "op": "setVariables", "variables": [{ "name": "slides", "type": "array", "label": "Slides", "default": [{ "title": "Plan", "body": "…" }, { "title": "Build", "body": "…" }] }] },
{ "op": "addNode", "type": "text", "props": { "text": "{{ slide.title }}", "x": 80, "y": 360, "w": 920, "fontSize": 96 } },
{ "op": "addNode", "type": "text", "props": { "text": "{{ index + 1 }}", "x": 80, "y": 80 } },
{ "op": "updateScene", "sceneIndex": 0, "patch": { "name": "{{ slide.title }}", "repeat": "slides", "repeatAs": "slide" } }
]
template_get shows the one stored scene with its repeat, repeatAs and if; the pages exist when it renders. On every page {{ page.number }}, {{ page.index }}, {{ page.name }} and {{ pages.count }} resolve to that page's position and the final page count (a 3 / 7 counter; page and pages are reserved names — see Page tokens). template_render { scene: k } renders page k + 1, template_render { pages: "all" } renders every page as its own still (the result lists pageUrls: [{ index, name, url, fileId }], pages as their count and a zipUrl; one credit per page), a still template's format: "pdf" holds one page per item, template_sign_urls { pages: "all" } signs a keyless URL per page, and with settings: { pageView: "carousel" } the template page shows them side by side. See Pages from data.
A layer can also run across pages: updateNode { nodeId, patch: { spread: true } } on a layer that sits directly in a scene frame lays it out across the pages (one artboard apart plus settings.pageGap, side by side when settings.pageFlow is row), so give it an x past its own page. Every page it reaches, in every render, prints the part that falls on it. It stacks by its zIndex like any layer (below 0 under that page's layers, above 0 over them); without one it goes under that page's layers when it sits at the bottom of its own page's stack, over them otherwise. See Spread layers.
When the list can outgrow the page — an invoice with 3 lines today and 30 tomorrow — switch on auto-pagination: give the scene frame a column auto-layout and set paginate on the scene:
[
{ "op": "updateNode", "nodeId": "<scene frame id>", "patch": { "layout": "column", "gapY": 12, "padY": 48 } },
{ "op": "updateScene", "sceneIndex": 0, "patch": { "paginate": { "enabled": true, "maxPages": 20, "marginTop": 0, "marginBottom": 0 } } },
{ "op": "updateNode", "nodeId": "<footer id>", "patch": { "pageFixed": true } }
]
paginate.enabled— overflowing flow children break onto extra PDF pages at layer boundaries;maxPagescaps at 50,marginTop/marginBottominset the content region on every page;marginTopContinuedreplacesmarginTopon pages 2+ (page 1 keepsmarginTop, so a full-bleed header can reach the top of page 1).- Per-layer
updateNodeknobs:breakBefore: "page"(force a new page),keepWithNext: true(glue a heading to what follows),pageFixed: true(repeat the layer on every page, outside the flow — headers and footers; its text may use{{pageNumber}}and{{totalPages}}, and so may itsifandbindings, answered per page (if: "pageNumber > 1"shows it from page 2 on, with its height reserved only there); in the column flow it keeps its side of the rows on every page — above them when it precedes them in layer order, below otherwise — with its height reserved so rows never run underneath;absolute: truewith explicitx/ypins it anywhere), andflowRegion: trueon a column frame inside the scene frame to make it a flow region (regions chain in layer order like linked text frames; only column auto-layout frames accept it). template_getreports the scene'spaginatesettings and each layer's flags. Re-declaring a variable with a new default (setVariables) also updates its live value unless the user has customised it, so bumping an invoice's sampleitemsfrom 3 to 24 changes what the template page previews. Onlytemplate_renderwithformat: "pdf"produces the extra pages — the result'spagessays how many; every other format exports page 1.
Rendering
template_render runs the same pipeline as the Rendering API — variables, brand resolution, variation and still-target validation included — and costs the same credits (1 per still — a PDF 1 per page — and 5 per clip by default); an out-of-credits space gets an isError result saying so. Each result says what it cost (creditsCharged) and what the space has left (balanceAfter), so an agent sharing a space with other sessions can track its own spend. To render one template under several brands, pass brand per call rather than switching the template's brand with set_template_brand between renders — that rewrites the template and races with concurrent renders.
| Parameter | Meaning |
|---|---|
format | Stills: png (default), webp, svg, pdf. Video: mp4, webm, gif, or zip for a PNG frame sequence. |
scale | Resolution multiplier, 0.25–4. 2 doubles the pixel size. |
fps | Video only, 1–60. Default 30. |
quality | high (antialiased, default) or standard (faster, rougher). |
scene, frame | Still formats: which scene and frame index to capture. Default 0 / 0. |
nodeId | Still formats: render one top-level frame at its own size instead of the scene. Use an id from template_get. |
variables | Values for the template's variables by name — what {{ name }} resolves to. get_template lists them with types and defaults. |
variation | A saved variation, by name or id (from get_template), applied before rendering — or an array of them stacked in order (at most one per single-select group). |
draft | true renders the current document — your latest edits, new variations and samples, or a live editing session — instead of the published version. Default false: a published template renders its published snapshot; a never-published one always renders its draft. |
brandVariant | Campaign variant id or ids (e.g. ["xmas"]) to render under. By default this replaces whatever variants the brand has applied, so the output is deterministic. |
brandVariantMode | replace (default) or add — add layers brandVariant on top of what the brand already has applied. |
brandTokens | Token values to render with, replacing the resolved brand entirely — no brand lookup, no variants. Use it for "render exactly these colours"; usually brandVariant is what you want. The object is bounded: at most 64 KB serialised, 8 levels deep, 200 keys or items per object or array, 8 KB per string. Anything outside those limits is rejected with a validation error. |
The result is { templateId, format, url, mimeType, variation?, still?, pages?, warnings? } plus a resource_link to the file — warnings lists where the output differs from the editor ({ nodeId, name, reason }): layers skipped or drawn as a fallback, SVG/PDF layers rasterized or approximated, text exported mid-textAnimate, and pagination and soundtrack notes — see Rendering, and pages is the page count of a PDF (more than 1 when a scene auto-paginates, or when a still template has several scenes — see Multi-scene PDFs). A render goes through the same pipeline as POST /api/v1/templates/:id/render, is logged the same way, and fires the same render.completed webhook.
Icons in creatives
An icon is an svg node. Facet's svg node holds raw markup in props.svg; rather than fetch that yourself, pass an Iconify name as props.icon and the server resolves it to markup before the operation is applied:
{
"op": "addNode",
"type": "svg",
"parentId": "<frame id>",
"props": { "icon": "ph:calendar", "x": 40, "y": 40, "w": 24, "h": 24 }
}
updateNodealso acceptspatch.icon, to swap an existing svg node's glyph.- Recolour with
svgColors:{ "*": "#ffffff" }tints a monochrome icon;{ "#000000": "#ff0000" }replaces one colour. Bind to the brand with{ "*": "{{ brand.colors.primary }}" }— eachsvgColorsvalue is limited to 32 characters, so keep expressions short. - Find names with
search_icons(hyphenated keywords match best:arrow-right,map-pin),list_icon_collectionsandlist_icon_collection. - Do not use emoji in text nodes or an
imagenode as a stand-in for a vector icon, and do not hand-write markup when a name exists. - An unknown icon name fails the whole
template_apply_opscall with a tool error, so check the name withsearch_iconsfirst.
Brand tokens
Brands hold reusable design tokens (colors, typography, logos, images, icons, copy) that creatives reference as brand.<group>.<key> in node props — e.g. {{ use(brand.colors.primary, "#111111") }} in a fill, {{ use(brand.logos.logo, "…placeholder.png") }} in an image src. Always wrap a brand reference in use() with a raw fallback so the design survives a missing token; the template-expressions guide covers the helpers.
Manage them with create_brand and update_brand; use list_brands to find a brandId and get_brand to read current values before merging. resolve_brand turns a name, id or website URL into a brandId — with the default createFromUrl: true an unknown URL is fetched and a brand is created from it, so pass createFromUrl: false to only look up.
Tokens are grouped objects, e.g. liveTokens: { "colors": { "primary": "#6366f1" }, "typography": { "heading": "Space Grotesk" } }. Rendering uses draftTokens when it has any value (the in-app brand editor saves there), else liveTokens, else tokens. Writing liveTokens without draftTokens also sets draftTokens, so what you write is what renders. Each token group passed to update_brand replaces the stored one wholesale, so fetch and merge first. Campaign variants layer over the base tokens and are selected per render with brandVariant. External image URLs are re-hosted to the space automatically. Managing brands requires an API key associated with a user.
Prompts
The server publishes four MCP prompts; get_guide returns the same text for clients that do not read prompts:
Prompt / get_guide topic | Contents |
|---|---|
creative-authoring | The document model behind template_create and template_apply_ops: scenes, the scene frame, node types, coordinates, keyframes, compositions, parking and stills. |
template-expressions | How {{ }} expressions, variables, brand tokens, repeat / repeatAs / repeatOffset and if resolve at render time. |
brand-tokens | The token groups a brand carries, how creatives reference them, and how campaign variants layer over them. |
icons | Finding an Iconify icon and placing it as an svg node. |
Tool descriptions are kept short so tools/list stays small; read the guide before the first write.
Scoped keys
When you mint an API key you can restrict it to a list of MCP tools. The scope picker lists the tools in the tables above. A key restricted to a list gets a clean tool error (This API key is not permitted to use the "…" tool.) for anything outside it; an unrestricted key can call every tool except the opt-in posting tools below.
Opt-in tools
social_create_post and social_cancel_post act in public, so an unrestricted key cannot call them: they return an error telling you to enable them, and whoami's allowedTools leaves them out until you do. Open the key's tool scopes (Settings → Space → Developers) and tick them explicitly — alongside whichever other tools the agent needs. The two read tools (social_list_accounts, social_list_posts) follow the normal rule. Even with the tool enabled, the key's owner must still be an owner, admin or editor of the space, as in the app.
A read-only key for an assistant that only needs to browse and render, for example, would grant whoami, get_guide, list_templates, get_template, template_get and template_render.
Security notes
- Treat the API key like a password. Anything configured with it can read, edit and render your space's templates.
- A key acts as the member who created it, with that member's current role. Tools that write (
template_create,template_apply_ops,set_template_brand,template_sign_urls,template_delete,media_upload,create_brand,update_brand,create_collection,create_content,create_shader,update_shader, and the social and mockup tools) need the owner, admin or editor role at the time of the call — the same rule the app applies. A key whose owner was moved to a view-only role or removed from the space keeps reading but gets a "role does not allow this action" error on writes. - Avoid committing a real key in a project-level
.cursor/mcp.json. Prefer the global~/.cursor/mcp.json, or use a placeholder and fill it in locally. - Revoke a key anytime from Settings → Space → Developers.
- Do not put the key in a web page. Browser calls are limited to this app.
Related docs
- Integrations — All available Bannx integrations
- Authentication — API key creation and Bearer usage
- Templates — The editor and the Template API
- Rendering — Render formats, tweaks, and output modes
- Templates — Template API reference
- Brands — Brand tokens and campaign variants
- Agent skills — Installable skills that drive this server
- Mockups — Print a design onto a product photo with
mockup_prepare