# wavebird

> wavebird is ad infrastructure for consumer AI apps. Its decision and proof paths keep sponsored placements beside AI answers, never inside model output, with consent and data-minimization boundaries. wavebird does not generate ad creative or campaigns with AI, does not insert sponsor content into prompts or model output, and is not an SSP, DSP, ad network, or model provider.

The current developer status is: API v1 is stable, `/v1/consent` is beta, and `/v1/jobs` plus `/v1/decisions/{slot_id}` are advanced; see [API stability](https://wavebird.ai/api/reference/stability).

## API documentation

### Start
- [API reference](https://wavebird.ai/api)
- [Quickstart](https://wavebird.ai/api/quickstart)
- [Integration paths](https://wavebird.ai/api/integration-paths): Choose between the Server API, Script Tag, and advanced SDK.
- [Testing](https://wavebird.ai/api/testing): Testing strategy for the wavebird API: sandbox keys, placement checks, hosted rendering validation, and full beacon-path verification.
- [Troubleshooting](https://wavebird.ai/api/troubleshooting): Troubleshoot the wavebird API by checking key class, activation, client_id, decision state, brand-safety policy, and beacon delivery.

### Core API
- [API v1 overview](https://wavebird.ai/api/v1): Canonical wavebird API v1 reference for placements, hosted rendering, activation, jobs, decisions, beacons, consent, project config, and GenAI ad infrastructure.
- [Browser activation](https://wavebird.ai/api/v1/browser-activate): Use this from browser integrations before creating jobs. Send the publishable key in the JSON body; the API validates the Origin header against the key's allowed-origins list.
- [Placements](https://wavebird.ai/api/v1/placements): Use this as the default Server API entry point. It combines job creation and first-decision wait so your frontend can hand the response to the hosted renderer instead of manually building media DOM.
- [Jobs](https://wavebird.ai/api/v1/jobs): Use this when you intentionally need job-plus-decision orchestration. New Server API integrations should start with POST /v1/placements. Browser-activation requests use a separate public-contract branch with contract_version and job.job_type.
- [Decisions](https://wavebird.ai/api/v1/decisions): Call this after job creation only for advanced flows. Filled decisions include placement.render so the hosted renderer can own media, sizing, click, and beacon behavior.
- [Renderer script](https://wavebird.ai/api/v1/render-js): Load this script in the customer frontend for the default Server API render path. Use window.wavebird.renderPlacement for REST placement responses. startTurn and withTurn remain optional Script Tag lifecycle helpers.
- [Render frame](https://wavebird.ai/api/v1/render-frame): The hosted renderer creates an iframe for this route. Customer frontends should not construct this URL manually in the default flow; use placement.render.frame_url.
- [Beacons](https://wavebird.ai/api/v1/beacons): Advanced direct server path. Default integrations should render placement.render with the hosted renderer, which sends browser beacons automatically to /public/wrapper/v1/beacons. Direct beacon writes are for server-rendered, custom-rendered, or QA validation flows; they require the sensitive asset_token returned with the placement or decision and are idempotent by beacon_id.
- [Consent](https://wavebird.ai/api/v1/consent): Optional session/user-level consent sync. It is separate from request-level placement consent and is not required before /v1/placements when that request already carries consent flags.
- [Project config](https://wavebird.ai/api/v1/project-config): Use this to inspect the server-stored defaults that jobs use. Secret values are never returned by this endpoint.

### Guides
- [Server API](https://wavebird.ai/api/patterns/server-api)
- [Script Tag](https://wavebird.ai/api/patterns/script-tag): Browser-first pattern for wavebird: Script Tag, publishable-key activation, auto-discovered slots, consent, and beacons.
- [Going live](https://wavebird.ai/api/guides/going-live): Launch checklist for partner integrations.
- [Privacy](https://wavebird.ai/api/privacy): Privacy model for the wavebird API: minimized delivery signals, consent-bounded relevance, and no prompt leakage to SSPs.
- [Brand safety](https://wavebird.ai/api/brand-safety): Brand-safety controls for the wavebird API: allowed formats, blocked categories, blocked domains, and fail-closed behavior.
- [Consent in consumer AI apps](https://wavebird.ai/api/guides/consent-genai): Consent patterns for chat, search, and agent flows.

### Reference
- [Authentication](https://wavebird.ai/api/reference/authentication): Key classes, browser activation, and origin rules for Wavebird API requests.
- [API stability](https://wavebird.ai/api/reference/stability): Stability levels for the public Wavebird API v1 endpoints.
- [Errors](https://wavebird.ai/api/reference/errors): Standard error envelope and common error codes.
- [Rate limits](https://wavebird.ai/api/reference/rate-limits): Rate-limit behavior for public API endpoints.
- [Versioning](https://wavebird.ai/api/reference/versioning): wavebird API versioning policy for the stable v1 REST surface, compatibility aliases, changelog practice, and production base URL.
- [Types](https://wavebird.ai/api/reference/types): Public runtime shape reference for the wavebird API: Script Tag attributes, methods, events, and rate-limit notes.
- [Request IDs](https://wavebird.ai/api/reference/request-ids): How request IDs help diagnose failures.
- [CORS and origins](https://wavebird.ai/api/reference/cors): Browser origin policy for publishable-key calls.
- [Changelog](https://wavebird.ai/api/changelog): Wavebird API and docs changes.
- [FAQ](https://wavebird.ai/api/faq): Developer FAQ for the wavebird API. API-first integration questions, Script Tag guidance, Server API guidance, and SDK positioning.

### Advanced
- [SDK](https://wavebird.ai/api/sdk): Public wavebird SDK package for TypeScript teams that need package-level control over AI ad requests, rendering, and beacons.
- [Callback](https://wavebird.ai/api/patterns/callback): Advanced callback pattern for wavebird when decision delivery should be handed back to your server through a callback flow.
- [Proxy](https://wavebird.ai/api/patterns/proxy): Proxy compatibility pattern for wavebird when your app must stay behind a controlled HTTP boundary.
- [Multi-region](https://wavebird.ai/api/guides/multi-region): Planning notes for multi-region publisher stacks.
- [Reliability](https://wavebird.ai/api/reference/reliability): Operational expectations without unsupported SLA claims.
- [Migration](https://wavebird.ai/api/migration): Migrate wavebird integrations from SDK-first onboarding to Server API first, Script Tag second, and SDK third.
## REST API

- [POST /v1/browser/activate](https://wavebird.ai/api/v1/browser-activate.md): Exchanges a publishable key and origin for a short-lived browser activation token.
- [POST /v1/placements](https://wavebird.ai/api/v1/placements.md): Creates one job, waits for the first slot decision, and returns the canonical placement response.
- [POST /v1/jobs](https://wavebird.ai/api/v1/jobs.md): Advanced compatibility route that creates a sponsorship job and returns one or more slot IDs.
- [GET /v1/decisions/{slot_id}](https://wavebird.ai/api/v1/decisions.md): Polls a slot for the selected sponsored asset and render metadata.
- [GET /v1/render.js](https://wavebird.ai/api/v1/render-js.md): Returns the browser renderer that mounts hosted placement frames and manages turn lifecycle.
- [GET /v1/render/{asset_token}](https://wavebird.ai/api/v1/render-frame.md): Returns isolated creative HTML for a single asset token.
- [POST /v1/beacons](https://wavebird.ai/api/v1/beacons.md): Records render, visible, click, completion, or heartbeat events for billing and proof integrity.
- [POST /v1/consent](https://wavebird.ai/api/v1/consent.md): Stores publisher consent state for Script Tag and custom consent flows.
- [GET /v1/projects/{client_id}/config](https://wavebird.ai/api/v1/project-config.md): Returns non-secret runtime configuration for a project.

## Script Tag

- [Script Tag installation](https://wavebird.ai/api/script-tag.md)
- [Script Tag integration pattern](https://wavebird.ai/api/patterns/script-tag)

## SDK

- [SDK quickstart](https://wavebird.ai/sdk/quickstart.md)
- [SDK installation](https://wavebird.ai/sdk/installation.md)
## SDK documentation

### Getting started
- [SDK overview](https://wavebird.ai/sdk)
- [Installation](https://wavebird.ai/sdk/installation): Install the Wavebird SDK package.
- [SDK Quickstart](https://wavebird.ai/sdk/quickstart)
- [Concepts](https://wavebird.ai/sdk/concepts)
- [Migration from SDK-first](https://wavebird.ai/sdk/migration): Move SDK-first integrations to API-first or Script Tag paths.

### Integration
- [Integration flow](https://wavebird.ai/sdk/integration-flow)
- [Configuration](https://wavebird.ai/sdk/configuration)
- [Consent and CS](https://wavebird.ai/sdk/consent)
- [Privacy](https://wavebird.ai/sdk/privacy)
- [Disclosure template](https://wavebird.ai/sdk/disclosure)
- [Privacy policy template](https://wavebird.ai/sdk/privacy-template)
- [Brand safety](https://wavebird.ai/sdk/brand-safety)
- [Testing](https://wavebird.ai/sdk/testing)
- [Troubleshooting](https://wavebird.ai/sdk/troubleshooting)
- [Graceful degradation](https://wavebird.ai/sdk/graceful-degradation)

### Patterns
- [Patterns overview](https://wavebird.ai/sdk/patterns)
- [SDK Server Integration](https://wavebird.ai/sdk/patterns/node)
- [SDK Browser Integration](https://wavebird.ai/sdk/patterns/browser)
- [Callback delivery](https://wavebird.ai/sdk/patterns/callback)
- [Proxy compatibility](https://wavebird.ai/sdk/patterns/proxy)

### Reference
- [Reference overview](https://wavebird.ai/sdk/reference)
- [Methods](https://wavebird.ai/sdk/reference/methods): Public methods exposed by WavebirdClient.
- [WavebirdClient](https://wavebird.ai/sdk/reference/wavebird-client)
- [Types](https://wavebird.ai/sdk/reference/types)
- [React components](https://wavebird.ai/sdk/reference/react-components): React component status for the advanced SDK.
- [Routes](https://wavebird.ai/sdk/reference/routes)
- [FAQ](https://wavebird.ai/sdk/faq)
## Resources

- [Ad revenue](https://wavebird.ai/guides/ad-revenue): How much ad revenue can a consumer AI app generate, and how is it calculated?
- [Monetization options](https://wavebird.ai/guides/ai-monetization): How do ads fit alongside subscriptions and credits?
## Machine-readable docs

- [API quickstart Markdown](https://wavebird.ai/api/quickstart.md)
- [SDK quickstart Markdown](https://wavebird.ai/sdk/quickstart.md)

Last updated: generated from checked-in docs models.
Source: https://wavebird.ai