wavebird logo

Getting started

Integration paths

Pick the smallest integration path that matches where your app controls rendering and consent.

Server API is the default

Use the Server API when your app already has a backend. It keeps secret keys out of the browser while the hosted renderer owns media sizing, clicks, and beacons.

  • Best for production GenAI apps with backend orchestration.
  • Uses secret keys and POST /v1/placements.
  • Pairs cleanly with render.js and wavebird.withTurn().

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"],16      "timing": "during"17    },18    "consent": {19      "semantic_targeting": false,20      "prompt_shared": false,21      "consent_source": "publisher"22    }23  }'

Script Tag is the browser path

Use the Script Tag when you want a browser slot to activate, request, render, and beacon with minimal application code.

  • Uses publishable keys plus allowed origins.
  • Handles consent UI when configured.
  • Keeps publisher markup small and framework independent.

Script Tag install

index.htmlhtml
1<script2  src="https://wavebird.ai/wavebird.js"3  data-client-id="wbproj_demo_8jK42"4  data-publishable-key="pk_test_wavebird_demo_publishable"5  data-job-type="chat">6</script>7 8<div9  data-wavebird-slot10  data-wavebird-formats="banner,native"11  data-wavebird-position="between">12</div>

SDK is advanced compatibility

Use the SDK only when a TypeScript wrapper is intentionally better than direct REST or Script Tag markup. The SDK remains a thin compatibility layer over the same API.

  • Useful for existing SDK-first integrations.
  • Still supported for backwards compatibility.
  • Not the primary onboarding surface.

Advanced SDK

wavebird.tstypescript
1import { CslClient } from "@csl/wrapper-sdk";2 3const client = new CslClient({4  baseUrl: "https://api.wavebird.ai",5  getApiKey: () => process.env.WAVEBIRD_SECRET_KEY ?? "",6});7 8const job = await client.createJob({9  client_id: "wbproj_demo_8jK42",10  session_id: "sess_demo_123",11  job_type: "chat",12  slots_requested: 1,13});

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