Start a campaign

From a goal to a priced plan in one call: goal (launch, funding, feature or program), product, moment (what goes live and when), window_start, window_end and budget_usd; optionally audience and company (left out, they come from your company context), geography (worldwide), desired_outcome (the goal's usual outcome), constraints and budget_min_usd. The answer's defaults lists every field it filled. The budget is held to this key's mandate: the plan is built within the smaller of budget_usd, the mandate's maximum plan total and what is left of its monthly cap, and a budget_min_usd above either limit is refused (mandate_refused, over_max_plan_total or over_monthly_cap, with the numbers); with no budget_min_usd the campaign is held to the mandate instead. The campaign is started for the brand exactly as from the workspace and the planner builds the plan from creators on sale now. Returns campaign_id and the plan as plan_quote returns it, or plan_note when nothing on sale fits yet. Needs an idempotency_key; a retry with the same key never starts a second campaign. A brand starts at most 3 campaigns in any 24 hours (rate_limited, details.reason daily_campaign_limit, details.resets_at when it reopens). Scope: campaigns:write. MCP tool: create_campaign.

post/campaigns

Request

  • Base URL: https://app.distribution.tech/api/v1
  • URL: https://app.distribution.tech/api/v1/campaigns
  • Auth: HTTP bearer

Headers

Idempotency-Keystring required

8 to 128 letters, digits or . _ : -. Retry with the same key and the same request to get the same answer; it never runs twice.

Request body

goal'launch' | 'funding' | 'feature' | 'program' required
productstring required
momentstring required

What goes live and when.

audiencestring
geographystring
window_startstring date required
window_endstring date required
budget_usdinteger required

The most to spend, in US dollars. The plan is held to this key's mandate: never above its maximum plan total or what is left of its monthly cap.

budget_min_usdinteger

The least to spend. Above the mandate's maximum plan total, or what is left of its monthly cap, the campaign is refused (mandate_refused). Left out, the budget is held to the mandate instead of refused.

desired_outcomestring
companystring
constraintsstring

Response

OK

campaign_idstring uuid required
status'plan_ready' | 'no_plan' required
plan_notestring nullable required
defaultsstring[]

The fields filled because the request left them out.

Changes

No recorded changes to this operation across all 1 revision of this API.