Bid Request

Authorizations

thrad-api-key

string

required

Your API key for authentication. The key’s environment (staging or production) determines how ads are served — see Staging vs. Production.

Content-Type

string

required

Must be application/json

End-User Headers

These headers identify the real end-user behind the request. They are required on every bid request and every view URL ping.

X-Forwarded-For

string

required

The end-user’s original IP address. Must be the real client IP, not your server’s IP.

User-Agent

string

required

The end-user’s original device/browser string exactly as received from the client.

Geolocation & Device Headers

The server resolves the user’s location and device from request headers. These are optional but strongly recommended for server-side integrations — sending them skips the server-side IP lookup and reduces latency.

X-User-Country

string

ISO 3166-1 alpha-2 country code (e.g. "US", "DE"). When present, X-User-Device and X-User-Timezone are required.

X-User-Device

string

User’s device type: "mobile" or "desktop". Required when X-User-Country is present. This is critical for device-targeted campaigns — without it, targeting will not work correctly.

X-User-Timezone

string

IANA timezone (e.g. "America/Los_Angeles"). Required when X-User-Country is present. Used for time-of-day pacing.

X-User-Region

string

Region or state (e.g. "CA", "Bavaria"). Optional but recommended for regional targeting.

X-User-City

string

City name (e.g. "San Francisco"). Optional but recommended for city-level targeting.

If you send X-User-Country without X-User-Device and X-User-Timezone, the request will be rejected with a 400 Bad Request. These three headers must always be sent together.

If none of the above headers are sent, the server falls back to IP-based geolocation using X-Forwarded-For. For direct calls (browser or mobile app → our API), this is handled automatically by the load balancer. If you’re proxying requests through your own backend, you must forward the user’s IP via X-Forwarded-For — otherwise the server sees your server’s IP and geo will be wrong.

If unsure about which headers to send, contact marco@thrads.ai and we’ll help you set it up.

Body

userId

string

required

Unique, anonymous user identifier (e.g. a UUID like user_a1b2c3d4-...). Must be stable across sessions for the same user. Do not use email, name, or other PII. On web, store in localStorage; on mobile, use the platform’s persistent storage (e.g. UserDefaults on iOS, SharedPreferences on Android).

chatId

string

contextual only Conversation identifier. One unique ID per conversation, not per user. Reset when user starts a new chat. Required when request_type is "contextual".

messages

array

contextual only Conversation history. Required when request_type is "contextual". Each message must have a role ("user" or "assistant") and content. PII (names, emails, addresses, etc.) should be masked or removed before sending.

Show messages properties

role

string

required

Message role. Must be either "user" or "assistant".

content

string

required

Message text content.

timestamp

string

required

ISO 8601 (e.g. "2025-11-23T10:00:00Z") or Unix timestamp (e.g. 1700730000). Used for conversation continuity tracking — without timestamps, the server cannot merge partial message histories and conversation analytics will be degraded.

config

object

Publisher configuration for pacing, creative constraints, and analytics. All fields are optional — omitted fields fall back to defaults set on your chatbot in the platform dashboard.

Show config properties

ad_offset

integer

contextual only Minimum turns before the first ad in a conversation. null uses your dashboard setting. 0 disables the offset check.

max_frequency

integer

contextual only Minimum number of requests between consecutive ads. For example, 3 means an ad can appear at most once every 3 requests. null uses your dashboard setting. 0 disables the frequency check.

max_headline_chars

integer

Maximum character length for ad headlines. Minimum value is 30. When set, the system guarantees no headline exceeds this limit — creatives that don’t fit are filtered or replaced.

image_enabled

boolean

default:"true"

Whether the publisher can render ad images. When false, product images are omitted and the ad is returned with a logo or no image. Defaults to true.

restricted_click_area

boolean

default:"false"

Set to true if your UI only makes specific elements clickable — logo, advertiser name, CTA button — rather than the entire ad surface. Analytics-only signal: it does not change the response payload. Lets us segment click-through performance by click-zone style. Defaults to false (full ad surface clickable).

experiment_tag

string

A/B test label for analytics segmentation (max 30 characters). See Experiments below.

request_type

string

default:"contextual"

Pipeline selector. Determines which ad pipeline runs and what fields are required.

