Create job
POST
/v1/jobsADVANCEDUse 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.
AUTH
Secret key, or activation token for browser flows
CONTENT TYPE
application/json
STATUS
Advanced
Request parameters
- client_id
- string
- Required
- Project ID (client_id, WAVEBIRD_CLIENT_ID), formatted like wbproj_....
- session_id
- string
- Optional
- Optional stable publisher session identifier.
- job_type
- string
- Optional
- Optional workload category: chat, code, image, voice, agent. Missing values normalize to chat.
- slots_requested
- integer
- Optional
- Number of ad slots to request. Defaults to one.
- 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.
- consent
- object
- Optional
- Request-level consent flags: semantic_targeting, prompt_shared, gdpr_applies, and consent_source.
| Name | Type | Required | Description |
|---|---|---|---|
| client_id | string | Required | Project ID (client_id, WAVEBIRD_CLIENT_ID), formatted like wbproj_.... |
| session_id | string | Optional | Optional stable publisher session identifier. |
| job_type | string | Optional | Optional workload category: chat, code, image, voice, agent. Missing values normalize to chat. |
| slots_requested | integer | Optional | Number of ad slots to request. Defaults to one. |
| 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. |
| consent | object | Optional | Request-level consent flags: semantic_targeting, prompt_shared, gdpr_applies, and consent_source. |
Returns
- job_id
- string
- Created job identifier.
- slot_ids
- string[]
- Slots to render or poll for decisions.
- poll_path_template
- string
- Canonical decision polling path.
- request_id
- string
- Support identifier.
| Name | Type | Description |
|---|---|---|
| job_id | string | Created job identifier. |
| slot_ids | string[] | Slots to render or poll for decisions. |
| poll_path_template | string | Canonical decision polling path. |
| request_id | string | Support identifier. |
Errors
CODESTATUSWHEN IT HAPPENS
unauthorized401Missing key or 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.