API reference

List workspaces

Required scope: workspaces:read · 200 Workspaces visible to the key.

Create a workspace

Required scope: workspaces:write · JSON body · 201 The created workspace. · supports Idempotency-Key

Get a workspace

• id (path): uuid

Required scope: workspaces:read · 200 The workspace, including its advertiser domain, IAB category, and disclosure level.

Update workspace settings

Advertiser domain and IAB category (set together; delivery needs them before a campaign can run, and they apply to every campaign in the workspace) and/or disclosureLevel, what client roles see of spend: billed_rates (spend at your rate multiplier), percent_delivery (no spend), or full_transparency (actual spend). Client roles cannot change settings.

• id (path): uuid

Required scope: workspaces:write · JSON body · 200 The updated workspace.

List campaigns in a workspace

• workspaceId (query, required)
• status (query): Filter by status.

Required scope: campaigns:read · 200 Campaigns ordered by creation date.

Create a campaign

Required scope: campaigns:write · JSON body · 201 The created campaign (sync to delivery is asynchronous). · supports Idempotency-Key

Get a campaign

• id (path): uuid

Required scope: campaigns:read · 200 The campaign.

Update a campaign

Also used for pause/resume via the status field.

• id (path): uuid

Required scope: campaigns:write · JSON body · 200 The updated campaign.

List line items in a campaign

• campaignId (query, required)

Required scope: line_items:read · 200 Line items ordered by creation date.

Create a line item

Targeting other than the default (untargeted) also needs the targeting:write scope.

Required scope: line_items:write · JSON body · 201 The created line item. · supports Idempotency-Key

Get a line item

• id (path): uuid

Required scope: line_items:read · 200 The line item, including its targeting.

Update a line item

Budget, bid, pacing, targeting, and status (pause/resume/activate) changes. `targeting` replaces the whole object, except that an omitted `adsTxtOnly` or `defaultExchanges` keeps its current value. A body that includes `targeting` also needs the targeting:write scope.

• id (path): uuid

Required scope: line_items:write · JSON body · 200 The updated line item.

Attach a creative to a line item

• id (path): uuid

Required scope: line_items:write · JSON body · 201 The association.

List the creatives on a line item

• id (path): uuid

Required scope: line_items:read · 200 Attached creatives (removed ones excluded).

Remove a creative from a line item

A running line item must keep at least one creative: attach the replacement first, or pause it.

• id (path): uuid
• creativeId (query, required)

Required scope: line_items:write · 200 No content.

List creatives in a workspace

• workspaceId (query, required)

Required scope: creatives:read · 200 Creatives ordered by creation date.

Create a creative

Assets are URL-based. Video/audio sync asynchronously. HTML5 may use an inline `html` body (Creative Studio / Waveforms produce ordinary html5 creatives this way; there is no separate Waveform type). For Soundframe (audio-led video), omit assets and set render.kind=audio_led_video. Supply audioSource and/or script (with targetDurationSeconds + voicePreset), and imageSource and/or imagePrompt (script alone can drive both); the worker generates gaps, renders MP4 (≤90s), then syncs as a normal video creative.

Required scope: creatives:write · JSON body · 201 The created creative. · supports Idempotency-Key

Get a creative

• id (path): uuid

Required scope: creatives:read · 200 The creative with processing status.

Look up targeting reference values

Values for targeting fields that take ids: metros (DMA codes), regions, cities (numeric city ids), inventorySources (exchanges), contentGenres. `q` searches labels (cities need 2+ characters); `values=a,b` returns the labels for stored values (up to 100). At most 50 results.

• kind (path): Which reference list.
• q (query): Search text.
• values (query): Comma-separated values to label.

Required scope: targeting:read · 200 Matching options as { value, label } items.

Forecast available impressions

Available supply matching the targeting over the flight (UTC, from tomorrow, at most 31 days). Not a delivery promise and not unique reach. Forecast capacity is shared and limited per account per minute: when it is used up the result is status unavailable with reason busy; retry in a minute. Identical queries are cached for 30 minutes.

Required scopes (all of): line_items:read, targeting:read · JSON body · 200 status ok with impressions, low, high, days, and unaccounted settings; or status unavailable with a reason.

Price an AI ad generation

Nothing is reserved or charged. Returns the typical and maximum cost in USD cents.

Required scopes (all of): creatives:write, ai:invoke · JSON body · 200 maxUsdMinor, typicalUsdMinor, creatives, and availableUsdMinor.

Generate ads with AI

