Configuration
Configuration now centers on the API contract rather than SDK options. The important boundaries are 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 are the three required fields for a placement request. Add optional context, hints, overrides, or consent only when the integration needs them.
Minimal placement request body
placement.json
json
On 429 the documented error code is rate_limited; retry after the Retry-After header. The public endpoint model does not define a JSON error-envelope shape.
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/Sandbox traffic.
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.
Rate limits
Public routes enforce per-key limits and return the standard error envelope with Retry-After on 429 responses.
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. |
Lifecycle
Key rotation and compatibility
Rotation
Rotate keys from Dashboard API Keys, copy the newly revealed value once, and update clients before removing old credentials. Existing server secret values are not recoverable from masked previews; create or rotate a Server Test Key when you need a usable sk_test_... value. Existing revoked keys should be treated as unavailable immediately unless your dashboard shows a grace deadline.
Compatibility aliases
Older public wrapper and browser activation paths remain compatibility aliases. New snippets and docs should use canonical /v1 routes.
Need rollout review?
Start with the Server API. Use contact only when you need rollout review, enterprise coordination, or non-standard integration help.