Docs

Adflow is an AI-native ad creative builder. Your agent connects via MCP (Model Context Protocol) to create design systems, build multi-scene projects, and generate AI imagery — all from natural language. This page documents every endpoint, schema, and skill your agent needs, plus a reference for the editor's creative features — vector expressions, guided physics, and the full capability map.

Quickstart

The typical agent workflow in five steps:

MCP Server Setup

Add the Adflow MCP server to your agent's configuration. You'll need an API key from the Admin panel.

Hosted server (recommended — zero-install)

Nothing to clone, no npm, no npx. Point your agent at the hosted endpoint and pass your API key as a header. This is the easiest way to connect — the server runs on adflow.design.

claude mcp add --transport http adflow https://adflow.design/api/mcp \
  --header "X-API-Key: adk_your_api_key_here"

Or as JSON (Claude Desktop / any MCP client that speaks the Streamable HTTP transport):

{
  "mcpServers": {
    "adflow": {
      "type": "http",
      "url": "https://adflow.design/api/mcp",
      "headers": {
        "X-API-Key": "adk_your_api_key_here"
      }
    }
  }
}

Your key authenticates every request and attributes usage/credits to your account — a missing or invalid key returns 401. The hosted server exposes the exact same tools as the local methods below.

Local server (offline / dev only)

Only needed if you're running offline or hacking on the server itself — most people should use the hosted URL above. You'll need the mcp-server/ folder (from the repo or a shared tarball) and Node 18+.

First install its dependencies:

cd mcp-server && npm install

Then point your agent at the server's absolute path and pass your key via the environment. ADFLOW_API_KEY is required; ADFLOW_URL is optional (defaults to https://adflow.design).

{
  "mcpServers": {
    "adflow": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/index.js"],
      "env": {
        "ADFLOW_API_KEY": "adk_your_api_key_here",
        "ADFLOW_URL": "https://adflow.design"
      }
    }
  }
}

Replace /absolute/path/to/mcp-server/index.js with the real path on your machine (e.g. /Users/you/adflow/mcp-server/index.js). A published npx adflow-mcp package is coming soon — it is not on npm yet, so don't rely on it today.

Authentication reference

Every request is authenticated with your Adflow API key. Create keys in Admin → API Keys. How you supply the key depends on the method:

MCP Endpoints

27 tools available via the MCP server. All return JSON. You call these by tool name (not by HTTP verb) — the coloured badge below each tool indicates the HTTP method of the REST endpoint it wraps, for reference when using the Direct API Fallback.

Design System Schema

The complete field reference for design systems. All fields are required for correct rendering.

Project Schema

The full project object structure returned by get_project and expected by update_project.

{
  "version": 2,
  "designSystemId": "client-slug",
  "preset": { /* full design system snapshot */ },
  "activeFormat": "square",
  "activeSceneId": "scene-uuid",
  "totalDuration": 12,
  "scenes": [ /* array of scene objects */ ]
}

Scene Schema

A scene may contain any of these fields. Almost all are optional — missing fields fall back to design-system and editor defaults, so a scene only needs the fields it actually sets.

Format Specifications

Font sizes are calculated by the renderer, not stored. The root unit determines all text sizes via multipliers.

Per-scene scale overrides: h1Scale, h2Scale, h3Scale, ctaScale (percentage, default 100).

Vector Expressions

Vector text layers accept inline expression tokens wrapped in curly braces. Each token evaluates live against the scene clock, so a single text string can count a number, cycle through words, or print a stable random digit — with no keyframes. Tokens evaluate identically in preview and in server render, and a token persists across linked scenes (the linked clips share one timeline window, so a {0-100} ramps once across the whole chain rather than restarting at each cut).

Where to type them: Canvas mode → a Vector layer → the text field (placeholder Type text…). Any glyph/string entry in the layer's text stack accepts tokens. There is no MCP parameter — expressions live inside the text content itself.

Number animation — decimals & direction

The decimal precision of the output matches the inputs: the result is shown to max(decimals of A, decimals of B) places. Both-integer inputs stay integer (rounded). Descending ranges (B < A) animate backwards.

Examples

