Configuration
Configure your project through client_id, key class, allowed origins, project defaults, and the runtime-safe project config exposed to browsers.
POST /v1/placements
Start with the smallest valid placement body
These three fields identify the project, session, and surface. Consent requirements also depend on the project and request: Dashboard-created Test projects need current consent, supplied on the request or synchronized beforehand. Add context, hints, and overrides only when needed.
Minimal placement request body
placement.json
json
Core
Identity and keys
Project ID (client_id, WAVEBIRD_CLIENT_ID)
Public project identifier used by both browser and server flows to resolve defaults and config. In the dashboard this is the Project ID (client_id, WAVEBIRD_CLIENT_ID), formatted like wbproj_....
Publishable key
Browser-safe key used only for activation-backed traffic. It must be bound to allowed origins.
Secret key
Server-only key for canonical backend calls against /v1/placements, advanced job/decision routes, and /v1/beacons. Use a Server Test Key (sk_test_...) first for Test traffic. Copy the full value when it is created or rotated; existing server secrets are not recoverable from masked previews.
Production dry-run key
Server-only key for pre-live production dry-run checks (sk_dry_...). It selects dry-run mode by credential class; do not add production_dry_run, production_billing_dry_run, billing_suppressed, or production_live_approved to request bodies.
Project config
Runtime defaults
Format and label defaults
Preferred formats, slot hints, disclosure labels, and other non-secret defaults are resolved from the authenticated key's project and client_id. Advanced Server API calls can override supported fields such as allowed_formats, timing, bidfloor, publisher, and blocked_categories.
Allowed origins and browser safety
Allowed origins gate publishable-key activation. Browser-safe integration is not just about the key prefix; it depends on server-side origin enforcement.
Operational notes
Change behavior
Config propagation
Changes apply through the active project config path. Browser integrations pick them up on the next activation or the next initialization cycle.
Runtime rules
Rate limits and CORS
| Surface | Key type | Origin behavior | Limit behavior |
|---|---|---|---|
/v1/placements, /v1/jobs, /v1/decisions, /v1/beacons | Secret key | Server-to-server requests do not depend on browser origin allowlists. | Per-key buckets; 429 includes Retry-After. |
/v1/browser/activate | Publishable key | The request origin must match the key's allowed origins. | Publishable-key and browser-IP buckets protect activation. |
| Browser token calls | Activation token | Preflight can succeed for candidate origins; the actual request is still checked against stored project/key state. | Separated from secret-key traffic so sandbox and live integrations do not share counters. |
Related reference
Key classes and rotation · Rate limits and retries · Compatibility routes
Need help with your integration?
Share the affected endpoint, request ID, and the behavior you expected. Leave out keys and user content.