Charges the wallet: up to the quoted maximum is set aside now and settled to the actual cost when the ads are delivered. Quote first. The ads appear as processing creatives in the workspace.

Required scopes (all of): creatives:write, ai:invoke · JSON body · 201 generationId, prepaidUsdMinor, and the number of creatives. · supports Idempotency-Key

List recent AI ad generations

• workspaceId (query, required)

Required scope: creatives:read · 200 The 20 most recent generations, newest first.

Update or archive a deal

Set status archived to archive. Line items can no longer target an archived deal.

• id (path): uuid

Required scope: catalog:write · JSON body · 200 The updated deal.

List curated deals you can activate

Required scope: catalog:read · 200 Platform curated deals, each marked alreadyActivated when in your library.

Activate a curated deal

Copies the curated deal into your deal library so line items can target it. Returns the existing deal when it is already there.

• id (path): uuid

Required scope: catalog:write · JSON body · 201 The library dealId.

List conversion events

• workspaceId (query, required)

Required scope: events:read · 200 Conversion event definitions.

Create a conversion event

Required scope: events:write · JSON body · 201 The created conversion event with its tracking snippet. · supports Idempotency-Key

List audience segments in a workspace

• workspaceId (query, required)
• status (query): Filter by status (active | archived).

Required scope: audiences:read · 200 Segments with matched counts and provisioning status.

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 · JSON body · 201 The created segment (upstream materialization is asynchronous). · supports Idempotency-Key

Get an audience segment

• id (path): uuid

Required scope: audiences:read · 200 The segment.

Archive an audience segment

• id (path): uuid

Required scope: audiences:write · 200 The archived segment.

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.

• id (path): uuid

Required scope: audiences:write · JSON body · 201 The upload batch with accepted counts.

Attach or detach a segment on a line item

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

• id (path): uuid

Required scopes (all of): audiences:write, targeting:write · JSON body · 200 The updated line item.

Search the third-party segment marketplace

• q (query): Optional search across name, taxonomy path, provider, and description. Omit to browse.
• provider (query): Filter by data provider.
• minCpm (query): Minimum data CPM in USD dollars (inclusive).
• maxCpm (query): Maximum data CPM in USD dollars (inclusive).
• minReach (query): Minimum provider-reported reach (inclusive).
• sort (query): Result ordering (default path).
• limit (query)
• offset (query): Pagination offset (default 0).

Required scope: audiences:read · 200 { items, total }: catalog rows with data CPM and reach.

Query metrics

Aggregated delivery/performance rows, including video/audio starts, quartiles, completes, and completionRate (completes / starts, null when nothing played). Grouped by creative, conversions are null: they are attributed per line item. format=csv streams a CSV export.

• workspaceId (query, required)
• from (query, required): YYYY-MM-DD inclusive.
• to (query, required): YYYY-MM-DD inclusive.
• groupBy (query)
• campaignId (query)
• format (query)

Required scope: reports:read · 200 Metric rows at the requested grain.

List domain events

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

• entityType (query)
• entityId (query)
• limit (query)

Required scope: webhooks:read · 200 Events, newest first.

List webhook endpoints

Required scope: webhooks:read · 200 Registered endpoints (secrets omitted).

Create a webhook endpoint

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

Required scope: webhooks:write · JSON body · 201 The endpoint including its one-time signing secret. · supports Idempotency-Key

Delete a webhook endpoint

• id (path): uuid

Required scope: webhooks:write · 200 Deletion confirmation.

List webhook deliveries

• endpointId (query)
• limit (query)

Required scope: webhooks:read · 200 Delivery attempts with status and response codes.

Replay a webhook delivery

• id (path): uuid

Required scope: webhooks:write · 200 The re-queued delivery.

List API keys

Required scope: api_keys:read · 200 Keys with prefixes only (never full secrets).

Create an API key

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

Required scope: api_keys:write · JSON body · 201 The created key including its one-time plaintext.

Revoke an API key

• id (path): uuid

Required scope: api_keys:write · 200 Revocation confirmation.

List rate cards

Required scope: catalog:read · 200 The tenant's rate cards (client-facing CPM by channel).

Create a rate card

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

Required scope: catalog:write · JSON body · 201 The created rate card. · supports Idempotency-Key

Update a rate card

Edit name, description, or entries; isDefault true makes it the tenant default; status archived retires it.

• id (path): uuid

Required scope: catalog:write · JSON body · 200 The updated rate card.

List productized packages

• status (query)

Required scope: catalog:read · 200 Sellable packages with targeting, floors, and pricing.

