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.

Server MCP Terhosting

npx add-mcp 'https://bannx.com/mcp'

Terpasang ke Claude Code, Codex, Cursor, dan lainnya

Dokumentasi

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:

  1. whoami — confirm the space, and see which tools this key may call (allowedTools).
  2. get_guide { "topic": "creative-authoring" } — the document model: scenes, the scene frame, node types, coordinates, keyframes. Read it before the first template_create.
  3. template_create — { "name": "Launch banner", "width": 1200, "height": 630, "brand": "Coca Cola" }. Take the templateId from the result. brand binds {{ brand.* }} to that brand (omit it to follow the space default; set_template_brand changes it later). You can seed the first scene with operations here too.
  4. template_get — read the snapshot. The scene's mainId is the scene frame; node ids are opaque 8-character strings and are only valid when they came from a snapshot. Never guess one.
  5. template_apply_ops — add and style nodes in one batch (example below). Use the nodeIds the result returns for later edits.
  6. template_render — { "templateId": "…", "format": "png", "variables": { "headline": "Ship faster" }, "brandVariant": ["xmas"] }.
  7. Open the returned url. The result also carries a resource_link so clients that render links can open it without parsing the JSON. When a script downloads it, send a User-Agent: Python's bare urllib (Python-urllib/3.x) is refused with 403 / error code: 1010, while requests, httpx, curl and fetch work 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

ToolDescriptionAccess
whoamiThe space, user and credit balance this key acts as. Call it first to confirm you are in the right space.Reads
get_guideRead one long-form guide by topic: creative-authoring, template-expressions, brand-tokens, icons.Reads

Templates

ToolDescriptionAccess
list_public_templatesBrowse 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_templateThe 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_templatesTemplates in the space, newest first: templateId, name, size, fps and whether there is a document to render.Reads
get_templateA 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

ToolDescriptionAccess
template_createCreate 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_getThe 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_opsApply 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_deleteRemove nodes (nodeIds) and/or whole scenes (sceneIndexes) from a creative. Cannot be undone from here.Destructive
delete_templatePermanently 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_renderRender 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_urlsMint 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_versionsA 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_saveSave 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_restoreRestore 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_brandAttach 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

ToolDescriptionAccess
media_uploadPut 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_prepareTurn 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).

ToolDescriptionAccess
social_list_accountsThe 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_postsPosts 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_postPost 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_postCancel 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:

  1. template_render { templateId, pages: "all", format: "png" } — one credit per page; each pageUrls[] entry carries a fileId.
  2. social_create_post { targets, text, fileIds: pageUrls.map(p => p.fileId), scheduledAt } — or pass the page urls as mediaUrls.

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_requested means an approver sent it back: the result's approval.note says why. Create a new post with the changes (the agent cannot edit the old one).
  • A post still unapproved at its time becomes expired and is never published.
  • social_cancel_post withdraws a waiting post.

Brands

ToolDescriptionAccess
list_brandsBrands in the space: id, name, and whether live or draft tokens exist.Reads
get_brandA brand with all its token groups (draftTokens, liveTokens, tokens) and campaign variants.Reads
resolve_brandTurn 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_brandCreate a brand with its token groups.Writes
update_brandChange a brand's name, tokens or campaign variants. Each token group you pass replaces the stored one whole.Writes (idempotent)

Content

ToolDescriptionAccess
list_collectionsContent collections in the space and their fields.Reads
create_collectionCreate a collection, or update one by collectionId. fields adds entry fields; existing fields are never changed or removed.Writes
list_contentsEntries in one collection, paginated.Reads
create_contentCreate an entry, or update one by contentId. publish: true publishes instead of saving a draft.Writes

Shaders

ToolWhat it doesAccess
list_shader_presetsThe 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_shadersThe space's shaders: id, name, status, declared inputs, cost. Find a shaderId here; never invent one.Reads
get_shaderOne shader's author source and input manifest, for editing.Reads
create_shaderAuthor 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_shaderChange 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

