Marketing Agent Platform — API

Brief in. Campaign out. Live. A 7-phase multi-agent orchestrator built on the Vercel AI ecosystem. Machine-readable spec at /api/docs.

Authentication

All /api/campaigns/* endpoints require an API key. Send it as either header:

x-api-key: <YOUR_API_KEY>
# or
Authorization: Bearer <YOUR_API_KEY>

The server reads the expected key from the API_KEY environment variable. /docs and /api/docs are public.

Endpoints

POST /api/campaigns

Kicks off a campaign. Runs the full pipeline (Lead → Strategy → Copy ∥ Image → Video → Scheduler) and returns a CampaignPackage.

Request body:

{
  "brief": {
    "id": "campaign-001",
    "audience": "Kampala SME owners",
    "product": "Mobile bookkeeping app",
    "goals": ["drive signups"],
    "tone": "friendly, confident",
    "platforms": ["instagram", "tiktok"],
    "videoDurationSec": 5,
    "providers": {
      "image": "google/gemini-2.5-flash-image",
      "video": "google/veo-3.1-lite"
    },
    "brandKitId": "kit-001"
  },
  "brandKit": {
    "id": "kit-001",
    "logos": [],
    "productImages": []
  }
}

Responses:

200 — CampaignPackage JSON
400 — { error: string } if Brief validation fails

GET /api/campaigns/:id/pulse

Server-Sent Events stream of agent activity for the given campaign. History is replayed first so a refreshed dashboard can rebuild state, then live events are streamed.

Event types:

agent.started / agent.progress / agent.completed / agent.failed
milestone.reached — e.g. strategy.locked, campaign.delivered
asset.produced — image, video, or copy reference
cost.incurred — running per-provider USD tally

Browser example (note: EventSource can't set custom headers; pass the key as a query param via a thin proxy, or use a fetch-based SSE client):

// Node / server-side
const res = await fetch("/api/campaigns/campaign-001/pulse", {
  headers: { "x-api-key": process.env.API_KEY }
});

GET /api/docs

Machine-readable JSON specification (this page's data source).

Image Providers

ID	Accepts Refs?	Max Resolution	Price (1024px)
`openai/gpt-image-2`	yes	2048px	$0.040
`google/gemini-2.5-flash-image`	yes	1024px	$0.039
`google/gemini-3.1-flash-image`	yes	4096px	$0.067
`google/gemini-3-pro-image`	yes	4096px	$0.134
`google/imagen-4-fast`	no	2048px	$0.020
`google/imagen-4-standard`	no	2048px	$0.040
`google/imagen-4-ultra`	no	2048px	$0.060

Video Providers

ID	Max Duration	Audio	$/sec @ 720p	$/sec @ 1080p
`google/veo-3.1-lite`	5s	yes	$0.05	$0.08
`google/veo-3.1-fast`	5s	yes	$0.10	$0.12
`google/veo-3.1-standard`	5s	yes	$0.40	$0.40

V1 Limitations

Video duration capped at 5 seconds.
Logos passed as references may distort in generated video frames — no post-generation overlay step in V1.
Linear pipeline — no revision/retry loops.
Fully autonomous — no human-in-the-loop checkpoints.

Full design docs in the repo: docs/01-vision.md and docs/02-architecture.md.