"contextual" (default) — in-chat ads. Requires chatId and messages.
"opener" — pre-chat ads (e.g. sponsored prompts, banners). chatId and messages are not required. Sponsored polls are not opener inventory.

ad_formats

array

Ad formats the publisher can render. The server picks the best match from this list.

Contextual: ["sponsored_message"] (default), ["sponsored_poll"], or ["sponsored_message", "sponsored_poll"].
Opener: ["sponsored_message"], ["sponsored_prompt"], or both. Defaults to ["sponsored_prompt"] when omitted. Do not include sponsored_poll on opener requests.

When contextual requests include both sponsored_message and sponsored_poll, Thrad selects the campaign through the normal contextual auction, then uses campaign delivery settings to choose whether the returned creative is a message or poll.

turn_number

integer

contextual only Current turn number in the conversation. Used for ad offset pacing and analytics. Must be >= 0. Only needed if you’re not calling the endpoint on every user-assistant exchange — if you are, the system derives this from the message count.

turns_from_last_ad

integer

contextual only Number of requests since the last ad was shown in this conversation. Used by the max frequency check. Optional — the system tracks this automatically. Only send this if you want to override the server-side counter.

summary

string

contextual only Publisher-provided conversation summary. Useful when you already have a summary from your chatbot and want to reduce latency.

force

boolean

default:"false"

contextual only When true, the system serves an ad as a last resort even if the conversation context doesn’t strongly match any campaign. The normal pipeline (contextual scoring → retargeting → exploration) runs first; force only kicks in when everything else returns no bid. Hard filters (banned content, geo targeting, budget caps) still apply — force never overrides safety or budget constraints.We recommend starting without force (the default) and only enabling it if your fill rate is too low. See Maximising Fill Rate for guidance.

user_metadata

object

User metadata for targeting and compliance. All fields are optional. Extra fields are accepted and stored for future use.

Show user_metadata properties

age_range

string

IAB standard age range. Accepted values: "0-12", "13-17", "18-24", "25-34", "35-44", "45-54", "55-64", "65+". When the value is "0-12" or "13-17", the request is treated as underage: the auction is skipped and the response is 200 OK with "bid": null. Send this whenever your platform knows the user’s age — it’s the only way to comply with age-gating on Thrad’s side.

IAB TCF v2 consent string generated by your CMP (e.g. OneTrust, Quantcast) when the user interacts with your cookie banner. Required for EU/UK users if you want oRTB DSPs to bid on that traffic — without it, EU-based DSPs will scrub or skip the request. Pass the raw base64-encoded string exactly as produced by your CMP. Non-EU publishers can omit this field.

us_privacy

string

IAB CCPA US Privacy string (e.g. "1YNN", "1---"). Generated by your CMP for California/US users. Forwarded to oRTB DSPs as regs.us_privacy. Non-US publishers can omit this field.

{
  "userId": "user_123",
  "chatId": "chat_456",
  "messages": [
    {
      "role": "user",
      "content": "Looking for running shoes",
      "timestamp": "2025-11-23T10:00:00Z"
    },
    {
      "role": "assistant",
      "content": "What's your budget?",
      "timestamp": "2025-11-23T10:00:15Z"
    }
  ],
  "summary": "User is looking for running shoes for marathon training",
  "config": {
    "ad_offset": 3,
    "max_frequency": 5,
    "max_headline_chars": 60,
    "experiment_tag": "variant_a"
  },
  "user_metadata": {
    "age_range": "25-34"
  },
  "turn_number": 4,
  "ad_formats": ["sponsored_message"],
  "force": false
}

{
  "requestId": "api_req_123",
  "timestamp": "2025-11-24T21:51:52.240297Z",
  "totalTime": 0.123,
  "status": "success",
  "message": "Bid successful",
  "data": {
    "bid": {
      "ad_format": "sponsored_message",
      "price": 5.50,
      "advertiser": "Nike",
      "domain": "nike.com",
      "headline": "Premium Running Shoes",
      "description": "Perfect for marathon training. Lightweight and comfortable.",
      "cta_text": "Shop Now",
      "url": "https://ssp.thrads.ai/api/v1/tracking/redirect?token=abc123",
      "placement": "image",
      "logo_url": "https://cdn.example.com/nike-logo.png",
      "image_url": "https://cdn.example.com/nike-shoes.jpg",
      "view_url": "https://ssp.thrads.ai/api/v1/tracking/view?token=v1",
      "dsp": "thrad_dsp",
      "bidId": "bid_abc123"
    }
  },
  "error": null
}