Raised {0-100}% this quarter      → counts 0 → 100 over the scene
Only {50-0} left!                    → counts down 50 → 0
{Save big, Move fast, Win}          → three words, ~33% each, last holds
Gate {random}, Seat {random}          → two independent stable digits
{0-100}% — {loading, almost, done}     → a counter and a word cycle in one line

Behaviour & gotchas

Verified against app.html — the token runtime vexprEvalCore (parse + interpolation) and the live updater __vectorExprRuntime.

Animate & Guide Physics

Animate Physics turns a Vector layer's glyphs / SVGs into a particle system driven by force fields — no keyframing required. It lives in Canvas mode in the Animate Physics panel that appears when a vector layer is selected. An untouched panel is a no-op (all forces 0); dial in forces, or hit Randomize for a coherent recipe.

Modes

Force dials & layout

All forces default to 0 (the inert pose) and run 0–100. Forces and the global modulators can be keyframed across start / mid / end; layout values (Count, Fill, Fan Out) are structural — read once so particle identity stays locked across a linked chain.

Randomize & per-value locks

Randomize rolls a coherent natural recipe (leaves-in-breeze, tornado, planetary orbits, water ripple, rain) and re-rolls the seed. Per-value locks (the amber padlock on each slider) pin a value so Randomize leaves it untouched — useful for fixing Count or a single force while you reroll everything else. A value can be both keyframed (green) and locked (amber) at once.

Guide Physics prompt

The Guide Physics field (e.g. "form a ring · make particles rotate 360 · pulse") biases the running simulation toward a shape and/or motion. It calls the AI animate endpoint in guide mode and returns a { formation, modifier } spec — a formation settles particles into a shape, a modifier adds per-particle motion. Physics still runs underneath the guide, and clearing the prompt returns to pure physics. The guide is baked so preview matches export.

Form Sources flag-gated · beta

Form Sources let you supply the formation from your own asset instead of a text prompt — particles assemble into the shape. It is off by default; live customers see no change. Enable it without a deploy (sticky, then reload):

# URL param (sticky)
https://adflow.design/app?formSources=on      # disable: ?formSources=off

# or localStorage
localStorage.setItem('adflow_form_sources','on')

A→B morph across linked scenes: each member of a linked physics chain can hold its own formation, and particles melt from shape A in one scene to shape B in the next across the cut (count is locked across the chain so particle i maps consistently).

Verified against app.html — PHYSICS_DEFAULTS, the FORM_SOURCES / GRADIENT_FX flag blocks, and the Guide Physics + Randomize handlers.

Editor Feature Map

The editor's user-facing creative surface, beyond the API/MCP layer above. Most features are always visible; a few are flag-gated (enable via URL param or localStorage as shown above). This map reflects the shipping product — see the dedicated sections above for expressions and physics.

Agent Skills

Skills are prompt modules your agent can invoke to get context-aware guidance for specific tasks. Install the adflow skill in your agent to unlock all MCP tools and workflow knowledge.

Core Skill

JSON Templates

Download these templates, fill in your client's brand details, and import via the API or MCP tools.

Design System Template

{
  "id": "your-client-slug",
  "name": "Your Client Name",
  "uiAccent": "#2563eb",
  "colorVars": [
    { "hex": "#2563eb", "name": "Primary" },
    { "hex": "#1e40af", "name": "Secondary" },
    { "hex": "#0a0a0a", "name": "Dark" },
    { "hex": "#f5f5f5", "name": "Light" }
  ],
  "fontHeadline": "'Inter', sans-serif",
  "fontBody": "'Inter', sans-serif",
  "fontH1": "'Inter', sans-serif",
  "fontH2": "'Inter', sans-serif",
  "fontH3": "'Inter', sans-serif",
  "fontCta": "'Inter', sans-serif",
  "fontImport": "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800;900&display=swap",
  "h1Weight": "900",
  "h2Weight": "400",
  "h3Weight": "400",
  "ctaWeight": "700",
  "h1Transform": "none",
  "h2Transform": "none",
  "ctaTransform": "uppercase",
  "h1LetterSpacing": "-0.02em",
  "h2LetterSpacing": "0",
  "ctaLetterSpacing": "0.05em",
  "ctaRadius": "4px",
  "ctaAlign": "center",
  "contentAlign": "left",
  "contentPosition": "middle",
  "logoPosition": "top-left",
  "logoScale": 100,
  "logoSvg": "",
  "logoFileName": "",
  "disclaimer": "",
  "disclaimerAlign": "left"
}

