Create placement

POST/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.

AUTH

Secret key or browser activation token

CONTENT TYPE

application/json

STATUS

Stable
Secret key or browser activation tokenVerification stepsOpen as Markdown ↗

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.

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.

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_current403

Required stored session consent is missing, stale, denied, revoked, or outside the authenticated scope. Inline flags cannot substitute for it.

consent_state_unavailable403

Required consent storage could not be read. Keep advertising off and preserve the primary app flow.

privacy_signal_policy_required403

A positive Sec-GPC signal was observed. Do not strip it or retry advertising without it.

unauthorized401

Missing or inactive secret key or browser activation token.

forbidden403

Wrong key type for the request.

rate_limited429

Key exceeded its rate limit; retry after the Retry-After header.

unsupported_media_type415

Non-empty request bodies must use Content-Type: application/json.

validation_error400

The request body failed validation. TCF/GPP inputs, including structurally valid strings without an authoritative policy mapping, are currently rejected.

Related

Need help with your integration?

Share the affected endpoint, request ID, and the behavior you expected. Leave out keys and user content.

Contact the team