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 tokenSandbox this Open as Markdown ↗

Request parameters

wait_ms: integer; Optional; Optional long-poll wait time in milliseconds. Defaults should stay short, for example 1500.

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. Prefer { topic, text }; raw text is processed only when prompt_shared is true and is never sent to SSPs or advertisers.

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; Request-level consent flags: semantic_targeting, prompt_shared, gdpr_applies, and consent_source.

Name	Type	Required	Description
wait_ms	integer	Optional	Optional long-poll wait time in milliseconds. Defaults should stay short, for example 1500.
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. Prefer { topic, text }; raw text is processed only when prompt_shared is true and is never sent to SSPs or advertisers.
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	Request-level consent flags: semantic_targeting, prompt_shared, gdpr_applies, and consent_source.

Returns

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.

Name	Type	Description
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.

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.

Sandbox/test traffic is non-billable. Sandbox substitute test 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/Sandbox. 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

CODESTATUSWHEN IT HAPPENS

unauthorized401

Missing secret key.

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.

API v1 overview Testing in sandbox Errors