wavebird logo

Server API

Server API is the recommended default backend path. Use it when your backend already owns session state, orchestration, or rollout policy, while Wavebird owns hosted media rendering in the browser.

create-placement.sh

bash

RECOMMENDED
curl -X POST https://api.wavebird.ai/v1/placements?wait_ms=1500 \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "wbproj_your_client_id",
    "session_id": "sess_demo_123",
    "job_type": "chat",
    "slots_requested": 1,
    "slot_hint": {
      "position": "below",
      "max_width": 728,
      "max_height": 90
    },
    "overrides": {
      "allowed_formats": ["banner", "clip"],
      "timing": "during"
    }
  }'

chat.html

html

RENDER
<script src="https://api.wavebird.ai/v1/render.js"></script>
<section id="wavebird-slot" data-wavebird-endpoint="/api/sponsor-slot" hidden></section>

<script type="module">
  async function onUserMessage(message) {
    return window.wavebird.withTurn("#wavebird-slot", () => sendChatMessage(message));
  }
</script>

Backend control

Why use the server path

Own the lifecycle

Request placements from your backend without exposing secret keys to the browser.

Keep secrets server-side

The secret-key path is simpler when your app already has a backend and does not need direct browser-side monetization control.

Pair with your renderer

Use the hosted renderer for the default path, or keep raw decision polling only for advanced compatibility flows.

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