Guide
Server-side integration
Use this pattern when your backend owns request context and the hosted renderer owns browser media behavior.
Create placements server-side
Your backend calls /v1/placements with a secret key. Never expose that key to browsers.
Create a placement
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"],16 "timing": "during"17 },18 "consent": {19 "semantic_targeting": false,20 "prompt_shared": false,21 "consent_source": "publisher"22 }23 }'Render safely
Return the canonical decision response to the frontend and let render.js use placement.render.frame_url inside a hosted iframe.
Record beacons
The hosted renderer records rendered, visible, clicked, and playback events idempotently for the default flow.
Need rollout review?
Start with the Server API. Use contact only when you need rollout review, enterprise coordination, or non-standard integration help.