Create job

POST/v1/jobsADVANCED

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.

AUTH

Secret key, or activation token for browser flows

CONTENT TYPE

application/json

STATUS

Advanced
Secret key or browser activation tokenVerification stepsOpen as Markdown ↗

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

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.

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 key or 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