Create a package

Required scope: catalog:write · JSON body · 201 The created package. · supports Idempotency-Key

Get a package

• id (path): uuid

Required scope: catalog:read · 200 The package with targeting, floors, and pricing.

Update a package

Only the fields sent change. The channel is fixed; status archived retires it.

• id (path): uuid

Required scope: catalog:write · JSON body · 200 The updated package.

Apply a playbook as a package

Send either { vertical } for a vertical playbook or { supplyPlaybookId } for a supply playbook. Creates a tenant-owned package you can then edit.

Required scope: catalog:write · JSON body · 201 The created package. · supports Idempotency-Key

Instantiate a package into a draft campaign

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

• id (path): uuid

Required scopes (all of): catalog:read, campaigns:write · JSON body · 201 The created campaignId, lineItemId, and applied CPM.

List curated deals

• workspaceId (query)
• status (query)

Required scope: catalog:read · 200 The tenant's curated deal library.

Add a deal to the library

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

Required scope: catalog:write · JSON body · 201 The created deal. · supports Idempotency-Key

List proposals in a workspace

• workspaceId (query, required)

Required scope: campaigns:read · 200 Proposals with status and public share tokens.

Get a proposal

• id (path): uuid

Required scope: campaigns:read · 200 The proposal with items, status, signature, and share token.

Create a proposal

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

Required scope: campaigns:write · JSON body · 201 The created proposal (status draft). · supports Idempotency-Key

Mark a proposal sent

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

• id (path): uuid

Required scope: campaigns:write · 200 The proposal with status sent.

Price a media plan

Send tiers of channel splits (percent of each tier budget). Budgets, CPMs from the default rate card (baseline when unpriced), and impression forecasts are computed. Nothing is saved.

Required scope: campaigns:read · JSON body · 200 { tiers } with priced lines.

List media plans in a workspace

• workspaceId (query, required)

Required scope: campaigns:read · 200 Saved media plans, newest first.

Save a media plan

Same splits as the preview plus workspace, name, and brief. Pricing is computed server-side, never taken from the request.

Required scope: campaigns:write · JSON body · 201 The saved media plan with priced tiers. · supports Idempotency-Key

Get a media plan

• id (path): uuid

Required scope: campaigns:read · 200 The media plan with priced tiers.

Book overview

Every client workspace with health score and band, 14-day spend against the prior 14 days, active campaigns, and pending change requests; plus cross-tenant channel benchmarks (shown only when enough tenants contribute).

Required scope: reports:read · 200 { clients, benchmarks }

Generate a Studio display set

AI writes the headline, subline, and call to action from the brief; html5 creatives are rendered for each size (or the chosen Waveform). AI use draws on the tenant's AI funding.

Required scopes (all of): creatives:write, ai:invoke · JSON body · 201 { creativeIds, sizes } · supports Idempotency-Key

Get billing position

Billing mode, wallet balance and the amount available to fund delivery (prepaid wallet), unbilled balance, and plan limits with current usage.

Required scope: billing:read · 200 The tenant's billing overview.

List ledger entries

Newest first. Charges are positive, payments and credits negative.

• limit (query): Default 100.
• offset (query): Rows to skip.

Required scope: billing:read · 200 Ledger entries.

Create a wallet top-up link

Returns a hosted checkout URL that a person opens to pay. Creating the link charges nothing; the wallet is credited once payment completes. New accounts have a top-up limit in their first 30 days.

Required scope: billing:write · JSON body · 201 The checkout url and amount. · supports Idempotency-Key

List automations in a workspace

• workspaceId (query, required)

Required scope: automations:read · 200 Autopilot automations with goal, cadence, policy, and status.

Create an automation

Required scope: automations:write · JSON body · 201 The created automation. · supports Idempotency-Key

Update an automation

Also pauses (status "paused", the kill switch) or resumes it.

• id (path): uuid

Required scope: automations:write · JSON body · 200 The updated automation.

List decisions

The explainable log of automation and agent decisions; proposed ones await approval.

• workspaceId (query, required)
• status (query)
• limit (query): Default 100.

Required scope: automations:read · 200 Decisions, newest first.

Approve a decision

Applies a proposed decision. Tokens bound to an agent policy get 403. Audience decisions also need audiences:write.

• id (path): uuid

Required scope: automations:write · 200 The updated decision.

Reject a decision

Rejects a proposed decision; nothing is applied.

• id (path): uuid

Required scope: automations:write · 200 The updated decision.

Undo a decision

