Bid - Thrad DSP API Documentation

{
  "userId": "user_123",
  "request_type": "contextual",
  "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"
    }
  ],
  "ad_formats": ["sponsored_message", "sponsored_carousel"],
  "prefetched": true,
  "request_id": "req_abc123",
  "country_code": "US",
  "region": "California",
  "city": "San Francisco",
  "device": "mobile",
  "timezone": "America/Los_Angeles",
  "config": {
    "max_headline_chars": 100,
    "image_enabled": true
  }
}

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

{
  "userId": "user_123",
  "request_type": "contextual",
  "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"
    }
  ],
  "ad_formats": ["sponsored_message", "sponsored_carousel"],
  "prefetched": true,
  "request_id": "req_abc123",
  "country_code": "US",
  "region": "California",
  "city": "San Francisco",
  "device": "mobile",
  "timezone": "America/Los_Angeles",
  "config": {
    "max_headline_chars": 100,
    "image_enabled": true
  }
}

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

Authorization

string

required

Bearer token for authentication. Format: Bearer your-api-key

Headers

Content-Type

string

required

Must be application/json

X-Forwarded-For

string

required

End-user’s IP address. First hop is the real user IP. Required on every bid request — use for geolocation, fraud detection, or frequency capping. The resolved country_code / region / city body fields are also provided as a convenience.

User-Agent

string

required

End-user’s device/browser string. Required on every bid request — use for device targeting, creative optimisation, or fraud detection.

Body

userId

string

required

Unique user identifier. Use anonymous UUIDs (e.g., user_a1b2c3d4-...). Do not use email or name.

request_type

string

required

Pipeline selector. One of:

"contextual" — in-chat ad. chatId and messages are required.
"opener" — pre-chat ad shown before the conversation starts. chatId and messages are not sent.

Defaults to "contextual" if omitted.

chatId

string

Conversation identifier. One unique ID per conversation, not per user. Reset when user starts a new chat.Required when request_type=contextual. Not sent for openers.

nAdsBefore

integer

Number of ads shown before this request in the current conversation. Added by SSP from cache. Contextual only.

messages

array

Conversation history. Must contain at least 2 messages, alternating between user and assistant roles, ending with a user message followed by an assistant message.Required when request_type=contextual. Not sent for openers (no conversation exists yet).

Show messages properties

role

string

required

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

content

string

required

Message text content.

timestamp

string

Optional ISO 8601 or Unix timestamp. Including timestamps enables time-in-chat analytics for better targeting.

ad_formats

string[]

Ad formats the publisher can render. Your DSP must pick one from this list when bidding and identify it in the bid response (ad_data.ad_format). If omitted, assume ["sponsored_message"].Allowed values per request_type:

contextual: "sponsored_message", "sponsored_carousel"
opener: "sponsored_message", "sponsored_carousel"

prefetched

boolean

true when the publisher is requesting an ad before the assistant reply is shown (pre-fetch). false when the ad is requested after the reply has already been displayed. Useful for tuning latency expectations and creative relevance.

request_id

string

Optional request identifier for distributed tracing when called from SSP. Used for correlation across services.

country_code

string

required

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

required

Device type. Possible values: "mobile", "desktop", "tablet".

timezone

string

required

User’s timezone in IANA format (e.g., "America/Los_Angeles").

config

object

Publisher creative constraints. Your DSP should respect these when generating the ad.

Show config properties

max_headline_chars

integer

default:"100"

Maximum headline length (in characters) the publisher can render. Minimum 30. Defaults to 100 if omitted.

image_enabled

boolean

default:"true"

Whether the publisher can render a hero/product image. When false, do not bid placement="image" — bid placement="text" with a logo_url instead (or no-bid).

Placement contract: every sponsored_message creative must declare a placement field — "image" (hero product photo) or "text" (advertiser logo + copy, no hero image). Each placement requires a matching URL: placement="image" needs image_url, placement="text" needs logo_url. Bids that omit placement or supply the wrong URL are rejected (dsp_missing_placement / dsp_invalid_image_bid / dsp_invalid_text_bid). See Ad Formats for the full contract.

{
  "userId": "user_123",
  "request_type": "contextual",
  "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"
    }
  ],
  "ad_formats": ["sponsored_message", "sponsored_carousel"],
  "prefetched": true,
  "request_id": "req_abc123",
  "country_code": "US",
  "region": "California",
  "city": "San Francisco",
  "device": "mobile",
  "timezone": "America/Los_Angeles",
  "config": {
    "max_headline_chars": 100,
    "image_enabled": true
  }
}

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

Response data payload. Must contain bid and bidId when submitting a bid. Return empty object {} for no-bid.

Show data properties

bid

float

required

Bid amount in CPM (cost per mille) dollars. Must be >= 0. Should have 2 decimal places. Values with more decimals will be rounded using banker’s rounding (IEEE 754).

bidId

string

required

Unique bid identifier required for render endpoint. Used to retrieve bid details during render phase.

ad_data

object

