API Reference

API v1 reference

API v1 is the canonical public runtime surface. The Server API is first priority, the Script Tag is second, and the SDK is an advanced compatibility layer over these same routes.

POST/v1/browser/activate

Activate browser key

Use this from browser integrations before creating jobs. Send the publishable key in the JSON body; the API validates the Origin header against the key's allowed-origins list.

Auth: No Authorization header; publishable key in JSON body with allowed Origin

Sandbox this Details

POST/v1/jobs

Create job

Use this as the main server-side entry point. Server-stored project configuration is loaded by client_id and merged with documented request-level overrides.

Auth: Secret key, or activation token for browser flows

Sandbox this Details

GET/v1/decisions/{slot_id}

Get decision

Call this after job creation when you are rendering manually instead of using the Script Tag or SDK helper.

Auth: Secret key or browser activation context

Sandbox this Details

POST/v1/beacons

Record beacon

Send one event per user-observable lifecycle transition. Beacon writes are designed to be idempotent by beacon_id.

Auth: Secret key, browser activation context, or asset token where issued

Sandbox this Details

POST/v1/consent

Record consent

Use this when you collect consent outside the built-in Script Tag dialog or need to sync a CMP result into wavebird.

Auth: Secret key, or activation token for browser flows

Sandbox this Details

GET/v1/projects/{client_id}/config

Get project config

Use this to inspect the server-stored defaults that jobs use. Secret values are never returned by this endpoint.

Auth: Secret key or authorized project context

Sandbox this Details

Ad formats

Browser activation

Code

Activate browser key

Exchanges a publishable key and origin for a short-lived browser activation token.

activate.sh

curl -X POST https://api.wavebird.ai/v1/browser/activate \
  -H "Origin: https://publisher.example" \
  -H "Content-Type: application/json" \
  -d '{
    "publishable_key": "pk_test_wavebird_demo_publishable"
  }'

Need rollout review?

Contact the team

Start in the dashboard, choose Script Tag or Server API, and use contact only when you need rollout review, enterprise coordination, or non-standard integration help. Billing beacon rules live in the API concepts guide.