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 and lets your server own session, pacing, and fallback behavior.

Best for production GenAI apps with backend orchestration.
Uses secret keys and canonical /v1 routes.
Pairs cleanly with custom renderers and internal observability.

create-job.sh

curl -X POST https://api.wavebird.ai/v1/jobs \
  -H "Authorization: Bearer sk_test_wavebird_demo_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "wbproj_demo_8jK42",
    "session_id": "sess_demo_123",
    "job_type": "chat",
    "slots_requested": 1,
    "consent": {
      "source": "publisher",
      "purposes": {
        "ads": true,
        "measurement": true
      }
    }
  }'

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.

index.html

<script
  src="https://wavebird.ai/wavebird.js"
  data-client-id="wbproj_demo_8jK42"
  data-publishable-key="pk_test_wavebird_demo_publishable"
  data-job-type="chat">
</script>

<div
  data-wavebird-slot
  data-wavebird-formats="banner,native"
  data-wavebird-position="between">
</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.

wavebird.ts

import { CslClient } from "@csl/wrapper-sdk";

const client = new CslClient({
  baseUrl: "https://api.wavebird.ai",
  getApiKey: () => process.env.WAVEBIRD_SECRET_KEY ?? "",
});

const job = await client.createJob({
  client_id: "wbproj_demo_8jK42",
  session_id: "sess_demo_123",
  job_type: "chat",
  slots_requested: 1,
});

Quickstart

Authentication

Code

Server API request

Recommended default path for backend-owned integrations.

create-job.sh

curl -X POST https://api.wavebird.ai/v1/jobs \
  -H "Authorization: Bearer sk_test_wavebird_demo_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "wbproj_demo_8jK42",
    "session_id": "sess_demo_123",
    "job_type": "chat",
    "slots_requested": 1,
    "consent": {
      "source": "publisher",
      "purposes": {
        "ads": true,
        "measurement": true
      }
    }
  }'

Need rollout review?

Contact the team

Start in the dashboard, choose Script Tag or Server API, and use contact only when you need rollout review, enterprise coordination, or non-standard integration help. Billing beacon rules live in the API concepts guide.