ToolDescriptionAccess
list_icon_collectionsThe Iconify icon sets available (prefix, name, size, samples). Phosphor (ph) is the house default.Reads
search_iconsFind icon names by keyword (query, optional prefix / prefixes). Returns names like ph:house.Reads
list_icon_collectionIcon 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 refs maps 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.
  • children is a list of { type, props, ref?, children? }. A parent must be a frame or board. Child x/y are relative to the parent. The result's childIds lists the new descendants depth-first.
  • w/h may be 0, as with the bar above, which grows from nothing. originX/originY take any finite number, so -3.2 scales 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: true to 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 addScene result carries sceneIndex and mainId. The batch result's refs maps a scene ref to its mainId, and sceneRefs maps it to its index ({ "intro": 1, "outro": 2 }), for template_render { scene } and later calls.
  • addScene makes the new scene the active one, so a later addNode without a parentId lands in it. Prefer parentId: "$<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); scene only accepts a scene ref — one from addScene, or a built-in one below.
  • template_create's seed operations accept 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 addScene or setActiveScene in the same batch does not move $main or renumber $sceneN. Scenes the batch adds are reached through their own addScene ref.
  • main and scene<N> are reserved: declaring them as a ref refuses the batch, and so does $sceneN past 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 }
} } }
  • unit is char, word or line. Unit i starts at start + i × stagger seconds and animates from from to its resting place over duration.
  • from takes opacity, x, y (multiples of the font size), scale, rot (degrees) and blur (px). It defaults to { "opacity": 0, "y": 0.4 }.
  • ease takes any keyframe ease (back for a pop), order is forward, reverse, center or random, and out: { "at": 4 } plays it backwards as an exit.
  • "mask": true clips 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": null removes it. Text layers only; HTML5 ad export refuses it. See Templates for the full contract.
  • Snapshots from template_get give every text layer read-only lines: [{ 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 from template_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, aperture as numbers, enabled as true/false; scene ids are in template_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.
  • overrides merge into the variation's existing ones; null deletes a key and replaceOverrides: true starts over. Omit id to create (the result returns it); pass it to edit. remove and removeGroups delete.
  • 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, add draft: true until 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, padY and clip when you want them. Auto layout keeps a gap of 12.
  • Gradient stops take pos from 0 to 1. An offset is stored as pos, and a stop with neither is refused.
  • Shadows go in effects as { "type": "dropShadow", "x", "y", "blur", "color", "opacity" }.
  • A shader layer's shaderUniforms take 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.
  • moveNode takes position before or after to reorder siblings (the order an auto-layout row or column lays them out in). above and below are the layer stack, so below puts 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 in bindings, 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:

  1. 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.
  2. Add its children with parentId set to the master.
  3. addNode { type: "instance", props: { componentId, x, y } } places it in any scene. Size defaults to the master's; without x/y it is centred in the scene frame.
  4. overrides: { "<master child id>": { text, fill, src, visible } } varies one instance. On updateNode the map merges into the stored one: a null prop drops that override, a null child drops all of that child's, and replaceOverrides: true starts 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; maxPages caps at 50, marginTop / marginBottom inset the content region on every page; marginTopContinued replaces marginTop on pages 2+ (page 1 keeps marginTop, so a full-bleed header can reach the top of page 1).
  • Per-layer updateNode knobs: 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 its if and bindings, 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: true with explicit x/y pins it anywhere), and flowRegion: true on 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_get reports the scene's paginate settings 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 sample items from 3 to 24 changes what the template page previews. Only template_render with format: "pdf" produces the extra pages — the result's pages says 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.

ParameterMeaning
formatStills: png (default), webp, svg, pdf. Video: mp4, webm, gif, or zip for a PNG frame sequence.
scaleResolution multiplier, 0.25–4. 2 doubles the pixel size.
fpsVideo only, 1–60. Default 30.
qualityhigh (antialiased, default) or standard (faster, rougher).
scene, frameStill formats: which scene and frame index to capture. Default 0 / 0.
nodeIdStill formats: render one top-level frame at its own size instead of the scene. Use an id from template_get.
variablesValues for the template's variables by name — what {{ name }} resolves to. get_template lists them with types and defaults.
variationA 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).
drafttrue 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.
brandVariantCampaign 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.
brandVariantModereplace (default) or add — add layers brandVariant on top of what the brand already has applied.
brandTokensToken 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 }
}
  • updateNode also accepts patch.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 }}" } — each svgColors value is limited to 32 characters, so keep expressions short.
  • Find names with search_icons (hyphenated keywords match best: arrow-right, map-pin), list_icon_collections and list_icon_collection.
  • Do not use emoji in text nodes or an image node 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_ops call with a tool error, so check the name with search_icons first.

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 topicContents
creative-authoringThe document model behind template_create and template_apply_ops: scenes, the scene frame, node types, coordinates, keyframes, compositions, parking and stills.
template-expressionsHow {{ }} expressions, variables, brand tokens, repeat / repeatAs / repeatOffset and if resolve at render time.
brand-tokensThe token groups a brand carries, how creatives reference them, and how campaign variants layer over them.
iconsFinding 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