Render Ad - Thrad API Documentation

{
  "bidId": "bid_abc123",
  "realizedPrice": 7.50,
  "production": true
}

{
  "data": {
    "ad_format": "sponsored_message",
    "placement": "image",
    "advertiser": "Nike",
    "domain": "nike.com",
    "headline": "Check out the Nike Air Zoom Alphafly",
    "description": "The marathon record-holder's shoe.",
    "cta_text": "Shop Now",
    "url": "https://your-dsp.com/click/token_abc123",
    "image_url": "https://cdn.nike.com/alphafly.png",
    "logo_url": "https://cdn.nike.com/logo.png",
    "view_url": "https://your-dsp.com/view/token_abc123",
    "feedback_url": "https://your-dsp.com/feedback?bid=bid_abc123"
  }
}

POST

api

dsp

render-ad

{
  "bidId": "bid_abc123",
  "realizedPrice": 7.50,
  "production": true
}

{
  "data": {
    "ad_format": "sponsored_message",
    "placement": "image",
    "advertiser": "Nike",
    "domain": "nike.com",
    "headline": "Check out the Nike Air Zoom Alphafly",
    "description": "The marathon record-holder's shoe.",
    "cta_text": "Shop Now",
    "url": "https://your-dsp.com/click/token_abc123",
    "image_url": "https://cdn.nike.com/alphafly.png",
    "logo_url": "https://cdn.nike.com/logo.png",
    "view_url": "https://your-dsp.com/view/token_abc123",
    "feedback_url": "https://your-dsp.com/feedback?bid=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

Content-Type

string

required

Must be application/json

This endpoint does not require API key authentication when called by SSP. Authentication is handled at the SSP level.

Body

bidId

string

required

The bid identifier from the winning bid response. Must match a valid bid in cache (TTL: ~60 seconds).

realizedPrice

float

required

The actual clearing price from the auction (what the winner pays). In first-price auctions, this matches the winning bid amount.

production

boolean

default:"true"

Whether the request is for production. Defaults to true.

{
  "bidId": "bid_abc123",
  "realizedPrice": 7.50,
  "production": true
}

{
  "data": {
    "ad_format": "sponsored_message",
    "placement": "image",
    "advertiser": "Nike",
    "domain": "nike.com",
    "headline": "Check out the Nike Air Zoom Alphafly",
    "description": "The marathon record-holder's shoe.",
    "cta_text": "Shop Now",
    "url": "https://your-dsp.com/click/token_abc123",
    "image_url": "https://cdn.nike.com/alphafly.png",
    "logo_url": "https://cdn.nike.com/logo.png",
    "view_url": "https://your-dsp.com/view/token_abc123",
    "feedback_url": "https://your-dsp.com/feedback?bid=bid_abc123"
  }
}

Response

data

object

required

Ad creative response payload. Shape is discriminated by ad_format. ad_format defaults to "sponsored_message" if omitted — only required when returning a non-default format like "sponsored_carousel".

Show data properties (sponsored_message, placement=image)

Full card with a hero product image. Use when you have a real product photo. Requires the original bid request’s config.image_enabled=true — otherwise respond with placement="text".

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 the config.max_headline_chars value sent on the bid request.

description

string

Ad body text/description. Optional.

url

string

required

Click-through URL. This is your own click tracking URL (your domain, your format). The SSP passes it through to the publisher as-is.

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 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 tracking URL. If provided, the SSP appends it as a query parameter to the click URL; the publisher fires it on render. Optional.

feedback_url

string

URL where Thrad should forward user feedback (thumbs up / thumbs down) for this ad. Optional — overrides any feedback_url you returned in the bid response. See Feedback Passthrough.

Show 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. Always valid regardless of config.image_enabled.

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 the config.max_headline_chars value sent on the bid request.

description

string

Ad body text/description. Optional.

url

string

required

Click-through URL. This is your own click tracking URL (your domain, your format). The SSP passes it through to the publisher as-is.

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 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 tracking URL. If provided, the SSP appends it as a query parameter to the click URL; the publisher fires it on render. Optional.

feedback_url

string

URL where Thrad should forward user feedback (thumbs up / thumbs down) for this ad. Optional — overrides any feedback_url you returned in the bid response. See Feedback Passthrough.

Show 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 original bid 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 forward user feedback for this carousel. Optional — overrides any feedback_url from the bid response. See Feedback Passthrough.

error

string

Error message when the request fails. Only present on error responses.

No extra fields allowed: The response model uses strict validation (extra="forbid"). If your response includes any field not listed above, validation will fail and the ad will be dropped. For example, adding "custom_tracking": "something" to the data object will cause the entire render response to be rejected.

Click URL requirement: We append a view_url parameter to the click URL for impression verification. Your click tracker must pass through or ignore unknown query parameters.

Status Codes

Status Code	Meaning	Scenario
`200 OK`	Success	Ad creative generated successfully
`400 Bad Request`	Validation error	Missing required fields (`description` or `url`) or invalid data types
`404 Not Found`	Bid not found	Bid expired (TTL ~60s), invalid bidId, or bid not in cache
`500 Internal Server Error`	Server error	LLM service unavailable, creative generation failed, or database error

Bid Feedback Webhook

​Authorizations

​Body

​Response

​Status Codes

Authorizations

Body

Response

Status Codes