Drive the creative engine from code.

Turbosurge exposes the whole ad-creation system programmatically — read your brand and ads, generate and create concepts, schedule and publish to connected platforms, and read real performance. Two doors, one set of handlers: a REST API and an MCP server for AI agents.

Two interfaces, identical behaviour

Every MCP tool calls the same handler as its REST endpoint — surge_get_analytics and GET /analytics return the same object. Pick REST for your own backend, MCP to let an AI agent (Claude, Cursor, any MCP client) operate your account directly.

You can	REST	MCP tool
Read your brand profile & ads	`GET /brand`, `/ads`	`surge_get_brand`, `surge_list_ads`
Generate ad concepts from a brief	—	`surge_generate_ads`
Create a production ad from a concept	—	`surge_create_ad`
Schedule & publish to platforms	`POST /schedule`	`surge_schedule_ad`
Read real post performance	`GET /analytics`	`surge_get_analytics`

Early access. The developer platform is live for every Turbosurge account. You mint your key and see your account's base URL in the app under Settings → API. A branded api.turbosurge.ai host is rolling out; until then your dashboard shows the exact base URL to use.

Authentication

Every request authenticates with a Bearer Surge API key. Keys are prefixed surge_live_ and are the only way in — a ClipSpeed csai_ key is refused at the prefix, before it can touch anything.

Create and revoke keys in Settings → API. Treat a key like a password: it grants full access to your Turbosurge account. Send it in the Authorization header.

# Every request carries your key in the Authorization header
curl "$SURGE_API_BASE/account" \
  -H "Authorization: Bearer surge_live_your_key_here"

A missing or invalid key returns 401 with WWW-Authenticate: Bearer realm="surge":

HTTP 401
{ "error": "unauthorized", "message": "Invalid or revoked API key." }

Rate limits

Requests are rate limited per key. When you exceed the limit the API returns 429 with a machine-readable retry hint, so you can back off precisely rather than guess:

HTTP 429
{ "error": "rate_limited",
  "message": "API rate limit exceeded",
  "retryAfterMs": 1840 }

Read retryAfterMs and wait that long before retrying. Generation and publish calls are heavier than reads — batch reads where you can, and don't poll analytics in a tight loop.

Endpoints

All paths are relative to your account's base URL ($SURGE_API_BASE, shown in Settings → API). Responses are JSON. Reads are GET; the two writes are marked.

Account & brand

Endpoint	Returns
GET`/account`	Plan, credits, usage for the authenticated account.
GET`/brand`	Your derived Brand Profile — summary, offer, audience, tone, angles.
GET`/connections`	Connected social accounts and whether each can publish right now.

Endpoint	Returns
GET`/ads`	Your ads, newest first.
GET`/ads/:id`	One ad by id, with its render and metadata.

Schedule & publish

Endpoint	Returns
GET`/schedule`	Your calendar — each plan's real outcome (posted, planned, or failed with the reason).
POST`/schedule`	Schedule an ad to a connected account. Publishing to a real audience — confirm the time before you call it.

Trending & performance

Endpoint	Returns
GET`/trending`	Trending posts in your vertical that Turbosurge can remix, with real engagement numbers.
GET`/analytics`	Rolled-up performance. Read `hasData` — it is `false` when nothing has published yet.
GET`/analytics/series`	Performance over time for charting.
GET`/analytics/posts/:itemId`	One posted plan's own numbers, by calendar item id.
GET`/insights`	What is working across your account.
GET`/insights/recommendation`	The next best action Turbosurge recommends.

# List your ads
curl "$SURGE_API_BASE/ads" \
  -H "Authorization: Bearer $SURGE_KEY"

MCP server

Turbosurge ships its own MCP server so an AI agent can drive your account directly — research, generate, render, schedule and measure. It authenticates with the same surge_live_ key and calls the same handlers as the REST API above.

Connect an agent

Point any MCP client at the Turbosurge MCP endpoint and pass your key as a Bearer token. In an MCP client config:

{
  "mcpServers": {
    "turbosurge": {
      "url": "$SURGE_MCP_URL",   // shown in Settings → API
      "headers": { "Authorization": "Bearer surge_live_..." }
    }
  }
}

Two write tools, and only two. Everything an agent reads is safe to run unattended; the only actions that change the world are surge_create_ad (creates a production ad) and surge_schedule_ad (publishes to a real audience). Confirm those with a human before calling.

Tools

Tool		Does
`surge_get_account`	read	Plan, credits, usage.
`surge_get_brand`	read	Your Brand Profile.
`surge_list_ads`	read	Your ads.
`surge_get_ad`	read	One ad by id.
`surge_list_connections`	read	Connected accounts + publish readiness.
`surge_list_trending`	read	Remixable trending posts in your vertical.
`surge_list_schedule`	read	Calendar with each plan's real outcome.
`surge_get_analytics`	read	Rolled-up performance (`hasData` aware).
`surge_get_analytics_series`	read	Performance over time.
`surge_get_post_analytics`	read	One posted plan's own numbers.
`surge_what_works`	read	What is working across your account.
`surge_recommendation`	read	The next best action.
`surge_generate_ads`	read	Generate ad concepts from a brief; returns candidates.
`surge_create_ad`	write	Render a production ad from a generated candidate.
`surge_schedule_ad`	write	Schedule & publish an ad to a connected account.

Get your API key & MCP URL →