Skip to main content
POST
https://ssp.thrads.ai
/
api
/
v1
/
dsp
/
bid
{
  "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"
}

{
  "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

​
thrad-api-key
string
required
Your API key for authentication
​
Content-Type
string
required
Must be application/json
​
X-Forwarded-For
string
Client IP address for geolocation (optional but recommended)
​
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.
{
  "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"
}

{
  "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.

​
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 thrad-api-key
429 Too Many RequestsRate limit exceededPublisher exceeded request quota
500 Internal Server ErrorServer errorException during auction execution, database failure, or service unavailable