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.

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.

Claude Code / Claude Desktop

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

Direct Node (local development)

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

Authentication

All requests require either:

MCP Endpoints

16 tools available via the MCP server. All return JSON.

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

Every scene in a project contains these fields. All are required for correct rendering.

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).

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",
  "brandColor1": "#2563eb",
  "brandColor2": "#1e40af",
  "bgColor": "#0a0a0a",
  "textColor": "#ffffff",
  "ctaBgColor": "#2563eb",
  "ctaTextColor": "#ffffff",
  "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":[...]}}'

Critical Rules