Answer Marketing Agent setup step

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Answers the setup step the Marketing Agent is waiting on with a fixed choice, without an agent turn.

Send the state's setup_stage as stage, along with its reset_epoch. Each step takes its own answers:

• channels takes channels_ok, which approves the channels and moves setup to kpis.
• kpis takes kpis_ok, which approves the KPIs and moves setup to budget.
• budget takes budget and competitor_research, together or one at a time. Once both are known, setup moves to generating and the agent writes the strategy. Send budget_go on its own to confirm a pair that's already stored.

To ask for a change instead, use Send Marketing Agent message.

Most answers are free and take effect at once. The one that completes the budget step starts the strategy run. The work runs in the background after the call returns. Poll Get Marketing Agent state until status is ready or error. If competitor_scan_status is running, keep polling until it is no longer running.

Each run is a Superagent turn, charged to the app's workspace in message credits based on the tokens it uses. A run can take several minutes and is stopped after 15. If the workspace is out of credits the run doesn't start, and last_error says so.

To retry safely, send the same message_id or Idempotency-Key header again. A retry returns the current state and applies nothing, so it never starts a second strategy run.

This is limited to 120 requests a minute per app for each workspace's personal API keys, so every key in a workspace shares one allowance, across every Marketing Agent endpoint. Some workspaces have a different limit.

<Note>This endpoint accepts a personal API key belonging to a user with editor access to the app and an editor role in its workspace. Read-only keys and workspace API keys are refused.</Note>

<Warning>The response includes fields beyond the ones documented here. Don't rely on undocumented response fields, as they can change at any time. Send only the fields documented here. Other request fields are not supported and their behavior can change.</Warning>

{
  "stage": "budget",
  "answers": [
    {
      "key": "budget",
      "selected_label": "$500 a month",
      "value": true,
      "band": "mid"
    }
  ],
  "message_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301"
}

{
  "status": "ready",
  "run_id": "68a1c9b7f0b3d9001a7e5d04",
  "last_error": "The scan did not complete. Retry the setup.",
  "setup_stage": "channels",
  "channels": [
    {
      "name": "Reddit communities",
      "why": "Freelancers already trade CRM tips in r/freelance.",
      "tactics": [
        "Share a build-in-public thread",
        "Answer lead-tracking questions"
      ],
      "priority": 5
    }
  ],
  "channels_revision_suggestion": "Swap LinkedIn for Product Hunt",
  "kpis": [
    {
      "name": "Weekly signups",
      "why": "Signups are the first sign the Reddit threads convert.",
      "baseline": "About 10 a week",
      "target": "50 a week in 90 days",
      "targets": {
        "mid": "50 a week in 90 days",
        "none": "20 a week in 90 days"
      },
      "target_values": {
        "mid": 50,
        "none": 20
      },
      "metric": {
        "template": "event_count",
        "event_name": "lead_created",
        "window_days": 7,
        "n": 7
      },
      "instrument": {
        "builder_prompt": "Track a lead_created event when a lead is saved on the Leads page.",
        "where": "src/pages/Leads.jsx:42",
        "requested_at": "2026-08-24T09:20:00+00:00"
      }
    }
  ],
  "kpis_revision_suggestion": "Track paid conversions instead of signups",
  "strategy": {
    "summary": "Win early freelancers in the communities they already use, then turn them into referrals.",
    "positioning": "The CRM for freelancers who never wanted a CRM.",
    "channel_plan": [
      {
        "name": "Reddit communities",
        "why": "Freelancers already trade CRM tips in r/freelance.",
        "tactics": [
          "Share a build-in-public thread",
          "Answer lead-tracking questions"
        ],
        "priority": 5
      }
    ],
    "key_metrics": [
      "Weekly signups",
      "Week-one retention"
    ],
    "budget_fit": "Organic first, with $100 a month for Reddit promoted posts."
  },
  "suggestions": [
    {
      "id": "68a1d0c2f0b3d9001a7e5e10",
      "title": "Add a referral link to the dashboard",
      "builder_prompt": "Add a Refer a friend card to the dashboard with a copyable invite link.",
      "category": "Referral",
      "rationale": "Freelancers recommend tools to each other.",
      "impact": "high",
      "effort": "low"
    }
  ],
  "budget": {
    "description": "$500 a month",
    "band": "mid"
  },
  "competitor_research_opt_in": true,
  "competitor_research_answer": true,
  "competitors": [
    {
      "name": "HubSpot",
      "url": "https://www.hubspot.com",
      "angle": "A full CRM suite for sales teams.",
      "gap": "Too heavy for a solo freelancer."
    }
  ],
  "competitor_scan_status": "done",
  "cmo_agent_app_id": "68a1c2e4f0b3d9001a7e5c21"
}