Getting started

Quickstart

The shortest Server API path is: create a Server Test Key, call /v1/placements from your backend, pass the filled placement to the browser, load /v1/render.js, and callwavebird.renderPlacement(). No SDK or withTurn() helper is required for this REST path.

Start in the dashboard

Create a workspace, open Dashboard API Keys, and create a Server Test Key for the backend. Copy the newly revealed sk_test_... value when it is created or rotated; existing server secrets are intentionally shown only as masked previews. Also copy the Project ID (client_id, WAVEBIRD_CLIENT_ID) formatted like wbproj_..., and configure local allowed origins before browser testing.

Key classes are separate: Server Test Key (sk_test_...) for Test, Server Production Dry-run Key (sk_dry_...) for non-billable pre-live dry-run, Server Production Key for approved live server traffic, and Browser Publishable Key for browser activation. Production dry-run is selected by the sk_dry_... credential class, not by request-body flags.

WAVEBIRD_API_BASE_URL=https://api.wavebird.ai
WAVEBIRD_SECRET_KEY=sk_test_your_server_test_key
WAVEBIRD_CLIENT_ID=wbproj_your_project_id
NEXT_PUBLIC_WAVEBIRD_PUBLISHABLE_KEY=pk_publishable_your_browser_key

Server API placement request

Recommended default path for backend-owned integrations.

Server API placement request

create-placement.shbash

1curl -X POST https://api.wavebird.ai/v1/placements?wait_ms=1500 \2  -H "Authorization: Bearer sk_test_wavebird_demo_secret" \3  -H "Content-Type: application/json" \4  -d '{5    "client_id": "wbproj_demo_8jK42",6    "session_id": "sess_demo_123",7    "job_type": "chat",8    "slots_requested": 1,9    "slot_hint": {10      "position": "below",11      "max_width": 728,12      "max_height": 9013    },14    "overrides": {15      "allowed_formats": ["banner", "clip", "native"],16      "timing": "during"17    },18    "consent": {19      "semantic_targeting": false,20      "prompt_shared": false,21      "gdpr_applies": false,22      "consent_source": "wavebird_consent"23    }24  }'

Validate decisions

Check filled, pending, and no-fill paths before live traffic.

Validate consent

Dashboard-created Test projects require current lifecycle consent. Pass request-level consent with /v1/placements or sync the session through /v1/consent.

Validate rendering

Confirm renderPlacement creates one hosted frame, reaches a rendered state, and reports frame_error without positive signals when media cannot load.

Need rollout review?

Start with the Server API. Use contact only when you need rollout review, enterprise coordination, or non-standard integration help.

Contact the team

API reference

Integration paths