{"openapi":"3.1.0","info":{"title":"Bannx API","version":"1","description":"Render design templates to images, video and PDF; run workflows; read brands; bulk jobs. Every error carries a stable `data.code` — see https://bannx.com/docs/errors. Guides: https://bannx.com/docs (markdown: append `.md` or send `Accept: text/markdown`).","contact":{"url":"https://bannx.com/docs"}},"servers":[{"url":"https://bannx.com"}],"externalDocs":{"url":"https://bannx.com/docs/api","description":"API reference"},"tags":[{"name":"Brands"},{"name":"Verified documents"},{"name":"Integrations"},{"name":"Content"},{"name":"Creatives"},{"name":"Templates"},{"name":"Workflows"}],"paths":{"/api/v1/brands/{id}":{"get":{"operationId":"getBrand","summary":"Get a brand","description":"Fetch one brand by ID. Public brands (publicOn set) need no auth; private brands require a dashboard session in the owning space. For API-key access use the MCP server (get_brand).","tags":["Brands"],"parameters":[{"in":"path","name":"id","required":true,"description":"Brand ID","schema":{"type":"string"}}],"responses":{"200":{"description":"JSON { doc } — the brand with its token sets"},"404":{"description":"Not found or not accessible"}},"security":[{"bearerAuth":[]},{"apiTokenQuery":[]}]}},"/api/v1/brands":{"get":{"operationId":"listBrands","summary":"List brands","description":"List brands in the current space. Session-authenticated (dashboard login); pass ?public=true to list public brands anonymously. For API-key access use the MCP server (list_brands).","tags":["Brands"],"parameters":[{"in":"query","name":"page","required":false,"description":"Page number (default 1)","schema":{"type":"string"}},{"in":"query","name":"perPage","required":false,"description":"Items per page (default 50)","schema":{"type":"string"}},{"in":"query","name":"public","required":false,"description":"\"true\" to list public brands without auth","schema":{"type":"string"}}],"responses":{"200":{"description":"JSON { list, count, pagesCount } of brands"},"401":{"description":"Not logged in (when public is not set)"}},"security":[{"bearerAuth":[]},{"apiTokenQuery":[]}]}},"/api/v1/credentials/{publicId}":{"get":{"operationId":"getPublicCredential","summary":"Verify a document","description":"Check a verified document (certificate, ID card, event badge) by the id in its QR code or verify link (`/verify/{publicId}`). No authentication. Returns the document's status — `valid`, `expired` (past `expiresAt`), `revoked` (by the issuer, with the reason they gave), `replaced` (a newer document of the same holder, see `replacedBy`) or `suspended` (bannx suspended the issuer; fields are withheld) — with the public fields the issuer chose to show, frozen when it was issued, and who issued it. `issuer.verifiedDomain` is set only while the issuer has proved control of that domain over DNS. Unknown ids get the same 404 as deleted ones. Responses may be cached for 30 seconds.","tags":["Verified documents"],"parameters":[{"in":"path","name":"publicId","required":true,"description":"The document's public id: 22 letters and digits, as printed in its verify link.","schema":{"type":"string"}}],"responses":{"200":{"description":"The document's public view."},"404":{"description":"No such document (CREDENTIAL_NOT_FOUND) — the same answer for unknown, mistyped and deleted ids."},"429":{"description":"Too many lookups from this address (RATE_LIMITED)."}},"security":[{"bearerAuth":[]},{"apiTokenQuery":[]}]}},"/api/v1/credentials/{publicId}/report":{"post":{"operationId":"reportPublicCredential","summary":"Report a document","description":"Flag a verified document as suspicious — it looks fake, it belongs to someone else, or the issuer is impersonating an organisation. No authentication. The issuer and bannx see the report; nothing in it is shown publicly. At most 5 reports an hour from one address, and one per document per day (a repeat is accepted and dropped).","tags":["Verified documents"],"parameters":[{"in":"path","name":"publicId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}},"security":[{"bearerAuth":[]},{"apiTokenQuery":[]}]}},"/api/v1/integrations/hooks/{id}":{"delete":{"operationId":"integrationsUnsubscribeHook","summary":"Unsubscribe from an event (integrations)","description":"Removes a subscription made with `POST /api/v1/integrations/hooks`, the way Zapier unsubscribes when a Zap turns off. Only removes subscriptions an integration created, in the key's space. Bearer API key with the `webhook.manage` scope.","tags":["Integrations"],"parameters":[{"in":"path","name":"id","required":true,"description":"Subscription id returned on subscribe.","schema":{"type":"string"}}],"responses":{"200":{"description":"JSON { ok: true, id }"},"401":{"description":"Missing or invalid API key, or the key lacks the webhook.manage scope (SCOPE_DENIED)."},"403":{"description":"The key's user may not manage webhooks in the space (FORBIDDEN)."},"404":{"description":"No integration subscription with that id in the key's space (HOOK_NOT_FOUND)."}},"security":[{"bearerAuth":[]},{"apiTokenQuery":[]}]},"get":{"operationId":"integrationsGetHook","summary":"Get an event subscription (integrations)","description":"Reads a subscription made with `POST /api/v1/integrations/hooks`, so an automation platform can check it still exists before reusing it. 404 means it was removed (in Settings → Developers, or by an unsubscribe) and should be created again. Never returns the signing secret. Bearer API key with the `webhook.manage` scope.","tags":["Integrations"],"parameters":[{"in":"path","name":"id","required":true,"description":"Subscription id returned on subscribe.","schema":{"type":"string"}}],"responses":{"200":{"description":"JSON { id, event, targetUrl, enabled, templateId?, platform?, signed }"},"401":{"description":"Missing or invalid API key, or the key lacks the webhook.manage scope (SCOPE_DENIED)."},"403":{"description":"The key's user may not manage webhooks in the space (FORBIDDEN)."},"404":{"description":"No integration subscription with that id in the key's space (HOOK_NOT_FOUND)."}},"security":[{"bearerAuth":[]},{"apiTokenQuery":[]}]}},"/api/v1/integrations/hooks":{"post":{"operationId":"integrationsSubscribeHook","summary":"Subscribe to an event (integrations)","description":"Registers an automation platform's URL for an event, the way Zapier REST hooks subscribe when a Zap turns on. bannx then POSTs `{ id, event, timestamp, spaceId, data }` to `targetUrl` each time the event happens in the key's space; for `render.completed`, `data` holds `templateId`, `format` and `url`. Bearer API key with the `webhook.manage` scope, whose user may manage webhooks in the space. `targetUrl` must be a public HTTPS URL. `templateId` is stored with the subscription so the platform can filter; delivery is not filtered.","tags":["Integrations"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["targetUrl","event"],"properties":{"targetUrl":{"type":"string","description":"Public HTTPS URL that receives the events."},"event":{"type":"string","enum":["render.completed"],"description":"Event to subscribe to."},"templateId":{"type":"string","description":"Optional template the subscriber cares about."},"platform":{"type":"string","description":"Who is subscribing, shown in Settings → Developers. Default \"integration\"."},"secret":{"type":"string","description":"Optional, 16-200 characters. bannx then signs each delivery with `X-Webhook-Signature: sha256=<hex HMAC-SHA256 of the raw body>` so the receiver can verify it came from bannx."}}}}}},"responses":{"200":{"description":"JSON { id, event, targetUrl } — keep `id` to unsubscribe."},"400":{"description":"targetUrl is not a public HTTPS URL, or the space has too many integration subscriptions (VALIDATION)."},"401":{"description":"Missing or invalid API key, or the key lacks the webhook.manage scope (SCOPE_DENIED)."},"403":{"description":"The key's user may not manage webhooks in the space (FORBIDDEN)."}},"security":[{"bearerAuth":[]},{"apiTokenQuery":[]}]}},"/api/v1/integrations/me":{"get":{"operationId":"integrationsMe","summary":"Who am I (integrations)","description":"Checks an API key and names the space it opens. Automation platforms (Zapier, Make, n8n) call it when a user connects bannx, and show `spaceName` as the connection label. Any valid key works; `scopes.apiEndpoints` lists the REST scopes the key carries (absent = every scope).","tags":["Integrations"],"responses":{"200":{"description":"The key's space."},"401":{"description":"Missing or invalid API key (AUTH_REQUIRED, TOKEN_INVALID, TOKEN_EXPIRED)."}},"security":[{"bearerAuth":[]},{"apiTokenQuery":[]}]}},"/api/v1/integrations/renders":{"get":{"operationId":"integrationsRecentRenders","summary":"Recent renders (integrations)","description":"The key's space's latest successful renders, newest first, each shaped like a `render.completed` event: `{ id, event, templateId, format, url, timestamp }`. Automation platforms use it as sample data for a \"New render\" trigger. Bearer API key with the `template.read` scope.","tags":["Integrations"],"parameters":[{"in":"query","name":"templateId","required":false,"description":"Only renders of this template.","schema":{"type":"string"}},{"in":"query","name":"limit","required":false,"description":"1-50. Default 3.","schema":{"type":"string"}}],"responses":{"200":{"description":"JSON { list: [{ id, event, templateId, format, url, timestamp }] }"},"401":{"description":"Missing or invalid API key, or the key lacks the template.read scope (SCOPE_DENIED)."}},"security":[{"bearerAuth":[]},{"apiTokenQuery":[]}]}},"/api/v1/integrations/templates/{id}/fields":{"get":{"operationId":"integrationsTemplateFields","summary":"Template fields (integrations)","description":"A template's variables as form fields — key, label, type, required, default and choices — so an automation platform can build the render form. Bearer API key with the `template.read` scope. Types: string, text (long text), number, integer, boolean, image (an image URL), color, list and object (both sent as JSON text, or a list as comma-separated text). Also says whether the template animates, so the form can default to a video format, and lists its saved variations.","tags":["Integrations"],"parameters":[{"in":"path","name":"id","required":true,"description":"Template ID","schema":{"type":"string"}}],"responses":{"200":{"description":"JSON { id, name, width, height, animated, durationSeconds, fields: [{ key, label, type, required, default?, helpText?, choices? }], variations: [{ id, name }] }"},"401":{"description":"Missing or invalid API key, or the key lacks the template.read scope (SCOPE_DENIED)."},"404":{"description":"No template with that id in the key's space (TEMPLATE_NOT_FOUND)."}},"security":[{"bearerAuth":[]},{"apiTokenQuery":[]}]}},"/api/v1/integrations/templates/{id}/render":{"post":{"operationId":"integrationsRenderWithCallback","summary":"Render a template (integrations)","description":"Renders like `POST /api/v1/templates/{id}/render` and takes the same fields except `raw`, but `variables` may be form text: each value is converted to its variable's type (numbers, booleans, a list as JSON or comma-separated text, an object as JSON), undeclared names are dropped and empty values keep the template's default. Without `callbackUrl` the answer is the render route's JSON. With `callbackUrl` it answers 202 at once and POSTs that JSON to `callbackUrl` when the render finishes, or `{ ok: false, templateId, error: { code, message, status } }` when it fails: for clips that outlast an automation platform's step limit. `callbackUrl` must be a public HTTPS URL. A server restart mid-render loses an async render and no callback arrives. Bearer API key with the `template.render` scope; costs what the same render costs.","tags":["Integrations"],"parameters":[{"in":"path","name":"id","required":true,"description":"Template ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"callbackUrl":{"type":"string","description":"Public HTTPS URL that receives the render result. Omit to render and answer in one request."},"format":{"type":"string","description":"Output format, as on the render route. Default png."},"variables":{"type":"object","description":"Variable values by name; text is converted to each variable's type."}}}}}},"responses":{"200":{"description":"Without callbackUrl: the render route's JSON { ok, templateId, format, url, creditsCharged, balanceAfter, … }."},"202":{"description":"With callbackUrl: JSON { ok: true, status: \"rendering\", templateId } — the result arrives at callbackUrl."},"400":{"description":"callbackUrl is not a public HTTPS URL (VALIDATION)."},"401":{"description":"Missing or invalid API key, or the key lacks the template.render scope (SCOPE_DENIED)."},"404":{"description":"No template with that id in the key's space (TEMPLATE_NOT_FOUND)."}},"security":[{"bearerAuth":[]},{"apiTokenQuery":[]}]}},"/api/v1/integrations/templates":{"get":{"operationId":"integrationsListTemplates","summary":"List templates (integrations)","description":"The key's space templates, most recently updated first, for a template picker on an automation platform. Bearer API key with the `template.read` scope. `search` matches the name or description.","tags":["Integrations"],"parameters":[{"in":"query","name":"search","required":false,"description":"Text the name or description contains.","schema":{"type":"string"}},{"in":"query","name":"page","required":false,"description":"1-based page. Default 1.","schema":{"type":"string"}},{"in":"query","name":"perPage","required":false,"description":"Rows per page, 1-100. Default 50.","schema":{"type":"string"}}],"responses":{"200":{"description":"JSON { list: [{ id, name, description, type, width, height, updatedOn }], count, page, perPage, pagesCount }"},"401":{"description":"Missing or invalid API key, or the key lacks the template.read scope (SCOPE_DENIED)."}},"security":[{"bearerAuth":[]},{"apiTokenQuery":[]}]}},"/api/v1/public/content/{collection}/{slug}":{"get":{"operationId":"publicGetContentBySlug","summary":"Get an entry","description":"Read a single PUBLISHED entry by slug. Authenticate with a content.read API key (Authorization: Bearer …). The slug is matched against the collection's configured preview.slugField (defaults to \"slug\"). Only liveData is returned; use ?depth= to resolve references and ?variants= for personalization.","tags":["Content"],"parameters":[{"in":"path","name":"collection","required":true,"description":"The collection's API name","schema":{"type":"string"}},{"in":"path","name":"slug","required":true,"description":"The entry slug","schema":{"type":"string"}},{"in":"query","name":"depth","required":false,"description":"Resolve reference fields to this depth (default 0)","schema":{"type":"string"}},{"in":"query","name":"variants","required":false,"description":"Comma-separated variant ids; returns personalization-resolved values","schema":{"type":"string"}}],"responses":{"200":{"description":"JSON { doc } — the published entry"},"401":{"description":"Missing or invalid API token"},"404":{"description":"Collection or entry not found"}},"security":[{"bearerAuth":[]},{"apiTokenQuery":[]}]}},"/api/v1/public/content/{collection}":{"get":{"operationId":"publicListContent","summary":"List entries","description":"List PUBLISHED entries in a collection. Authenticate with a content.read API key (Authorization: Bearer …). Only liveData is returned — never drafts. Values under `data` are keyed by field API name. Supports pagination, reference resolution (?depth=), and personalization (?variants=).","tags":["Content"],"parameters":[{"in":"path","name":"collection","required":true,"description":"The collection's API name","schema":{"type":"string"}},{"in":"query","name":"page","required":false,"description":"Page number (default 1)","schema":{"type":"string"}},{"in":"query","name":"perPage","required":false,"description":"Items per page (default 20)","schema":{"type":"string"}},{"in":"query","name":"depth","required":false,"description":"Resolve reference fields to this depth (default 0)","schema":{"type":"string"}},{"in":"query","name":"variants","required":false,"description":"Comma-separated variant ids; returns personalization-resolved values","schema":{"type":"string"}}],"responses":{"200":{"description":"JSON { list, count, pagesCount } of published entries"},"401":{"description":"Missing or invalid API token"},"404":{"description":"Collection not found"}},"security":[{"bearerAuth":[]},{"apiTokenQuery":[]}]}},"/api/v1/templates/{id}/bulk":{"post":{"operationId":"creativeBulkApi","summary":"Bulk render","description":"Render one file per row of `rows` (each row is variable values by name) and pack them into a ZIP — or, with `format: \"pdf\"` and `output: \"pdf\"`, merge every row into one PDF. Queued: the response is a job id — poll `GET /api/v1/templates/bulk/{jobId}` for progress and the download URL. Bearer API key with the `template.render` scope; credits for every row are reserved up front.","tags":["Creatives"],"parameters":[{"in":"path","name":"id","required":true,"description":"Template ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rows"],"properties":{"rows":{"type":"array","items":{"type":"object"},"description":"One object per output: variable values by name. Optional `id` / `name` keys name the file; a reserved `_filename` key sets the file name exactly (no extension, never passed to the template). Reserved `_variation` (a saved variation id or name, or several comma-separated) renders that row with its own variation in place of the run's; `_scene` (still formats, counted from 0) renders that page of the row instead of the first. A dotted key fills part of an object or list variable (`to.name`, `items.0.qty`) and keeps the template's saved values for the rest; a string holding JSON (`{…}` / `[…]`) fills an object or list variable. Max 500."},"format":{"type":"string","enum":["png","webp","svg","pdf","mp4","webm","gif"],"description":"Output format for every row. Default png."},"pages":{"type":"string","enum":["all"],"description":"`all`: every page of a still template as its own file, per row (`<row>-01-<page>.png`, …), each page costing a still's credits. png, webp or svg only, and not with a row `_scene`."},"output":{"type":"string","enum":["zip","pdf"],"description":"`zip` (default): one file per row in a ZIP. `pdf`: every row's pages merged, in row order, into one PDF — only with `format: \"pdf\"` (VALIDATION otherwise). Rows that fail are left out and listed in `errors`."},"dpi":{"type":"integer","minimum":72,"maximum":1200,"description":"PDF only: page size = pixels × 72 / dpi. Unset: the template's export default, else 300 on a print size (A4, Letter, business card, 4×6 label…) so the PDF comes out at paper size, else 72 (1 px = 1 pt)."},"scale":{"type":"number","minimum":0.1,"maximum":4,"description":"Resolution multiplier. Default 1."},"size":{"type":"string","description":"Render every row at another size: a size preset id or WIDTHxHEIGHT (see the single render's `size`). A row may override it with a reserved `_size` field (and `_fit`), e.g. one record as a story and another as a square in the same run."},"fit":{"type":"string","enum":["reflow","scale"],"description":"How the design adapts to `size`. Default reflow."},"fps":{"type":"integer","minimum":1,"maximum":60,"description":"Video formats only."},"quality":{"type":"string","enum":["low","medium","high"]},"variation":{"type":"string","description":"Saved variation (id, or its name as the editor shows it) to apply to every row — or several, as a JSON array or comma-separated string, stacked in order (at most one per single-select group). A row's `_variation` replaces it."},"variants":{"type":"array","maxItems":10,"items":{"type":"string","description":"A variation id or name; a list of them (or a comma-separated string) to combine in one file; or \"\" for the row as it is set."},"description":"Render every row once per look: N rows × M looks = N × M files (at most 1000). Each entry is a variation id or name, or several to combine in one file (an array, or comma-separated), stacked on top of the row's `_variation` (else the run's `variation`); `\"\"` is the row as it is set. Files are named `<row>-<look name>` (the `\"\"` look keeps `<row>`), each costing a render."},"brand":{"type":"string","description":"Render every row under another brand of the key's space — a brandId, brand name or website URL. The template keeps its own brand. Another space's brand is BRAND_NOT_FOUND."}}}}}},"responses":{"200":{"description":"JSON { jobId, total }"},"401":{"description":"Missing or invalid API key, or the key lacks the template.render scope"},"402":{"description":"Not enough credits for the batch"},"404":{"description":"Template not found in the key's space, or `brand` names no brand of it (BRAND_NOT_FOUND)"},"409":{"description":"`brand` matches several brands (BRAND_AMBIGUOUS)"},"422":{"description":"Invalid body (VALIDATION), e.g. `output: \"pdf\"` with a format other than pdf"}},"security":[{"bearerAuth":[]},{"apiTokenQuery":[]}]}},"/api/v1/templates/{id}/render":{"get":{"operationId":"creativeRenderApiGet","summary":"Render a template (GET)","description":"Render a template by ID from the URL alone: options and variables as query parameters, the file streamed back by default (`output=json` stores it and returns `{ url }`). Every query key that is not a render option is a template variable, e.g. `?title=Hello&count=3`; `variables` may also be a JSON object string, and `var.<name>` / `variables[<name>]` name a variable that collides with an option. Auth: `Authorization: Bearer` or `?api_token=` — a key in the URL must be scoped to the Template Render API only (a render-only key), so leaking the URL leaks nothing else.","tags":["Creatives"],"parameters":[{"in":"path","name":"id","required":true,"description":"Template ID","schema":{"type":"string"}},{"in":"query","name":"api_token","required":false,"description":"A render-only API key (endpoint scope exactly template.render, no MCP tools). Alternative to the Authorization header.","schema":{"type":"string"}},{"in":"query","name":"format","required":false,"description":"png (default), webp, svg, pdf, webm, mp4, gif, zip, html5","schema":{"type":"string"}},{"in":"query","name":"clickUrl","required":false,"description":"Required for html5: absolute HTTP(S) destination URL","schema":{"type":"string"}},{"in":"query","name":"loops","required":false,"description":"HTML5 repetitions: 1–10, default 1","schema":{"type":"string"}},{"in":"query","name":"network","required":false,"description":"HTML5 network preset: generic (default), google-ads, dv360, cm360, amazon-dsp, adroll","schema":{"type":"string"}},{"in":"query","name":"output","required":false,"description":"`json` to store the file and return { url, timings } instead of the bytes","schema":{"type":"string"}},{"in":"query","name":"scale","required":false,"description":"Resolution multiplier 0.25–4","schema":{"type":"string"}},{"in":"query","name":"quality","required":false,"description":"standard | high","schema":{"type":"string"}},{"in":"query","name":"scene","required":false,"description":"Still formats: scene index. Omit on a pdf of a still (non-animated) template to get every scene as a page.","schema":{"type":"string"}},{"in":"query","name":"frame","required":false,"description":"Still formats: frame index within the scene","schema":{"type":"string"}},{"in":"query","name":"nodeId","required":false,"description":"Still formats: render one layer","schema":{"type":"string"}},{"in":"query","name":"variation","required":false,"description":"Saved variation id, or several comma-separated (stacked in order; at most one per single-select group)","schema":{"type":"string"}},{"in":"query","name":"brand","required":false,"description":"Render with another brand of the key's space for this render only: a brandId, brand name or the brand's website URL. The template keeps its own brand. Another space's brand is BRAND_NOT_FOUND (404); a name matching several brands is BRAND_AMBIGUOUS (409).","schema":{"type":"string"}},{"in":"query","name":"brandVariant","required":false,"description":"Brand campaign variant id(s), comma-separated","schema":{"type":"string"}},{"in":"query","name":"draft","required":false,"description":"`true` renders the current document instead of the published version","schema":{"type":"string"}},{"in":"query","name":"size","required":false,"description":"Another output size: a preset id (og, story, leaderboard, …) or WIDTHxHEIGHT; the template is not changed","schema":{"type":"string"}},{"in":"query","name":"fit","required":false,"description":"reflow (default) | scale — how the design adapts to `size`","schema":{"type":"string"}},{"in":"query","name":"dpi","required":false,"description":"PDF only: print resolution 72–1200 (page = pixels × 72 / dpi points). Default: the template's exportDefaults.dpi, else 300 on a print-size template, else 72","schema":{"type":"string"}},{"in":"query","name":"variables","required":false,"description":"JSON object of variables (optional — bare keys work too)","schema":{"type":"string"}}],"responses":{"200":{"description":"The rendered file (default; `x-credits-charged` / `x-credits-balance` headers carry what it cost, and on a template with verified documents on `x-credential-id` / `x-credential-url` name the document it issued), or JSON { ok, templateId, format, url, timings, creditsCharged, balanceAfter, brand?, credential? } with output=json — `credential` { id, url, code, reused } is the verified document this render issued"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key lacks the template.render scope, or a URL key is not render-only, or the space's verified documents are suspended (CREDENTIALS_SUSPENDED)"},"404":{"description":"Template not found in the key's space, or `brand` names no brand of the key's space (BRAND_NOT_FOUND)"},"409":{"description":"`brand` matches several brands of the space (BRAND_AMBIGUOUS)"}},"security":[{"bearerAuth":[]},{"apiTokenQuery":[]}]},"post":{"operationId":"creativeRenderApi","summary":"Render a template","description":"Render a creative template by ID to png, webp, svg, pdf, webm, mp4, gif, zip (frame sequence), or html5 (standalone ad ZIP), with variable overrides. Bearer API key with the `template.render` scope. `{{ brand.* }}` resolves against `brand` when given (another brand of the key's space, for this render only), else the template's brand, else the space default. Returns `{ url, creditsCharged, balanceAfter }` with the uploaded render (plus `credential` when the template has verified documents on); `raw: true` (or `?format=binary`) streams the bytes instead. Send an `Idempotency-Key` header to retry safely: the same key with the same request within 24 hours returns the first JSON answer again (header `Idempotent-Replayed: true`) without rendering or charging again.","tags":["Creatives"],"parameters":[{"in":"path","name":"id","required":true,"description":"Template ID","schema":{"type":"string"}},{"in":"header","name":"Idempotency-Key","required":false,"description":"Optional, 1-255 printable ASCII characters, kept 24 hours per space. A retry with the same key and the same request returns the first JSON answer without rendering or charging again. The same key with a different request, while the first is still running, or after a raw render is IDEMPOTENCY_CONFLICT (409, `data.reason`).","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"format":{"type":"string","enum":["png","webp","svg","pdf","webm","mp4","gif","zip","html5"],"description":"Output format. Default png."},"clickUrl":{"type":"string","description":"Required for html5: HTTP(S) click-through URL."},"loops":{"type":"integer","minimum":1,"maximum":10,"description":"HTML5 playback repetitions. Default 1."},"network":{"type":"string","enum":["generic","google-ads","dv360","cm360","amazon-dsp","adroll"],"description":"HTML5 ad network preset the report is judged against. Default generic."},"variables":{"type":"object","description":"Variable overrides by name."},"scale":{"type":"number","minimum":0.25,"maximum":4,"description":"Resolution multiplier. Default 1."},"fps":{"type":"integer","minimum":1,"maximum":60,"description":"Frames per second for video formats. Default 30."},"quality":{"type":"string","enum":["standard","high"],"description":"Render quality tier. Default from the template, else high."},"scene":{"type":"integer","description":"Still formats: scene index to render. Omit on a pdf of a still (non-animated) template to get every scene as a page."},"frame":{"type":"integer","description":"Still formats: frame index within the scene."},"nodeId":{"type":"string","description":"Still formats: render one layer instead of the artboard."},"variation":{"type":"string","description":"Saved variation id to apply before rendering — or several, as a JSON array or a comma-separated string, stacked in order: later wins on the same property; at most one per single-select group (VARIATION_CONFLICT)."},"brandVariant":{"type":"array","items":{"type":"string"},"description":"Brand campaign variant ids to render under. Replaces whatever the brand currently has active, so the result is deterministic. Accepts a single id or a comma-separated string too."},"brandVariantMode":{"type":"string","enum":["replace","add"],"description":"How brandVariant combines with the brand's active set. Default replace."},"brandTokens":{"type":"object","description":"Brand token values to render with, REPLACING the resolved brand. Use it to render exactly what a preview shows, unsaved edits included. Bounded in size and depth. Exclusive with `brand`."},"brand":{"type":"string","description":"Render with another brand of the key's space for this render only — a brandId, brand name or the brand's website URL (matched, never fetched). The template keeps its own brand, so concurrent renders under different brands do not race. Another space's brand (public catalog included) is BRAND_NOT_FOUND; a name matching several brands is BRAND_AMBIGUOUS with `data.candidates`."},"draft":{"type":"boolean","description":"Render the current (unpublished) document instead of the published version. Default false: a published template renders its published snapshot; a never-published one renders its draft."},"size":{"type":"string","description":"Render at another size without changing the template: a size preset id (e.g. \"og\", \"story\", \"leaderboard\") or \"WIDTHxHEIGHT\" (16–8192 px a side, 64 MP max); an object { preset } or { width, height } is accepted too. The response echoes `size: { width, height, fit, preset?, from }`."},"fit":{"type":"string","enum":["reflow","scale"],"description":"How the design adapts to `size`: reflow (layer constraints + auto-layout, default) or scale (uniform scale to fit, letterboxed)."},"pages":{"type":"string","enum":["all"],"description":"Every page of a still template as one still each — one page per scene, a scene repeated over data one page per item, resolved with this request's variables. Still formats only (png, webp, svg; a pdf already holds every page), exclusive with scene and nodeId, at most 50 pages (PAGE_LIMIT_EXCEEDED). Costs one still per page, reserved up front. The JSON answer is `{ pages: <count>, pageUrls: [{ index, name, url, fileId }], zipUrl }`; with `raw` the body is a ZIP (`application/zip`) of `01-<page name>.<ext>`, `02-…`."},"dpi":{"type":"integer","minimum":72,"maximum":1200,"description":"PDF only: print resolution. Page size = pixels × 72 / dpi points, so a 1200 × 1800 px label at 300 is a 4 × 6 in page. Default: the template's exportDefaults.dpi, else 300 on a print-size template (A4, Letter, business card, 4×6 label…), else 72 (1 px = 1 pt). Out of range is VALIDATION (422)."},"raw":{"type":"boolean","description":"Stream the file bytes instead of returning JSON."}}}}}},"responses":{"200":{"description":"JSON { ok, templateId, format, url, timings, creditsCharged, balanceAfter, brand?, variation?, still?, pages? (pdf), size?, warnings? ([{ nodeId, name, reason }] — layers skipped or drawn as a fallback, SVG/PDF fallbacks, text caught mid-textAnimate, pagination and soundtrack notes) } — or the raw file when `raw`/binary is requested (then `x-credits-charged` / `x-credits-balance` headers carry the credits). With `pages: \"all\"`: { ok, templateId, format, pages (count), pageUrls: [{ index, name, url, fileId }], zipUrl, timings, creditsCharged, balanceAfter, … } — or, raw, a ZIP of the numbered stills (`x-page-count` header)."},"401":{"description":"Missing or invalid API key, or the key lacks the template.render scope"},"403":{"description":"The space's verified documents are suspended, so a template with them on cannot render (CREDENTIALS_SUSPENDED)"},"404":{"description":"Template not found in the key's space, or `brand` names no brand of the key's space (BRAND_NOT_FOUND)"},"409":{"description":"`brand` matches several brands of the space (BRAND_AMBIGUOUS, see data.candidates); or the `Idempotency-Key` was used with a different request, its first request is still running, or it belongs to a finished raw render (IDEMPOTENCY_CONFLICT, `data.reason`: payload-mismatch, in-flight, raw-completed)"},"422":{"description":"`pages: \"all\"` with a pdf or video format, with scene/nodeId, or on an animated template, or `dpi` outside 72–1200 (VALIDATION); or the set is over 50 pages (PAGE_LIMIT_EXCEEDED)"}},"security":[{"bearerAuth":[]},{"apiTokenQuery":[]}]}},"/api/v1/templates/{id}/signed-urls":{"post":{"operationId":"signTemplateRenderUrlsApi","summary":"Sign render URLs","description":"Return signed image URLs (`/r/:id?…&sig=…`) for one variable set or up to 500 rows. A signed URL needs no key or session: the signature covers the template id and every parameter, so it can sit in an email, a CRM field, an OG tag or an `<img>` on any site. Each distinct URL renders once (charged like one still) and is served from cache after; republishing the template refreshes them. Still formats only (png, webp), scale ≤ 2, published version only. Requires the template.render scope.","tags":["Creatives"],"parameters":[{"in":"path","name":"id","required":true,"description":"Template ID","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"variables":{"type":"object","additionalProperties":true,"description":"Variables for ONE URL"},"rows":{"type":"array","maxItems":500,"description":"Many URLs — one per row; each row may override `options`","items":{"type":"object","properties":{"variables":{"type":"object","additionalProperties":true},"options":{"$ref":"#/components/schemas/SignedRenderOptions"}}}},"options":{"$ref":"#/components/schemas/SignedRenderOptions"},"pages":{"type":"string","enum":["all"],"description":"One URL per PAGE for every row: a still template's scenes (a scene repeated over data is one page per item, resolved with the row's variables), each signed with its `scene` index — so a carousel's keyless links exist before anything renders. Exclusive with `options.scene` and `nodeId`; at most 50 pages a row and 500 URLs a call (PAGE_LIMIT_EXCEEDED / VALIDATION). Each returned row then carries `scene` and `page: { index, name }`."}}},"example":{"rows":[{"variables":{"name":"Ada","plan":"Team"}},{"variables":{"name":"Grace","plan":"Scale"}}],"options":{"format":"webp"}}}}},"responses":{"200":{"description":"JSON { templateId, published, urls: [{ url, path, variables, scene?, page? }] } — `published: false` means the URLs will 404 until the template is published; `scene` and `page: { index, name }` appear with `pages: \"all\"`"},"401":{"description":"Missing or invalid API key"},"403":{"description":"The key lacks the template.render scope"},"404":{"description":"Template not found in the key's space, or `options.brand` names no brand of it (BRAND_NOT_FOUND)"},"422":{"description":"A variable name collides with a render option, an option is out of range, `pages: \"all\"` is combined with `options.scene` / `nodeId` or signs more than 500 URLs (VALIDATION), or a row resolves to more than 50 pages (PAGE_LIMIT_EXCEEDED)"}},"security":[{"bearerAuth":[]},{"apiTokenQuery":[]}]}},"/api/v1/templates/bulk/{jobId}":{"get":{"operationId":"creativeBulkStatusApi","summary":"Bulk render status","description":"Progress of a bulk render started with `POST /api/v1/templates/{id}/bulk`: state, per-row counts, and on completion the download — `zipUrl` for a ZIP run, `fileUrl` for an `output: \"pdf\"` run (one merged PDF); `output` says which. Poll every few seconds until `state` is `completed` or `failed`.","tags":["Creatives"],"parameters":[{"in":"path","name":"jobId","required":true,"description":"Job id from the bulk request","schema":{"type":"string"}}],"responses":{"200":{"description":"JSON { jobId, state, total, completed, succeeded, failed, currentItem?, errors, output, zipUrl?, fileUrl?, credentials? } — `credentials` ([{ row, credentialId, url, code, reused }]) lists the verified document each rendered row issued, when the template has verified documents on"},"404":{"description":"No such job in the key's space"}},"security":[{"bearerAuth":[]},{"apiTokenQuery":[]}]}},"/api/v1/templates/public":{"get":{"operationId":"listPublicTemplates","summary":"List public templates","description":"List published community/gallery templates from their published snapshots. No authentication required.","tags":["Templates"],"parameters":[{"in":"query","name":"search","required":false,"description":"Semantic + keyword search over name, description and each template's design digest (format, palette, fonts, layout), ranked by relevance (\"job application\" finds the hiring posts, \"dark editorial portrait\" finds the look); max 80 chars. Falls back to a substring match when search is unavailable.","schema":{"type":"string"}},{"in":"query","name":"category","required":false,"description":"Category filter, or \"featured\" for the curated list","schema":{"type":"string"}},{"in":"query","name":"format","required":false,"description":"Output format filter: creative (designs — also matches templates with no format set), video, doc, html-ad, mockups, backgrounds","schema":{"type":"string","enum":["creative","video","doc","html-ad","mockups","backgrounds"]}},{"in":"query","name":"page","required":false,"description":"Page number (default 1)","schema":{"type":"string"}},{"in":"query","name":"usesBrandVariables","required":false,"description":"Filter published designs: true uses brand-kit variables, false uses none","schema":{"type":"boolean"}},{"in":"query","name":"isPremium","required":false,"description":"Filter by access: true lists premium templates only, false lists free ones (anything not flagged premium)","schema":{"type":"boolean"}},{"in":"query","name":"features","required":false,"description":"Comma-separated feature tags the published snapshot must ALL carry, from its `features.tags` (e.g. data.loops, data.computation, data.class.fillable, motion.animated, layout.pagination); 1-8 tags. See the Template features section of the templates guide.","schema":{"type":"string"}},{"in":"query","name":"perPage","required":false,"description":"Items per page (max 100)","schema":{"type":"string"}},{"in":"query","name":"view","required":false,"description":"Row shape. `card` returns only what a gallery card shows: `_id`, `slug`, `name`, `type`, `format`, `category`, `isPremium` (when true), `createdBy`, `thumbnail` (URLs only, variants up to 960 px wide; `src` is omitted when variants exist, use the largest), `thumbnailCurrent`, `contentHash`, `usesBrandVariables`, `width`, `height`, `sampleCount` (stored sample sets), `pages` (page count of a still template whose `templateSettings.pageView` is `carousel`, when above 1: its scenes after scene `repeat` / `if` resolve against the default values, so one scene repeated over a 4-item list counts 4) `communityAuthor` (`{ kind: user|space, name }`, on templates listed through a reviewed community submission) and, for videos, `video` / `meta` poster URLs, plus `_lean: true`. No document, variables or design digest; fetch one template with GET /api/v1/templates/public/{id} for those. Omit for the full published row.","schema":{"type":"string","enum":["card"]}}],"responses":{"200":{"description":"JSON { list, count, pagesCount }. Each row is the template as published, or a card row with view=card"}},"security":[{"bearerAuth":[]},{"apiTokenQuery":[]}]}},"/api/v1/templates/public/{id}":{"get":{"operationId":"getPublicTemplateDoc","summary":"Get a public template","description":"Fetch one published template by ID, as published. Only templates with publicOn are returned; private IDs 404. No authentication required.","tags":["Templates"],"parameters":[{"in":"path","name":"id","required":true,"description":"Template ID","schema":{"type":"string"}}],"responses":{"200":{"description":"JSON { doc } — the template as published (creative doc under templateSettings.creative)"},"404":{"description":"Template not found or not public"}},"security":[{"bearerAuth":[]},{"apiTokenQuery":[]}]}},"/api/v1/workflows/{id}/process":{"get":{"operationId":"processWorkflowGet","summary":"Run a workflow (GET)","description":"Embed a workflow output. Auth is Authorization: Bearer or ?api_token=, with the workflow.process scope. GET cannot upload files. With cacheId, serves the cached output (run once via POST, then embed). Otherwise runs from query text inputs (text_<nodeId> or textInputs JSON). Workflows that need an image can only be served from cache. Raw bytes by default; format=json returns metadata. See /docs/workflows.","tags":["Workflows"],"parameters":[{"in":"path","name":"id","required":true,"description":"Workflow ID","schema":{"type":"string"}},{"in":"query","name":"format","required":false,"description":"binary (default) streams the image; json returns metadata.","schema":{"type":"string","enum":["json","binary"]}},{"in":"query","name":"cacheId","required":false,"description":"Serve this cached output. The usual path for an <img src>.","schema":{"type":"string"}},{"in":"query","name":"textInputs","required":false,"description":"JSON object of { nodeId: value } when there is no cacheId.","schema":{"type":"string"}},{"in":"query","name":"api_token","required":false,"description":"API key, for embedding where a header cannot be set. Same workflow.process scope as Bearer.","schema":{"type":"string"}}],"responses":{"200":{"description":"Raw image bytes, or JSON metadata when format=json."},"403":{"description":"API key missing the workflow.process scope, or not scoped to a space."}},"security":[{"bearerAuth":[]},{"apiTokenQuery":[]}]},"post":{"operationId":"processWorkflow","summary":"Run a workflow","description":"Run a workflow and return its output. Bearer API key with the `workflow.process` scope, belonging to the workflow's space. Body is multipart/form-data. Omit `format` or pass `json` for metadata, base64 and a file URL; `format=binary` streams the raw bytes (`x-workflow-run-id`, `x-workflow-cache`). `cacheId` stores the output and later calls with the same key return it without re-running. `async=true` returns a job id immediately — poll GET /api/v1/workflows/:id/process/jobs/:jobId. A synchronous call waits about 55 seconds, then returns 202 while the run continues. See /docs/workflows.","tags":["Workflows"],"parameters":[{"in":"path","name":"id","required":true,"description":"Workflow ID","schema":{"type":"string"}},{"in":"query","name":"format","required":false,"description":"json (default) returns metadata; binary streams the output bytes.","schema":{"type":"string","enum":["json","binary"]}},{"in":"query","name":"cacheId","required":false,"description":"Opt-in output cache key, 1–128 chars (A–Z a–z 0–9 . _ -).","schema":{"type":"string"}},{"in":"query","name":"async","required":false,"description":"If true, enqueue the run and return a jobId.","schema":{"type":"boolean"}}],"requestBody":{"required":false,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"Primary image input."},"nodeFile_<nodeId>":{"type":"string","format":"binary","description":"File for one input node (image or document). Replace <nodeId> with that node's id."},"text_<nodeId>":{"type":"string","description":"Text for one text-input node. Replace <nodeId> with that node's id."},"textInputs":{"type":"string","description":"JSON object of { nodeId: value } for every text input at once."}}}}}},"responses":{"200":{"description":"JSON { ok, workflowId, runId, status, cached, durationMs, output: { url, base64, mimeType, width, height } }, or the raw bytes when format=binary."},"202":{"description":"JSON { ok, runId, status: \"running\", workflowId } when a synchronous run is still going. The run finishes in the background and workflow.executed fires."},"400":{"description":"Missing workflow id, or a cacheId that fails the key rules."},"403":{"description":"API key missing the workflow.process scope, or not scoped to a space."}},"security":[{"bearerAuth":[]},{"apiTokenQuery":[]}]}},"/api/v1/workflows/{id}/process/jobs/{jobId}":{"get":{"operationId":"getWorkflowProcessJob","summary":"Workflow run status","description":"Poll a job enqueued with POST /api/v1/workflows/:id/process?async=true. Bearer API key with the workflow.process scope. The job must belong to the key's space and this workflow. state moves waiting, then active, then completed or failed. See /docs/workflows.","tags":["Workflows"],"parameters":[{"in":"path","name":"id","required":true,"description":"Workflow ID","schema":{"type":"string"}},{"in":"path","name":"jobId","required":true,"description":"Job id returned by the async process call.","schema":{"type":"string"}}],"responses":{"200":{"description":"JSON { jobId, workflowId, state, progress, result, failedReason }. result is set when state is completed."},"403":{"description":"API key missing the workflow.process scope, or not scoped to a space."},"404":{"description":"Job not found for this workflow and space."}},"security":[{"bearerAuth":[]},{"apiTokenQuery":[]}]}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key from Settings → Developers. Scope it to the endpoints and MCP tools the integration needs."},"apiTokenQuery":{"type":"apiKey","in":"query","name":"api_token","description":"Query-string key for GET template render (scope exactly template.render, no MCP tools) and GET workflow process (scope workflow.process). Other calls use Authorization: Bearer."}},"schemas":{"Error":{"type":"object","description":"Every error response. Branch on `data.code` (stable); `message` is for people.","properties":{"status":{"type":"integer"},"statusMessage":{"type":"string"},"message":{"type":"string"},"data":{"type":"object","properties":{"code":{"type":"string"},"title":{"type":"string"},"message":{"type":"string"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["code"]}}},"SignedRenderOptions":{"type":"object","description":"Render options a signed URL may carry. Still formats only; the draft is never signable.","properties":{"format":{"type":"string","enum":["png","webp"],"default":"png"},"scale":{"type":"number","minimum":0.25,"maximum":2},"scene":{"type":"integer","minimum":0,"description":"One page of a still template (0-based scene index); `pages: \"all\"` on the request signs every page instead"},"frame":{"type":"integer","minimum":0},"nodeId":{"type":"string","description":"Render one layer"},"variation":{"type":"string","description":"Saved variation id"},"brandVariant":{"type":"string","description":"Brand campaign variant id(s), comma-separated"},"brand":{"type":"string","description":"Another brand of your space to render under (brandId, name or website URL when signing; the URL carries its id, covered by the signature). The template keeps its own brand."},"size":{"type":"string","description":"Render at another size without changing the template: a size preset id (og, story, leaderboard, …) or WIDTHxHEIGHT, e.g. 1200x628. 16–8192 px a side."},"fit":{"type":"string","enum":["reflow","scale"],"default":"reflow","description":"How the design adapts to size: reflow re-lays it out with its constraints, scale scales it uniformly and letterboxes on the scene background."},"exp":{"type":"integer","description":"Unix seconds; the URL stops rendering after this"}}}}}}