Campaign

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

All API references → · Six flows, four surfaces →


Base URL	`https://api.hanzo.ai`
Operations	11
Auth	`Authorization: Bearer $HANZO_API_KEY`

RemoveCampaignChannel drops one channel from a campaign and returns the updated campaign.

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

RemoveCampaignChannel 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.

Parameter	In	Type	Required	Description
`id`	path	string	yes	ID is the campaign, from the path.
`kind`	path	string	yes	Kind is the channel to remove: paid, organic or email.

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

POST /v1/campaign/{id}/channels

AddCampaignChannel 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.

Parameter	In	Type	Required	Description
`id`	path	string	yes	ID is the campaign to add the channel to, from the path.

Request body — application/json (required)

Field	Type	Required	Description
`account`	string	—	Account is the provider account this channel runs under: an ad-account, a page, or a mailing-list id.
`id`	string	—	ID is the campaign to add the channel to, from the path.
`kind`	string	—	Kind is the channel kind and the identity a campaign holds at most one of: paid, organic or email.
`platform`	string	—	Platform is the provider within the kind — meta, google, x, instagram, or the email provider.

post_v1_campaign_by_id_launch

POST /v1/campaign/{id}/launch

Parameter	In	Type	Required	Description
`id`	path	string	yes

CampaignMetrics 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.

GET /v1/campaign/{id}/metrics

CampaignMetrics 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.

Parameter	In	Type	Required	Description
`id`	path	string	yes	ID is the campaign to report on, from the path.
`range`	query	string	—	Range is the lookback window: 24h, 7d, 30d or 90d.
`start`	query	string	—	Start is an explicit RFC3339 window start.
`end`	query	string	—	End is an explicit RFC3339 window end.

post_v1_campaign_by_id_pause

POST /v1/campaign/{id}/pause

Parameter	In	Type	Required	Description
`id`	path	string	yes

GetCampaign returns one campaign of the caller's org — its name, audience, creatives, channels with their per-channel launch state, schedule, budget and status.

GET /v1/campaign/{id}

GetCampaign 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.

Parameter	In	Type	Required	Description
`id`	path	string	yes	ID is the campaign's server-minted handle, "cmp_"-prefixed.

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

PUT /v1/campaign/{id}

UpdateCampaign 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.

Parameter	In	Type	Required	Description
`id`	path	string	yes	ID is the campaign to update, from the path.

Request body — application/json (required)

Field	Type	Required	Description
`audience`	string	—
`budget`	integer	—
`channels`	cloud_ChannelSpec[]	—
`content`	string[]	—
`id`	string	—	ID is the campaign to update, from the path.
`name`	string	—
`scheduleAt`	integer	—

DeleteCampaign removes one campaign of the caller's org and answers 204 with no body.

DELETE /v1/campaign/{id}

DeleteCampaign 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.

Parameter	In	Type	Required	Description
`id`	path	string	yes	ID is the campaign's server-minted handle, "cmp_"-prefixed.

SummarizeCampaigns 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.

GET /v1/campaign/summary

SummarizeCampaigns 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.

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

GET /v1/campaign

ListCampaigns 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.

Parameter	In	Type	Required	Description
`status`	query	string	—	Status keeps only campaigns in that state: draft, live, paused or failed.
`limit`	query	integer	—	Limit bounds the page.

CreateCampaign creates a campaign as a DRAFT and returns it.

POST /v1/campaign

CreateCampaign 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)

Field	Type	Required	Description
`audience`	string	—	Audience is the segment or audience selector this campaign targets.
`budget`	integer	—	Budget is the campaign's total budget in CENTS.
`channels`	cloud_ChannelSpec[]	—	Channels are the fan-out targets, at most one per kind (paid, organic, email) and at most 12.
`content`	string[]	—	Content is the ordered creative set. Content[0] is the active creative and the rest are A/B variants; at most 32, empty
`name`	string	—	Name is the campaign's display name.
`scheduleAt`	integer	—	ScheduleAt is when the campaign should run, in unix seconds.

All Hanzo APIs · Interactive reference

Campaign

On this page