Create placement
/v1/placementsUse 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.
AUTH
CONTENT TYPE
STATUS
Request parameters
- wait_ms
- integer
- Optional
- Optional long-poll wait time in milliseconds. Defaults should stay short, for example 1500.
- test_outcome
- no_fill
- Optional
- Optional deterministic no-fill control for Test requests made with a Server Test Key. Never use it with Production keys.
- client_id
- string
- Required
- Project ID (client_id, WAVEBIRD_CLIENT_ID), formatted like wbproj_....
- session_id
- string
- Required
- Stable publisher session identifier.
- job_type
- string
- Required
- Workload category: chat, code, image, voice, agent.
- prompt
- object | string
- Optional
- Optional context. Supplied text reaches the wavebird API; targeting requires the applicable semantic_targeting and prompt_shared permissions. Prefer a controlled topic and omit raw text when it should not be transmitted. Standard SSP builders use the partner signal projection.
- slot_hint
- object
- Optional
- Placement position and maximum dimensions.
- overrides
- object
- Optional
- Advanced request-level controls: allowed_formats (banner, clip, native), native_template_id, timing, bidfloor, bidfloor_currency, publisher, blocked_categories, and related policy settings.
- consent
- object
- Optional
- Projects using wavebird_consent require a current stored consent record for the authenticated tenant, client_id, and session_id. Record the actual user decision through /v1/consent before placement; inline flags cannot replace or expand that permission.
| Name | Type | Required | Description |
|---|---|---|---|
| wait_ms | integer | Optional | Optional long-poll wait time in milliseconds. Defaults should stay short, for example 1500. |
| test_outcome | no_fill | Optional | Optional deterministic no-fill control for Test requests made with a Server Test Key. Never use it with Production keys. |
| client_id | string | Required | Project ID (client_id, WAVEBIRD_CLIENT_ID), formatted like wbproj_.... |
| session_id | string | Required | Stable publisher session identifier. |
| job_type | string | Required | Workload category: chat, code, image, voice, agent. |
| prompt | object | string | Optional | Optional context. Supplied text reaches the wavebird API; targeting requires the applicable semantic_targeting and prompt_shared permissions. Prefer a controlled topic and omit raw text when it should not be transmitted. Standard SSP builders use the partner signal projection. |
| slot_hint | object | Optional | Placement position and maximum dimensions. |
| overrides | object | Optional | Advanced request-level controls: allowed_formats (banner, clip, native), native_template_id, timing, bidfloor, bidfloor_currency, publisher, blocked_categories, and related policy settings. |
| consent | object | Optional | Projects using wavebird_consent require a current stored consent record for the authenticated tenant, client_id, and session_id. Record the actual user decision through /v1/consent before placement; inline flags cannot replace or expand that permission. |
Returns
- job_id
- string
- Server-issued job identifier for this placement. Keep it on the publisher server when reporting generation lifecycle; never accept a browser-supplied job ID.
- slot_id
- string
- Slot identifier for diagnostics and advanced compatibility.
- status
- string
- Decision state, usually pending or ready.
- placement
- object | null
- Hosted-render placement descriptor when a fill is ready.
- placement.render
- object
- Hosted frame descriptor with frame_url, script_url, media_type (image, video, or native), dimensions, label, sponsor, click URL, and native_template_id for native fills.
- decision
- object | null
- Canonical decision payload retained for compatibility and debugging.
- decision.format
- banner | clip | native
- Filled creative format. Native fills return structured assets; clip fills return video media.
- decision.assets
- object | null
- Native-only assets: title, image_url, optional description, cta_text, and icon_url. Null for banner and clip.
- decision.delivery_url
- string | null
- Banner image or clip video URL. Null for native fills because native assets are returned as structured fields.
- authoritative_consent
- object
- Decision-bound stored or request-level consent snapshot used by render.js. Rendering and beacons fail closed unless it is granted, current, and unexpired.
| Name | Type | Description |
|---|---|---|
| job_id | string | Server-issued job identifier for this placement. Keep it on the publisher server when reporting generation lifecycle; never accept a browser-supplied job ID. |
| slot_id | string | Slot identifier for diagnostics and advanced compatibility. |
| status | string | Decision state, usually pending or ready. |
| placement | object | null | Hosted-render placement descriptor when a fill is ready. |
| placement.render | object | Hosted frame descriptor with frame_url, script_url, media_type (image, video, or native), dimensions, label, sponsor, click URL, and native_template_id for native fills. |
| decision | object | null | Canonical decision payload retained for compatibility and debugging. |
| decision.format | banner | clip | native | Filled creative format. Native fills return structured assets; clip fills return video media. |
| decision.assets | object | null | Native-only assets: title, image_url, optional description, cta_text, and icon_url. Null for banner and clip. |
| decision.delivery_url | string | null | Banner image or clip video URL. Null for native fills because native assets are returned as structured fields. |
| authoritative_consent | object | Decision-bound stored or request-level consent snapshot used by render.js. Rendering and beacons fail closed unless it is granted, current, and unexpired. |
Integration guidance
Format response shapes
Banner fills expose placement.image_url and decision.delivery_url, and placement.render.media_type is image.
Clip fills expose placement.video_url and decision.delivery_url, and placement.render.media_type is video. Hosted clip rendering emits play_started and play_completed beacons automatically.
Native fills expose structured decision.assets and placement.image_url from assets.image_url. decision.delivery_url is null, and placement.render.media_type is native.
Test traffic is non-billable. Test substitute assets currently cover banner and clip media; native fills still use the normal structured native asset shape.
Per-format placement bodies
Use overrides.allowed_formats to test one format at a time in Test mode. Empty arrays and unsupported values are rejected.
[
{
"client_id": "wbproj_...",
"session_id": "sess_...",
"job_type": "chat",
"overrides": { "allowed_formats": ["banner"] }
},
{
"client_id": "wbproj_...",
"session_id": "sess_...",
"job_type": "chat",
"overrides": { "allowed_formats": ["clip"] }
},
{
"client_id": "wbproj_...",
"session_id": "sess_...",
"job_type": "chat",
"overrides": {
"allowed_formats": ["native"],
"native_template_id": "card"
}
}
]Common request errors
Malformed JSON returns validation_error with status 400.
Wrong Content-Type returns unsupported_media_type with status 415.
Invalid formats, unsupported format combinations, stale beacon timestamps, and invalid asset tokens are rejected before billing.
Errors
consent_not_current403Required stored session consent is missing, stale, denied, revoked, or outside the authenticated scope. Inline flags cannot substitute for it.
consent_state_unavailable403Required consent storage could not be read. Keep advertising off and preserve the primary app flow.
privacy_signal_policy_required403A positive Sec-GPC signal was observed. Do not strip it or retry advertising without it.
unauthorized401Missing or inactive secret key or browser activation token.
forbidden403Wrong key type for the request.
rate_limited429Key exceeded its rate limit; retry after the Retry-After header.
unsupported_media_type415Non-empty request bodies must use Content-Type: application/json.
validation_error400The request body failed validation. TCF/GPP inputs, including structurally valid strings without an authoritative policy mapping, are currently rejected.