Campaign

Package campaign is one go-to-market push across paid, organic and email at once.

campaign

DELETE /v1/campaign/{id}/channels/{kind}

Drops one channel from a campaign and returns the updated campaign. 404 when the campaign carries no channel of that kind.

It removes the channel from the PLAN. A channel that is live at its provider should be paused first — dropping the row here leaves nothing to pause it with afterwards.

POST /v1/campaign/{id}/channels

Adds a channel to a campaign, or REPLACES the one it already has of that kind, and returns the updated campaign.

A campaign carries at most one channel per kind, because the kind IS the executor: adding a second "paid" channel would mean two ad accounts running one campaign with no way to tell their results apart. The new channel starts "pending" — adding it does not launch it.

Request body — application/json (required)

POST /v1/campaign/{id}/launch

Launch a campaign across every channel it declares

Pushes the campaign live on each of its channels through that channel's executor and answers the whole campaign with the per-channel outcome written back onto it.

The fan-out is BEST-EFFORT PER CHANNEL, and the honest reading of the result is the rule most callers get wrong: one channel failing never aborts the others, so each channel row carries its own live, failed or unavailable status and detail, and a paid launch can be live while an email launch failed. The campaign itself is live when AT LEAST ONE channel launched and failed only when none did — live is not a claim that every channel launched. Repeating the call is safe: a channel already live is skipped, never re-launched. A campaign carrying more than one creative has its variant assigned here by the experiment seam and tagged as utm_content.

Org-scoped and fails closed: a valid bearer is required (403 without one), the campaign is read under the caller's OWN org so another tenant's id is a 404, and a campaign with no channels is a 400 — there is nothing to launch. Each executor resolves its own org's connector token from the org passed to it, so a launch can never spend through another tenant's connector.

GET /v1/campaign/{id}/metrics

Returns a campaign's results over a window: the analytics funnel (impressions, clicks, conversions, revenue, visitors), the spend each channel's connector reports, and the derived growth KPIs — CTR, CVR, CAC and ROAS.

There is exactly ONE metrics plane and nothing is stored here: the funnel is an analytics query over the campaign's utm_campaign-tagged events, and the spend is each provider's own number read through the org's connector. A warehouse that is not emitting yet degrades to available:false with zeroes — honest-empty, never a 500 and never a fabricated number. When the campaign runs more than one creative and an experiment is wired, abTest carries the A/B analysis.

POST /v1/campaign/{id}/pause

Pause every live channel on a campaign at its provider

Pauses each live channel on its provider and answers the whole campaign, moved to paused, with the per-channel outcome written back onto it.

Only channels that are live and carry a provider reference are touched; a channel whose executor is no longer wired is marked unavailable and one whose pause errored is marked failed, with the reason on the row. The campaign still reports paused in both cases, and that is deliberate rather than sloppy: no live channel remains that this process will meter, and the rows say exactly which provider was not reached so it can be settled by hand.

Org-scoped and fails closed: a valid bearer is required (403 without one) and the campaign is read under the caller's OWN org, so another tenant's id is a 404.

GET /v1/campaign/{id}

Returns one campaign of the caller's org — its name, audience, creatives, channels with their per-channel launch state, schedule, budget and status. 404 when the org has no campaign with that id.

PUT /v1/campaign/{id}

Rewrites a campaign's core fields — name, audience, creatives, schedule and budget — and returns the updated campaign.

Channels are replaced ONLY while the campaign is still a draft. Once it is launched its channels carry provider state (an external id, a live status), so they are added and removed explicitly through the channels sub-resource instead; a whole-object write would silently orphan a running execution.

Request body — application/json (required)

DELETE /v1/campaign/{id}

Removes one campaign of the caller's org and answers 204 with no body. 404 when the org has no campaign with that id.

It deletes the RECORD, not the executions: a campaign whose channels are live on a provider should be paused first, or those executions keep running with nothing here to report them.

GET /v1/campaign/summary

Returns the org's go-to-market roll-up: how many campaigns exist, how many are live, their total budget in cents, and which channel executors this deployment can actually reach.

The channel list is the deployment's honest capability, not a wish: a kind missing from it is one a launch will record as "unavailable" rather than fail on.

GET /v1/campaign

Returns the org's campaigns, newest first, optionally narrowed to one status.

A campaign is the top-level go-to-market object: a value that SPANS channels (paid, organic, email) and fans out to the executor for each. The listing is org-scoped server-side, so one org can never see another's campaigns.

POST /v1/campaign

Creates a campaign as a DRAFT and returns it.

A draft is inert: nothing is sent, no connector is touched and no budget is committed until the campaign is launched. The channels named here are validated and de-duplicated by kind (one executor per kind), and every channel starts "pending" whatever the caller claims — a client can never assert a launched state.

Request body — application/json (required)

---

All Hanzo APIs · Interactive reference