Ads
Package ads is your paid ad campaigns, launched and paused from one place.
Package ads is your paid ad campaigns, launched and paused from one place.
| Base URL | https://api.hanzo.ai |
| Operations | 7 |
| Auth | Authorization: Bearer $HANZO_API_KEY |
ads
post_v1_ads_campaigns_by_id_launch
POST /v1/ads/campaigns/{id}/launch
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
Returns one of the caller org's campaigns.
GET /v1/ads/campaigns/{id}
Returns one of the caller org's campaigns. An id another org owns reads as not found, so the response cannot confirm that it exists.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
Replaces the user-owned fields of one of the caller org's campaigns and answers the stored row.
PUT /v1/ads/campaigns/{id}
Replaces the user-owned fields of one of the caller org's campaigns and answers the stored row. It is a full replace, not a patch: every field is written from the request, so an omitted one is cleared. externalId is launch-owned and is never touched here, so editing a campaign cannot break its link to a live provider execution.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
account | string | — | Account is the provider ad-account this campaign runs on (Meta act_<id>). |
budget | integer | — | Budget is the campaign budget in MINOR units (cents). |
name | string | — | Name is the campaign's display label. |
objective | string | — | Objective is the campaign goal as the provider names it. |
platform | string | — | Platform is the ad network: meta, google, tiktok or x. |
spend | integer | — | Spend is the amount spent so far in MINOR units (cents). |
status | string | — | Status is the lifecycle state: draft, active, paused or completed. |
Removes one of the caller org's campaigns and answers 204 with no body.
DELETE /v1/ads/campaigns/{id}
Removes one of the caller org's campaigns and answers 204 with no body. It deletes the stored record only: a campaign already launched keeps running on the ad network, which must be stopped there. An id another org owns reads as not found.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
Returns the caller org's ad campaigns, most recently updated first, optionally narrowed to one lifecycle status.
GET /v1/ads/campaigns
Returns the caller org's ad campaigns, most recently updated first, optionally narrowed to one lifecycle status. The listing is bounded by the org: another tenant's campaigns are not reachable from here at all.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
status | query | string | — | Status filters to one lifecycle state (draft, active, paused, completed). |
limit | query | integer | — | Limit caps how many campaigns come back: default 200, maximum 1000. |
Registers a new ad campaign for the caller's org and answers 201 with the stored row.
POST /v1/ads/campaigns
Registers a new ad campaign for the caller's org and answers 201 with the stored row. It only records the campaign — nothing is sent to the ad network until POST /v1/ads/campaigns/{id}/launch runs it. The org is stamped by the server from the validated principal, so a body can never place a campaign in another tenant.
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
account | string | — | Account is the provider ad-account this campaign runs on (Meta act_<id>). |
budget | integer | — | Budget is the campaign budget in MINOR units (cents). |
name | string | — | Name is the campaign's display label. |
objective | string | — | Objective is the campaign goal as the provider names it. |
platform | string | — | Platform is the ad network: meta, google, tiktok or x. |
spend | integer | — | Spend is the amount spent so far in MINOR units (cents). |
status | string | — | Status is the lifecycle state: draft, active, paused or completed. |
Rolls the caller org's ad campaigns up into four numbers: how many campaigns exist, how many are active, and the summed budget and spend across all of them.
GET /v1/ads/summary
Rolls the caller org's ad campaigns up into four numbers: how many campaigns exist, how many are active, and the summed budget and spend across all of them. Budget and spend are MINOR units (cents), the same units the campaign rows carry. It counts only this org's campaigns.
How is this guide?