REST API

Everything braaand can do is available over plain HTTPS. The MCP connector and the CLI are usually the comfortable paths, but when you're wiring braaand into your own backend, an orchestrator, or a language without an SDK, this is the surface you build against.

The base URL is:

https://www.braaand.ai/api

Building an agent? Pick the shortest path before hand-rolling HTTP:

1. MCP — connect https://mcp.braaand.ai/mcp and your agent gets dozens of ready-made tools whose descriptions carry the on-brand rules (what to set, what to leave to the cascade). Zero integration work. See Connect an AI client.
2. The CLI — npm i -g braaand for coding agents with shell access. Auth is stored once (braaand login), renders land as files on disk instead of flowing through the model's context, and payloads too large for a request body (bulk onboards over ~4 MB) only work here. See Command line.
3. The Claude skill — the packaged braaand playbook for Claude Code. See Claude skill.
4. This page + GET /api — for your own HTTP wrapper. GET /api returns a prose orientation written for LLMs; feed your model that plus this page and it can drive the API. One thing neither carries in full: braaand's styling philosophy (let role, color schemes, and themes drive look — never set fonts or colors inline). If your agent will edit creatives rather than just fill copy, also feed it How your brand flows in. The docs are fetchable as raw markdown — this page lives at /docs/md/agents/rest-api, and /docs/llms.txt indexes everything with deep links.

Get a key

1. Go to Settings → Profile → API keys and click New key. Copy the ae_… value right away — it's shown once and stored hashed.
2. Or from the terminal: npm i -g braaand && braaand login walks you through device auth and stores a key for the CLI.

Send it as a bearer token on every request:

curl -H "Authorization: Bearer ae_..." https://www.braaand.ai/api/brands

A user key acts as you. For a single-purpose integration scoped to one brand, mint a brand token (bt_…) instead — POST /api/brands/{brandId}/tokens with { "name": "zapier", "role": "editor" } — and it can never touch other brands or manage members.

Quickstart: brief to PNG in four calls

1. Find your brand and a template.

curl -H "Authorization: Bearer $KEY" https://www.braaand.ai/api/brands
# → [{ "id": "acme", "name": "Acme", "role": "owner", ... }]

curl -H "Authorization: Bearer $KEY" https://www.braaand.ai/api/brands/acme/templates
# → [{ "id": "acme-hero-statement-1a2b3c4d", "name": "Hero statement", "elements": [...], ... }]

2. Clone the template into a creative.

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  https://www.braaand.ai/api/brands/acme/creatives \
  -d '{ "templateId": "acme-hero-statement-1a2b3c4d", "name": "Summer sale hero" }'
# → 201 { "id": "crv_9f8e...", "elements": [{ "id": "heading", ... }], ... }

3. Put your copy in. Element ids come from the creative you just received; patches are partial and merge.

curl -X PATCH -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  https://www.braaand.ai/api/brands/acme/creatives/crv_9f8e.../elements/heading \
  -d '{ "content": "Up to 50% off" }'

4. Render it. The response is the PNG itself (an X-Render-Id header carries the id for your records).

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  https://www.braaand.ai/api/render \
  -d '{ "kind": "creative", "brandId": "acme", "creativeId": "crv_9f8e...", "format": "1x1" }' \
  --output summer-sale-1x1.png

Producing at scale: workflows

For a batch ("give me a campaign from this brief"), launch a workflow and poll its manifest — there are no webhooks; the manifest is recomputed on every read, so polling always reflects the latest state including later edits.

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  https://www.braaand.ai/api/brands/acme/factory/workflows \
  -d '{ "brief": { "raw": "Summer sale, warm and urgent, CTA to acme.com/sale" }, "count": 20 }'
# → 201 { "workflowId": "...", "boardId": "...", "manifestUrl": "...", "boardUrl": "...", "shareUrl": "..." }

curl -H "Authorization: Bearer $KEY" "$MANIFEST_URL"
# → { "status": "running", "creatives": [{ "id": "crv_...", "renders": { "1x1": "https://..." }, "score": 84, ... }] }

The brief is free text — how many creatives you want goes in count (1-200), never in the prose. The produced creatives land on a board (boardId) — a durable review place that can hold creatives from more than one run — pre-sorted into an Approved section (score ≥ 75) and Needs review for the rest. Every run is also a live node pipeline; open /brands/{brandId}/factory/{workflowId}/pipeline in the app to watch or edit it. boardUrl is the human review surface; shareUrl is a read-only link you can hand a client without a braaand account. For a full accounting of the run (build stages, scores, cost), pull GET .../factory/workflows/{workflowId}/log.

Conventions

• Status codes. 401 bad or missing credentials, 403 not allowed, 404 not found, 400 validation, 402 out of credits (the body carries a machine-readable code), 507 storage quota exceeded, 429 rate limited (with a Retry-After header), 409 edit conflict or "run is still building".
• Errors are JSON: { "error": "human-readable message", "code": "machine_readable_when_relevant" }. Malformed request bodies answer 400 { "error": "invalid_json" }; schema failures answer 400 { "error": "validation", "details": [{ "path", "message" }] }.
• Edit conflicts. Templates and creatives carry a version number. Send the version your edits are based on in the X-Doc-Version header (or as version in the body) and the save is compare-and-set: if someone else saved first you get a 409 with the currentVersion, so you re-read and re-apply instead of overwriting their work. Partial updates without a version are merged onto a fresh read server-side.
• Merging. Config-style PUTs (brand config, templates, creatives) only overwrite the fields present in the body — omit a field to leave it alone.
• Rate limits (per caller): render 120/5 min, batch render 20/5 min, agent chat 60/5 min, onboarding 10/hour, workflow launch 20/hour.
• Formats are named 1x1 (1080×1080), 4x5 (1080×1350), 9x16 (1080×1920), and 16x9 (1200×628) by default; each document carries its own list, so read formats off the doc rather than assuming.
• Ids are stable strings — creatives are prefixed crv_, keys ae_, brand tokens bt_, share links dt_.
• No pagination. List endpoints return everything; filter server-side where query params exist (e.g. creatives by collection, status, tag).
• Asset and render URLs are capabilities. They contain unguessable ids and are safe to hot-link; they're also immutable and cached hard, so the URL changes whenever the content does.
• Stability. There is no versioned prefix yet; the shapes documented here are the supported surface. Build against the documented fields and treat undocumented ones as subject to change.

Endpoints

Generated from the codebase — always current. Internal surfaces (admin, cron, webhooks) are omitted.

Brands

Factory (workflows)

Rendering

Previews

System templates

System assets

Onboarding

Account (me)

Auth (device flow)

Share (delivery links)

Misc