API reference

Base URL: your Waveband host. Authenticate every request with Authorization: Bearer wbk_.... Machine-readable spec: OpenAPI 3.1. Rate limit: 240 requests/minute per key (HTTP 429 beyond that). Errors are JSON with a stable code and human-readable message — see the error reference.

Keys are created in Console → Developers with exactly the scopes they need, optionally pinned to a single workspace. The key is shown once at creation.

Developer settings page with API keys, webhooks, and OAuth clients — Console → Developers: API keys, webhook endpoints, and OAuth clients.

Scopes

Every operation below names its required scope. The full scope list (append-only — removing a scope would be a breaking change):

workspaces:readworkspaces:writecampaigns:readcampaigns:writeline_items:readline_items:writetargeting:readtargeting:writecreatives:readcreatives:writeevents:readevents:writesegments:readsegments:writeaudiences:readaudiences:writereports:readreports:writemetrics:readdatasets:readdatasets:exportbilling:readbilling:writewebhooks:readwebhooks:writeapi_keys:readapi_keys:writeautomations:readautomations:writebranding:readbranding:writedomains:readdomains:writeai:invokediagnostics:readdiagnostics:runadmin:readadmin:writecatalog:readcatalog:writeapprovals:readapprovals:write

Operations

get/api/v1/workspaces

List workspaces

Required scope: workspaces:read

post/api/v1/workspaces

Create a workspace

Required scope: workspaces:write · supports Idempotency-Key

get/api/v1/campaigns

List campaigns in a workspace

Required scope: campaigns:read

post/api/v1/campaigns

Create a campaign

Required scope: campaigns:write · supports Idempotency-Key

get/api/v1/campaigns/{id}

Get a campaign

Required scope: campaigns:read

patch/api/v1/campaigns/{id}

Update a campaign

Also used for pause/resume via the status field.

Required scope: campaigns:write

get/api/v1/line-items

List line items in a campaign

Required scope: line_items:read

post/api/v1/line-items

Create a line item

Required scope: line_items:write · supports Idempotency-Key

get/api/v1/line-items/{id}

Get a line item

Required scope: line_items:read

patch/api/v1/line-items/{id}

Update a line item

Budget, bid, pacing, targeting, and status (pause/resume/activate) changes.

Required scope: line_items:write

post/api/v1/line-items/{id}/creatives

Attach a creative to a line item

Required scope: line_items:write

get/api/v1/creatives

List creatives in a workspace

Required scope: creatives:read

post/api/v1/creatives

Create a creative

Assets are URL-based (upload to your storage or ours first). Video/audio transcode asynchronously.

Required scope: creatives:write · supports Idempotency-Key

get/api/v1/creatives/{id}

Get a creative

Required scope: creatives:read

get/api/v1/conversion-events

List conversion events

Required scope: events:read

post/api/v1/conversion-events

Create a conversion event

Required scope: events:write · supports Idempotency-Key

get/api/v1/audiences

List audience segments in a workspace

Required scope: audiences:read

post/api/v1/audiences

Create an audience segment

Pixel-based rules (site_visitors, converters, event_rule), uploaded lists (crm_list, ip_list), or a marketplace activation.

Required scope: audiences:write · supports Idempotency-Key

get/api/v1/audiences/{id}

Get an audience segment

Required scope: audiences:read

delete/api/v1/audiences/{id}

Archive an audience segment

Required scope: audiences:write

post/api/v1/audiences/{id}/members

Upload members to a list segment

crm_list: emails/phones (hashed at ingest; raw values are never stored) or pre-hashed sha256 lines. ip_list: IP addresses.

Required scope: audiences:write

post/api/v1/audiences/{id}/attach

Attach or detach a segment on a line item

One-click retargeting: merges the segment into the line item's audience targeting.

Required scope: audiences:write

get/api/v1/marketplace-segments

Search the third-party segment marketplace

Required scope: audiences:read

get/api/v1/reports

Query metrics

Aggregated delivery/performance rows; format=csv streams a CSV export.

Required scope: reports:read

get/api/v1/events

List domain events

The event stream that webhooks deliver; useful for backfill and debugging.

Required scope: webhooks:read

get/api/v1/webhooks

List webhook endpoints

Required scope: webhooks:read

post/api/v1/webhooks

Create a webhook endpoint

The signing secret is returned once. Verify deliveries via X-Waveband-Signature: sha256=HMAC(secret, body).

Required scope: webhooks:write · supports Idempotency-Key

delete/api/v1/webhooks/{id}

Delete a webhook endpoint

Required scope: webhooks:write

get/api/v1/webhook-deliveries

List webhook deliveries

Required scope: webhooks:read

post/api/v1/webhook-deliveries/{id}/replay

Replay a webhook delivery

Required scope: webhooks:write

get/api/v1/rate-cards

List rate cards

Required scope: catalog:read

post/api/v1/rate-cards

Create a rate card

The first active card becomes the tenant default; isDefault switches it.

Required scope: catalog:write · supports Idempotency-Key

get/api/v1/packages

List productized packages

Required scope: catalog:read

post/api/v1/packages

Create a package

Required scope: catalog:write · supports Idempotency-Key

post/api/v1/packages/{id}/instantiate

Instantiate a package into a draft campaign

Creates a draft campaign + line item priced from the package or default rate card.

Required scope: catalog:read

get/api/v1/deals

List curated deals

Required scope: catalog:read

post/api/v1/deals

Add a deal to the library

Registers an SSP-issued deal ID; provisioning to delivery is asynchronous.

Required scope: catalog:write · supports Idempotency-Key

get/api/v1/proposals

List proposals in a workspace

Required scope: campaigns:read

post/api/v1/proposals

Create a proposal

Line items priced in USD minor units; share at /p/{token} once sent.

Required scope: campaigns:write · supports Idempotency-Key

post/api/v1/proposals/{id}/send

Mark a proposal sent

Activates the public microsite for viewing and click-to-sign.

Required scope: campaigns:write

get/api/v1/api-keys

List API keys

Required scope: api_keys:read

post/api/v1/api-keys

Create an API key

Scopes cannot exceed the calling key's scopes. The key is returned once.

Required scope: api_keys:write · supports Idempotency-Key

delete/api/v1/api-keys/{id}

Revoke an API key

Required scope: api_keys:write