# Create placement

Creates one job, waits for the first slot decision, and returns the canonical placement response.

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.

| Method | Path | Authentication | Stability |
| --- | --- | --- | --- |
| POST | /v1/placements | Secret key or browser activation token | stable |

## Request fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| wait_ms | integer | No | Optional long-poll wait time in milliseconds. Defaults should stay short, for example 1500. |
| test_outcome | no_fill | No | Optional deterministic no-fill control for Test requests made with a Server Test Key. Never use it with Production keys. |
| client_id | string | Yes | Project ID (client_id, WAVEBIRD_CLIENT_ID), formatted like wbproj_.... |
| session_id | string | Yes | Stable publisher session identifier. |
| job_type | string: chat, code, image, voice, agent | Yes | Workload category: chat, code, image, voice, agent. |
| prompt | object \| string | No | 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 | No | Placement position and maximum dimensions. |
| overrides | object | No | 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 | No | 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. |

## Response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| job_id | string | Yes | 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 | Yes | Slot identifier for diagnostics and advanced compatibility. |
| status | string | Yes | Decision state, usually pending or ready. |
| placement | object \| null | Yes | Hosted-render placement descriptor when a fill is ready. |
| placement.render | object | No | 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 | Yes | Canonical decision payload retained for compatibility and debugging. |
| decision.format | banner \| clip \| native | No | Filled creative format. Native fills return structured assets; clip fills return video media. |
| decision.assets | object \| null | No | Native-only assets: title, image_url, optional description, cta_text, and icon_url. Null for banner and clip. |
| decision.delivery_url | string \| null | No | Banner image or clip video URL. Null for native fills because native assets are returned as structured fields. |
| authoritative_consent | object | No | Decision-bound stored or request-level consent snapshot used by render.js. Rendering and beacons fail closed unless it is granted, current, and unexpired. |

## Errors

| Status | Code | Description |
| --- | --- | --- |
| 403 | consent_not_current | Required stored session consent is missing, stale, denied, revoked, or outside the authenticated scope. Inline flags cannot substitute for it. |
| 403 | consent_state_unavailable | Required consent storage could not be read. Keep advertising off and preserve the primary app flow. |
| 403 | privacy_signal_policy_required | A positive Sec-GPC signal was observed. Do not strip it or retry advertising without it. |
| 401 | unauthorized | Missing or inactive secret key or browser activation token. |
| 403 | forbidden | Wrong key type for the request. |
| 429 | rate_limited | Key exceeded its rate limit; retry after the Retry-After header. |
| 415 | unsupported_media_type | Non-empty request bodies must use Content-Type: application/json. |
| 400 | validation_error | The request body failed validation. TCF/GPP inputs, including structurally valid strings without an authoritative policy mapping, are currently rejected. |

## Response example

```json
{
  "job_id": "job_demo_123",
  "slot_id": "slot_demo_123",
  "status": "ready",
  "placement": {
    "image_url": "https://cdn.example.com/native-main.png",
    "video_url": null,
    "click_url": "https://sponsor.example",
    "sponsor_name": "Demo Sponsor",
    "width": 300,
    "height": 250,
    "format": "native",
    "asset_token": "wbat_asset_demo",
    "ad_label_text": "Sponsored",
    "render": {
      "strategy": "hosted_frame",
      "frame_url": "https://api.wavebird.ai/v1/render/wbat_asset_demo",
      "script_url": "https://api.wavebird.ai/v1/render.js",
      "media_type": "native",
      "width": 300,
      "height": 250,
      "aspect_ratio": "300/250",
      "label_text": "Sponsored",
      "sponsor_name": "Demo Sponsor",
      "click_url": "https://sponsor.example",
      "native_template_id": "card"
    }
  },
  "authoritative_consent": {
    "lifecycle_state": "granted",
    "revision": 1,
    "updated_at_ms": 1777032000000,
    "expires_at_ms": 1777032300000,
    "source": "wrapper_cmp",
    "purposes": { "semantic_targeting": true, "prompt_shared": false }
  },
  "decision": {
    "fill": true,
    "format": "native",
    "asset_token": "wbat_asset_demo",
    "delivery_url": null,
    "assets": {
      "title": "Explore weekend travel deals",
      "image_url": "https://cdn.example.com/native-main.png",
      "description": "Save on hand-picked city breaks.",
      "cta_text": "Book now",
      "icon_url": "https://cdn.example.com/native-icon.png"
    }
  }
}
```

## 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.

```json
[
  {
    "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.

## cURL

```bash
curl -X POST https://api.wavebird.ai/v1/placements?wait_ms=1500 \
  -H "Authorization: Bearer sk_test_wavebird_demo_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "wbproj_demo_8jK42",
    "session_id": "sess_demo_123",
    "job_type": "chat",
    "slots_requested": 1,
    "slot_hint": {
      "position": "below",
      "max_width": 728,
      "max_height": 90
    },
    "overrides": {
      "allowed_formats": ["banner", "clip", "native"],
      "timing": "during"
    },
    "consent": {
      "semantic_targeting": false,
      "prompt_shared": false,
      "gdpr_applies": false,
      "consent_source": "wavebird_consent"
    }
  }'
```

## Node

```javascript
const response = await fetch("https://api.wavebird.ai/v1/placements?wait_ms=1500", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_test_wavebird_demo_secret",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  client_id: "wbproj_demo_8jK42",
  session_id: "sess_demo_123",
  job_type: "chat",
  slots_requested: 1,
  slot_hint: {
    position: "below",
    max_width: 728,
    max_height: 90
  },
  overrides: {
    allowed_formats: ["banner", "clip", "native"],
    timing: "during"
  },
  consent: {
    semantic_targeting: false,
    prompt_shared: false,
    gdpr_applies: false,
    consent_source: "wavebird_consent"
  }
})
});

const data = await response.json();
console.log(data);
```

## Python

```python
import json
import urllib.request

payload = json.loads("{\"client_id\":\"wbproj_demo_8jK42\",\"session_id\":\"sess_demo_123\",\"job_type\":\"chat\",\"slots_requested\":1,\"consent\":{\"semantic_targeting\":false,\"prompt_shared\":false,\"gdpr_applies\":true,\"consent_source\":\"wavebird_consent\"}}")

request = urllib.request.Request(
    "https://api.wavebird.ai/v1/placements?wait_ms=1500",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": "Bearer sk_test_wavebird_demo_secret",
        "Content-Type": "application/json",
    },
    method="POST",
)

with urllib.request.urlopen(request) as response:
    print(response.read().decode("utf-8"))
```
