Skip to main content
{
  "userId": "user_123",
  "chatId": "chat_456",
  "nAdsBefore": 2,
  "messages": [
    {
      "role": "user",
      "content": "Looking for running shoes",
      "timestamp": "2024-11-23T10:00:00Z"
    },
    {
      "role": "assistant",
      "content": "What's your budget?",
      "timestamp": "2024-11-23T10:00:15Z"
    }
  ],
  "production": true,
  "request_id": "req_abc123",
  "country_code": "US",
  "region": "California",
  "city": "San Francisco",
  "device": "mobile",
  "timezone": "America/Los_Angeles"
}

{
  "data": {
    "bid": 7.50,
    "bidId": "bid_abc123"
  }
}
Implementation Required: Your DSP must implement this endpoint on your own server. The SSP at ssp.thrads.ai will send POST requests to your configured DSP endpoint URL.

​
Authorizations

​
Authorization
string
required
Bearer token for authentication. Format: Bearer your-api-key
​
Content-Type
string
required
Must be application/json
​
X-Forwarded-For
string
Client IP address for geolocation (optional but recommended)
​
CF-Connecting-IP
string
Cloudflare client IP address for geolocation (optional, sent when available)
​
True-Client-IP
string
Backup client IP header (optional)

​
Body

​
userId
string
required
Unique user identifier. Use anonymous UUIDs (e.g., user_a1b2c3d4-...). Do not use email or name.
​
chatId
string
required
Conversation identifier. One unique ID per conversation, not per user. Reset when user starts a new chat.
​
nAdsBefore
integer
Number of ads shown before this request in the current conversation. Added by SSP from cache. Optional.
​
messages
array
required
Conversation history. Must contain at least 2 messages (user and assistant). Messages must alternate between user and assistant roles, ending with a user message followed by an assistant message.
​
production
boolean
default:"true"
Whether the request is for production. Defaults to true.
​
request_id
string
Optional request identifier for distributed tracing when called from SSP. Used for correlation across services.
​
country_code
string
ISO 3166-1 alpha-2 country code (e.g., "US", "GB"). Derived from IP geolocation.
​
region
string
State or region name (e.g., "California"). Derived from IP geolocation.
​
city
string
City name (e.g., "San Francisco"). Derived from IP geolocation.
​
device
string
Device type. Possible values: "mobile", "desktop", "tablet".
​
timezone
string
User’s timezone in IANA format (e.g., "America/Los_Angeles").
{
  "userId": "user_123",
  "chatId": "chat_456",
  "nAdsBefore": 2,
  "messages": [
    {
      "role": "user",
      "content": "Looking for running shoes",
      "timestamp": "2024-11-23T10:00:00Z"
    },
    {
      "role": "assistant",
      "content": "What's your budget?",
      "timestamp": "2024-11-23T10:00:15Z"
    }
  ],
  "production": true,
  "request_id": "req_abc123",
  "country_code": "US",
  "region": "California",
  "city": "San Francisco",
  "device": "mobile",
  "timezone": "America/Los_Angeles"
}

{
  "data": {
    "bid": 7.50,
    "bidId": "bid_abc123"
  }
}

​
Response

Additional fields (such as requestId, timestamp, status, message, etc.) are allowed in the response and will be ignored by the SSP.
​
data
object
required
REQUIRED - Response data payload. Must contain bid and bidId when submitting a bid. Return empty object {} for no-bid.
​
error
string
Error message when the request fails. Only present on error responses.
Pre-rendered ad_data validation is strict. The SSP validates ad_data against the exact render response schema (extra="forbid"). Unknown fields will cause the bid to be rejected. Required fields: headline, description, url. If you include ad_data, the render endpoint (/render-ad) is never called for that bid — make sure the ad creative is complete.

​
Status Codes

Status CodeMeaningScenario
200 OKSuccessBid generated successfully or DSP chose not to bid
400 Bad RequestInvalid inputMalformed request body or missing required fields
401 UnauthorizedAuthentication failedMissing or invalid Authorization header
429 Too Many RequestsRate limit exceededPublisher exceeded request quota
500 Internal Server ErrorServer errorException during auction execution, database failure, or service unavailable