# Create job

Advanced compatibility route that creates a sponsorship job and returns one or more slot IDs.

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.

| Method | Path | Authentication | Stability |
| --- | --- | --- | --- |
| POST | /v1/jobs | Secret key, or activation token for browser flows | advanced |

## Request fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| client_id | string | Yes | Project ID (client_id, WAVEBIRD_CLIENT_ID), formatted like wbproj_.... |
| session_id | string | No | Optional stable publisher session identifier. |
| job_type | string: chat, code, image, voice, agent | No | Optional workload category: chat, code, image, voice, agent. Missing values normalize to chat. |
| slots_requested | integer | No | Number of ad slots to request. Defaults to one. |
| 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. |
| consent | object | No | Request-level privacy flags. Projects using wavebird_consent still require a current stored record for the authenticated project and session; inline flags cannot substitute for it. |

## Response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| job_id | string | Yes | Created job identifier. |
| slot_ids | string[] | Yes | Slots to render or poll for decisions. |
| poll_path_template | string | Yes | Canonical decision polling path. |
| request_id | string | Yes | Support identifier. |

## 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 key or 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_ids": ["slot_demo_123"],
  "poll_path_template": "/v1/decisions/{slot_id}",
  "request_id": "req_JVd28x"
}
```

## cURL

```bash
curl -X POST https://api.wavebird.ai/v1/jobs \
  -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,
    "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/jobs", {
  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,
  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}")

request = urllib.request.Request(
    "https://api.wavebird.ai/v1/jobs",
    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"))
```
