Configuration reference
The reference below documents the released constructor and payload fields that are safe to explain publicly today. Secret keys belong only in server environments; browser integrations use publishable keys with allowed origins configured in the dashboard.
WavebirdClientOptions
Released package surface
Every SDK HTTP request sends x-csl-wrapper-version: <wrapper_version> as a wire-protocol header. decisionDelivery defaults to "auto", and timing values are clamped to safe ranges.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
baseUrl | string | yes | none | Base wavebird API URL. A trailing slash is normalized away. |
getApiKey | () => string | Promise<string> | server only | none | Server-side secret key resolver for wrapper-authenticated requests. Use a sandbox sk_test_... key first, then switch to a live key after production readiness is approved. |
getPublishableKey | () => string | Promise<string> | browser only | none | Browser-safe publishable key resolver. The SDK exchanges this for an activation token after the request origin matches the allowed origins configured in the dashboard. |
publishableKey | string | browser only | none | Static browser-safe publishable key alternative to getPublishableKey. Use only publishable keys in browser code. |
decisionDelivery | "auto" | "websocket" | "polling" | "callback" | no | "auto" | Decision delivery strategy for the client. |
publisher | { app_name?: string; app_domain?: string; app_bundle?: string; categories?: string[] } | no | none | Optional publisher metadata automatically merged into every createJob() request. |
options.timeout_ms | number | no | 2000 | Base request timeout. Values are clamped to the documented safe range. |
options.decision_timeout_ms | number | no | 30000 | Decision wait budget. Values are clamped to the documented safe range. |
options.long_poll_wait_ms | number | no | 1500 | Long-poll wait_ms used by decision reads. |
options.short_poll_interval_ms | number | no | 250 | Short-poll interval used after long-poll attempts are exhausted. |
options.onError | (error: WavebirdSdkError) => void | no | none | Observation hook for structured SDK errors surfaced through onError rather than thrown as hard failures. |
options.wrapper_version | string | no | "sdk" | Optional wrapper version label. Sent as x-csl-wrapper-version on every SDK request. |
JobRequest
Released public types
job_type is required and slots_requested defaults to 1. When decisionDelivery: "callback" is used without callback_url, createJob() returns null and onError receives WavebirdSdkError with code sdk_internal.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
job_type | string | yes | none | App job type. |
slots_requested | number | no | 1 | Number of requested slots. |
model_id | string | no | "unknown" | Optional model identifier for the job. |
locale | string | no | "en" | Optional app locale. |
predicted_latency_ms | number | no | none | Optional latency hint. |
client_id | string | no | runtime-derived if omitted | Optional client id. |
chat_session_id | string | no | none | Optional chat session id. |
prompt | { text?: string; token_count_estimate?: number } | string | no | none | Optional prompt payload. Sent to the wavebird runtime for topic extraction only when you choose to provide it. The data firewall reduces this to an abstract category and language before any signal reaches a configured partner path. Raw text is never forwarded. |
context.topic | string | no | none | Optional topic hint when you do not want to share prompt text. |
context.prompt_text | string | no | none | Optional prompt alias for integrations that separate explicit context from prompt capture. |
consent | ConsentFlags | no | server defaults | Optional consent flags for semantic targeting, prompt sharing, GDPR, wrapper-CMP TCF, GPP, and legacy US privacy. |
publisher | { app_name?: string; app_domain?: string; app_bundle?: string; categories?: string[] } | no | constructor defaults if configured | Optional publisher metadata automatically merged from the client constructor when configured. |
slot_config | { allowed_formats?: ("banner" | "clip" | "native")[]; max_width?: number; max_height?: number; position_hint?: string; bidfloor?: number; bidfloorcur?: string } | no | none | Optional format, size, placement, and bidfloor hints. |
brand_safety | { blocked_categories?: string[]; blocked_domains?: string[] } | no | none | Optional blocking controls for categories and advertiser domains. |
ssp_partner_id | string | no | none | Legacy single-partner selector for advanced routing cases. |
routing.preferred_partner_id | string | no | none | Preferred routing hint for new integrations. |
routing.candidate_partner_ids | string[] | no | none | Optional routing hint list for candidate partners. |
callback_url | string | no | none | Callback target for callback delivery. |
GenerationRequest
Released public types
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
generation_id | string | no | none | Identifier for the model generation. |
model_id | string | no | none | Reported model identifier. |
usage_json | unknown | no | none | Usage payload for finished or failed. |
error | string | no | none | Failure detail for the failed path. |
BeaconRequest
Released public types
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
beacon_id | string | yes | none | Idempotency input for the beacon. |
asset_token | string | yes | none | Asset authenticator for fill beacons. |
beacon_type | "rendered" | "visible_started" | "visible_ended" | "heartbeat" | "play_started" | "play_completed" | "clicked" | yes | none | Beacon type for render, visibility, playback, or click events. |
occurred_at_ms_client | number | yes | none | Client timestamp for the event. |
measurements | Record<string, unknown> | no | none | Optional measurements bag. |
Dashboard keys and configuration
Create the project in the dashboard before using the SDK. Use a sandbox secret key as WAVEBIRD_SECRET_KEY for server-side testing, and use a publishable key as NEXT_PUBLIC_WAVEBIRD_PUBLISHABLE_KEY only for browser activation from allowed origins.
Updating your project's app_domain in the dashboard immediately rewrites allowed_origins on active publishable keys for that project.
Secret keys remain valid because browser origin checks do not apply to server-side auth. If the same domain update also reflects a server deployment or ownership change, rotate the affected secret keys in the dashboard so consumers pick up a replacement key while the previous key stays valid for 24 hours.
Use this when your wrapper domain changes between preview and production, or when you move to a new canonical app host.
Rate limits
Each API key has a configurable rate limit. The default is 100 requests per minute per key. When the limit is exceeded, createJob() does not throw. It returns a typed fail-soft result instead:
rate-limit.json
json
View and adjust rate limits in the dashboard under Settings → API Keys → Advanced.
Related docs: Testing and Troubleshooting.
Choose hosted defaults or package control
These pages document the package layer for teams that choose wavebird to control ad requests, decisions, rendering helpers, consent, and beacons directly. Use the API docs for hosted defaults, and use contact only when you want rollout review, enterprise coordination, or help with non-standard integration constraints. Beacon billing rules live in SDK Concepts.