Restores the previous values of an applied decision. Audience decisions also need audiences:write.

• id (path): uuid

Required scope: automations:write · 200 The updated decision.

Create a report share link

A read-only report URL that works without signing in. Default expiry is 30 days.

Required scope: reports:write · JSON body · 201 The share link id, url, and expiry. · supports Idempotency-Key

Revoke a report share link

• id (path): uuid

Required scope: reports:write · 200 Confirmation that the link no longer opens.

Narrate a report

A plain-English summary of what happened, why, and what to do next. Runs an AI model; usage on platform models is billed.

Required scopes (all of): reports:read, ai:invoke · JSON body · 200 The narrative and the number of report rows it covers.

List case studies in a workspace

• workspaceId (query, required)

Required scope: catalog:read · 200 Case studies, newest first.

Generate a case study

Computes the campaign's real delivery metrics and has an AI model write the story around them; the numbers are never model output. Usage on platform models is billed.

Required scopes (all of): campaigns:read, reports:read, catalog:write, ai:invoke · JSON body · 201 The saved case study. · supports Idempotency-Key

Get a case study

• id (path): uuid

Required scope: catalog:read · 200 The case study with sections and metrics.

List change requests

• workspaceId (query)
• status (query)

Required scope: approvals:read · 200 Client change requests, newest first.

Submit a change request

Proposes a campaign change (pause, activate, budget) for the agency to review.

Required scopes (all of): approvals:write, campaigns:read · JSON body · 201 The pending change request. · supports Idempotency-Key

Review a change request

Approving applies the change with the reviewer's permissions and guardrails.

• id (path): uuid

Required scope: campaigns:write · JSON body · 200 The reviewed change request.

List audience marketplace providers

Required scope: audiences:read · 200 Providers with segment counts, and catalog freshness.

List people

Everyone with access to the tenant: staff and client logins. Workspace-bound people are listed only when the key can see their workspace.

Required scope: members:read · 200 People with membershipId, email, role, and workspaceId.

Invite a person

Creates or reuses the user by email and grants a role. Client roles need a workspaceId. The person signs in with an emailed code. Rejected when they already have access (change their role instead).

Required scope: members:write · JSON body · 201 The new membership (membershipId, userId, email, role, workspaceId). · supports Idempotency-Key

Change a person's role

Replaces the role and workspace binding of a membership. Send workspaceId null for tenant-wide access. You cannot change your own role.

• id (path): uuid

Required scope: members:write · JSON body · 200 The updated membership.

Remove a person

Revokes the membership. You cannot remove your own access.

• id (path): uuid

Required scope: members:write · 200 { deleted: true }

Invite a client login

Grants a client role (viewer, approver, collaborator) bound to one workspace. Client logins see only that workspace.

Required scope: members:write · JSON body · 201 The new client membership. · supports Idempotency-Key

List teams

Required scope: members:read · 200 Teams with their staff role, members, and workspace assignments.

Create a team

A team gives a group of staff one role across a set of client workspaces.

Required scope: members:write · JSON body · 201 The created team. · supports Idempotency-Key

Change team members and workspaces

Adds and removes members (people already in the tenant, staff only) and, when workspaceIds is sent, replaces the team's workspaces. All changes apply together or not at all.

• id (path): uuid

Required scope: members:write · JSON body · 200 The team with its members and workspaces.

Delete a team

• id (path): uuid

Required scope: members:write · 200 { deleted: true }

Get branding

Required scope: branding:read · 200 Product name, logos, colors, skin, support and email settings.

Update branding

Changes only the fields sent. Image fields take an https URL; uploading logo files is done in the console.

Required scope: branding:write · JSON body · 200 The full branding record after the change.

List custom domains

Required scope: domains:read · 200 Domains with status and the DNS records to add.

Add a custom domain

Registers a hostname for the white-label console. Add every record in verificationRecords at your DNS provider; status moves from pending_dns to pending_ssl to active.

Required scope: domains:write · JSON body · 201 The domain with status and verificationRecords (type, name, value, purpose). · supports Idempotency-Key

Get a custom domain

Poll this for verification status; it is re-checked in the background.

• id (path): uuid

Required scope: domains:read · 200 The domain with status, verificationRecords, lastError, and lastCheckedAt.

Re-check a custom domain

Checks verification now instead of waiting for the background check.

• id (path): uuid

Required scope: domains:write · 200 The domain with its current status and verificationRecords.

Remove a custom domain

• id (path): uuid

Required scope: domains:write · 200 Deletion confirmation.