Optional - Pre-rendered ad creative. When included, the SSP skips the render step entirely and serves this ad directly.Important: If ad_data is present but invalid (missing required fields, wrong types, or unknown fields), the entire bid is rejected — treated as a no-bid with reason invalid_ad_data. Only include this if you’re confident in the format.The shape of ad_data is discriminated by the ad_format field. The format must be one your DSP was offered in ad_formats on the request. ad_format defaults to "sponsored_message" if omitted — only required when returning a non-default format like "sponsored_carousel".

Show ad_data properties (sponsored_message, placement=image)

Full card with a hero product image. Use when you have a real product photo. Publishers that set config.image_enabled=false cannot render this — bid placement="text" instead (or no-bid).

ad_format

string

default:"sponsored_message"

"sponsored_message". Optional — this is the default when omitted.

placement

string

required

Must be "image". Declares that this creative renders with a hero product image.

headline

string

required

Ad headline text. Must respect config.max_headline_chars from the request.

description

string

Ad description or body text. Optional.

url

string

required

Click-through/tracking URL.

advertiser

string

required

Brand display name (e.g. "Nike").

domain

string

Brand domain (e.g. "nike.com"). Optional.

cta_text

string

required

Call-to-action button text (e.g., “Learn More”, “Shop Now”).

image_url

string

required

Hero/product image URL — rendered as the main visual of the card. Required for placement="image".

logo_url

string

Advertiser brand mark. Optional, but recommended — publishers may render it as a small logo next to the product image.

view_url

string

Impression/view tracking pixel URL. If provided, the SSP appends it as a query parameter to the click URL for impression counting. Optional.

feedback_url

string

URL where Thrad should POST user feedback (thumbs up / thumbs down) for this ad. The URL is yours — embed the bid ID or any token you need to attribute the signal. Optional. See Feedback Passthrough.

Show ad_data properties (sponsored_message, placement=text)

Compact card with advertiser logo + copy, no hero image. Use when you don’t have a real product photo — brand awareness creatives, or catalogues that only have logo-style assets.

ad_format

string

default:"sponsored_message"

"sponsored_message". Optional — this is the default when omitted.

placement

string

required

Must be "text". Declares that this creative renders compactly with a logo rather than a hero image.

headline

string

required

Ad headline text. Must respect config.max_headline_chars from the request.

description

string

Ad description or body text. Optional.

url

string

required

Click-through/tracking URL.

advertiser

string

required

Brand display name (e.g. "Acme Sports").

domain

string

Brand domain (e.g. "acmesports.com"). Optional.

cta_text

string

required

Call-to-action button text (e.g., “Learn More”, “Shop Now”).

logo_url

string

required

Advertiser brand/logo URL — rendered as the card’s visual. Required for placement="text".

image_url

string

Ignored for placement="text". Send as null or omit.

view_url

string

Impression/view tracking pixel URL. If provided, the SSP appends it as a query parameter to the click URL for impression counting. Optional.

feedback_url

string

URL where Thrad should POST user feedback (thumbs up / thumbs down) for this ad. Optional. See Feedback Passthrough.

Show ad_data properties (carousel)

Beta. Carousel is in early release. Upcoming improvements: support for mixed-brand carousels (multiple advertisers per carousel) and per-tile viewability tracking (which tile was actually seen vs only rendered). Current constraints — same-brand only, single carousel-level view_url — will be relaxed in a future version.

ad_format

string

required

Must be "sponsored_carousel". Required for carousel responses (no default).

advertiser

string

Brand display name shared across all tiles. Optional but recommended — all tiles in a carousel must belong to the same brand.

domain

string

Brand domain shared across all tiles. Optional.

logo_url

string

Shared brand mark/logo URL covering the whole carousel. Optional.

items

array

required

Carousel tiles. Exactly 3 items required, all from the same brand. Order is preserved (index 0 is the lead tile). Cross-brand carousels are rejected.

Show item properties

headline

string

required

Tile headline. Must respect config.max_headline_chars from the request.

image_url

string

required

Tile image URL. Required for every tile — carousel without images is rejected.

url

string

required

Per-tile click-through URL. Must be unique per tile so click attribution can identify which tile was clicked.

description

string

Optional secondary text for the tile.

view_url

string

Single impression/view tracking pixel URL covering the whole carousel. Optional.

feedback_url

string

URL where Thrad should POST user feedback (thumbs up / thumbs down) for this carousel. Optional. See Feedback Passthrough.

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. Allowed optional fields include view_url and feedback_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 Code	Meaning	Scenario
`200 OK`	Success	Bid generated successfully or DSP chose not to bid
`400 Bad Request`	Invalid input	Malformed request body or missing required fields
`401 Unauthorized`	Authentication failed	Missing or invalid `Authorization` header
`429 Too Many Requests`	Rate limit exceeded	Publisher exceeded request quota
`500 Internal Server Error`	Server error	Exception during auction execution, database failure, or service unavailable

Onboarding Render Ad

​Authorization

​Headers

​Body

​Response

​Status Codes

Authorization

Headers

Body

Response

Status Codes