A 200 OK response with "bid": null is not an error - it means the auction ran successfully but no DSP submitted a winning bid. This is normal behavior.

Response

requestId

string

Unique request identifier used in logs and tracing.

timestamp

string

ISO 8601 timestamp of when the response was generated.

totalTime

float

Total processing time for this request in seconds.

status

string

Response status: "success" or "error".

message

string

Human-readable message describing the result.

data

object

Response data payload.

Show data properties

bid

object|null

Winning bid object (null if no bids). Contains ad creative information when available.

Show bid properties

price

float

Clearing price (CPM) in dollars — what the publisher earns.

ad_format

string

The ad format returned (e.g. "sponsored_message", "sponsored_prompt", "sponsored_poll"). Matches one of the values from the request’s ad_formats array.

advertiser

string

Advertiser brand name. Falls back to the advertiser’s website domain if no brand name is available.

domain

string

Advertiser website domain (e.g. "nike.com"). Always present when a bid is returned.

dsp

string

Winning DSP identifier (e.g., "thrad_dsp").

bidId

string

Bid identifier for tracking and debugging.

headline

string

Ad headline text. Respects config.max_headline_chars when set.

description

string

Ad body text. May be null in some cases.

cta_text

string

Call-to-action text, e.g., “Shop Now”, “Learn More”. Defaults to “Learn More” on the publisher side if absent.

url

string

Sponsored message and prompt click tracking URL. Use this for ad clicks — it tracks the click and redirects to the advertiser’s landing page. Poll option clicks use vote_url, not url.

placement

string

sponsored_message only. Render mode: "text" (compact, logo only) or "image" (full product photo). When missing, treat as "text". See Ad Formats & Rendering for the full creative-field rules per mode.

logo_url

string

Advertiser brand/logo URL. Required when placement="text". May also be present alongside image_url when placement="image".

image_url

string

Product/hero photo URL. Present when placement="image", absent when placement="text". Setting config.image_enabled=false forces text mode, so image_url will never be returned.

view_url

string

Optional impression tracking pixel URL. Fire it when the ad becomes visible to the user. See Billing & Viewability.

sponsored_poll_id

integer

sponsored_poll only. Poll identifier.

question

string

sponsored_poll only. Poll question text.

options

array

sponsored_poll only. Poll answer options. Render each option as a button or equivalent selectable control.

Show options properties

string

Option identifier to submit when voting.

text

string

Option label to display.

vote_url

string

sponsored_poll only. Signed vote URL. Submit the selected option to this URL instead of using normal click tracking. See Sponsored Poll Tracking.

results_url

string

sponsored_poll only. Signed results URL. Fetch this URL to refresh aggregate results without recording a vote. See Sponsored Poll Tracking.

cta_url

string

sponsored_poll only. Optional signed click tracking URL for the advertiser CTA shown after voting. Voting does not redirect automatically.

results

object

sponsored_poll only. Optional aggregate results returned with the creative.

Show results properties

total_votes

integer

Total votes counted for the poll.

options

array

Result rows for each poll option, including id, text, votes, and percentage.

error

object|null

Error details when status = "error" (otherwise null).

Status Codes

Status Code	Meaning	Scenario
`200 OK`	Success	Auction ran successfully (with or without winning bid), or pacing blocked
`400 Bad Request`	Invalid input	Malformed request body or missing required fields
`401 Unauthorized`	Authentication failed	Missing or invalid `thrad-api-key`
`403 Forbidden`	Origin not allowed	Request from non-whitelisted domain (browser integration only)
`429 Too Many Requests`	Rate limit exceeded	Publisher exceeded request quota
`500 Internal Server Error`	Server error	DSP render failed, validation error, or internal exception

Get Started

SDK

API

Authorizations

End-User Headers

Geolocation & Device Headers

Body

Response

Status Codes

Get Started

SDK

API

Documentation Index

​Authorizations

​End-User Headers

​Geolocation & Device Headers

​Body

​Response

​Status Codes

Authorizations

End-User Headers

Geolocation & Device Headers

Body

Response

Status Codes