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.

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.

ad_formats

array

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

Contextual: ["sponsored_message"] (default). More formats coming soon — see Ad Formats & Rendering.
Opener: ["sponsored_message"], ["sponsored_prompt"], or both. Defaults to ["sponsored_prompt"] when omitted.

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", ads are automatically blocked for that user to comply with age-gating requirements.

{
  "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,
  "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",
      "image_url": "https://cdn.example.com/nike-shoes.jpg",
      "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"). 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

Click tracking URL. Use this for ad clicks — it tracks the click and redirects to the advertiser’s landing page.

image_url

string

Ad image URL. Only present when config.image_enabled is true and an image is available.

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

​Authorizations

​End-User Headers

​Geolocation & Device Headers

​Body

​Response

​Status Codes

Authorizations

End-User Headers

Geolocation & Device Headers

Body

Response

Status Codes