Project Template

{
  "name": "My Campaign Name",
  "designSystem": "your-client-slug",
  "scenes": [
    {
      "h1": "Your Main Headline",
      "h2": "Supporting copy goes here",
      "h3": "",
      "cta": "Call To Action",
      "bgType": "colour",
      "bgColor": "#0a0a0a",
      "notes": "Scene description or AI image prompt",
      "duration": 6
    },
    {
      "h1": "Second Scene",
      "h2": "Another supporting message",
      "h3": "",
      "cta": "Learn More",
      "bgType": "gradient",
      "bgColor": "#1e40af",
      "notes": "",
      "duration": 6
    }
  ]
}

Direct API Fallback

When MCP tools aren't available, use the REST API directly with your API key.

# List design systems
curl -s -H "X-API-Key: YOUR_KEY" "https://adflow.design/api/design-systems/list"

# Save / update design system
curl -s -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  "https://adflow.design/api/design-systems/save" \
  -d '{"id": "client-slug", "data": { ... }}'

# List projects
curl -s -H "X-API-Key: YOUR_KEY" "https://adflow.design/api/projects/list"

# Get project by UUID
curl -s -H "X-API-Key: YOUR_KEY" "https://adflow.design/api/projects/PROJECT_UUID"

# Create new project
# project blob MUST include version, designSystemId, preset.name, activeFormat
curl -s -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  "https://adflow.design/api/projects/save" \
  -d '{"filename": "project-slug", "project": {"version":2, "designSystemId":"client-slug", "preset":{"name":"Client Name"}, "activeFormat":"square", "scenes":[...]}}'

# Update existing project
curl -s -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  "https://adflow.design/api/projects/save" \
  -d '{"filename": "project-slug", "projectId": "UUID", "project": {"version":2, "designSystemId":"client-slug", "preset":{"name":"Client Name"}, "activeFormat":"square", "scenes":[...]}}'

# ─── AI generation (genai/*) — all POST, all return a blob URL ───

# Generate an image from a text prompt
# model: flux-dev (default), flux-pro, imagen4, imagen4-fast, gpt-image-1, nano-banana-pro, ideogram-v3, recraft-v3, recraft-v3-transparent
curl -s -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  "https://adflow.design/api/genai/generate" \
  -d '{"model":"flux-dev", "prompt":"a red sports car at sunset", "width":2160, "height":2160, "filename":"car.png", "design_system_id":"client-slug"}'

# Edit an existing image with an instruction (the editing suite)
# Same shape applies to /api/genai/inpaint, /retouch, and /enhance
curl -s -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  "https://adflow.design/api/genai/edit" \
  -d '{"model":"nano-banana-pro", "prompt":"make the sky stormy", "image_url":"https://.../car.png", "filename":"car-edited.png"}'

# Outpaint / extend an image (fill new pixels around the frame)
curl -s -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  "https://adflow.design/api/genai/outpaint" \
  -d '{"image_data":"data:image/png;base64,...", "expand_top":0, "expand_bottom":256, "expand_left":0, "expand_right":0, "prompt":"more road", "filename":"car-extended.png"}'

# Animate an element / scene into a video clip
curl -s -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  "https://adflow.design/api/genai/animate" \
  -d '{"prompt":"slow pan across the car", "duration":6, "format":"mp4", "width":1080, "height":1080}'

# List your past generations
curl -s -H "X-API-Key: YOUR_KEY" "https://adflow.design/api/genai/list"

# ─── Renders (renders/*) ───

# Rasterise composition HTML to a PNG screenshot (server-side Puppeteer)
curl -s -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  "https://adflow.design/api/renders/screenshot" \
  -d '{"html":"<!doctype html>...", "width":1080, "height":1080}'

# Render composition HTML to a video on AWS Lambda (returns an executionArn)
curl -s -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  "https://adflow.design/api/renders/video" \
  -d '{"html":"<!doctype html>...", "width":1080, "height":1080, "fps":30, "quality":"high", "format":"mp4"}'

# Poll render progress (executionArn returned by /renders/video)
curl -s -H "X-API-Key: YOUR_KEY" "https://adflow.design/api/renders/progress?executionArn=ARN"

Critical Rules