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

Geolocation Headers

The server resolves the user’s location from request headers. These are optional but strongly recommended — 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-Region, X-User-City, and X-User-Timezone are also read.

X-User-Region

string

Region or state (e.g. "CA", "Bavaria").

X-User-City

string

City name (e.g. "San Francisco").

X-User-Timezone

string

IANA timezone (e.g. "America/Los_Angeles").

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

ISO 8601 or Unix timestamp. Enables time-in-chat analytics for better targeting.

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 turns between consecutive ads. 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 turns since the last ad was shown in this conversation. Used by the max frequency check. Only needed if you’re not calling the endpoint on every user-assistant exchange — if you are, the system tracks this automatically.

force

boolean

default:"false"

When true, the system serves an ad as a last resort even if the conversation context doesn’t strongly match any campaign. 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.

{
  "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"
    }
  ],
  "config": {
    "ad_offset": 3,
    "max_frequency": 5,
    "max_headline_chars": 60,
    "experiment_tag": "variant_a"
  },
  "turn_number": 4,
  "turns_from_last_ad": 6,
  "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

Experiments

Beta — available to all publishers.

Use config.experiment_tag to run A/B tests on your integration. Tag each request with a label (max 30 characters) and the tag is recorded on every impression. You can then compare performance metrics (impressions, clicks, CTR, revenue) across experiment variants in your dashboard. Example: test whether showing ads after turn 3 vs turn 5 performs better.

// Variant A: ads after turn 3
{
  "config": {
    "ad_offset": 3,
    "experiment_tag": "offset_3"
  }
}

// Variant B: ads after turn 5
{
  "config": {
    "ad_offset": 5,
    "experiment_tag": "offset_5"
  }
}

Split your traffic between the two variants and compare offset_3 vs offset_5 in your dashboard analytics. You can use experiment tags to test any parameter — ad offset, max frequency, headline length, image vs no-image, or anything else in your integration logic.

Get Started

Guides

API Reference

Authorizations

Geolocation Headers

Body

Response

Status Codes

Experiments

Get Started

Guides

API Reference

​Authorizations

​Geolocation Headers

​Body

​Response

​Status Codes

​Experiments

Authorizations

Geolocation Headers

Body

Response

Status Codes

Experiments