Skip to main content

​
Requesting an Ad Format

Use the ad_formats field in your bid request to specify which formats your integration can render. The server picks the best match and the response includes an ad_format field confirming what was returned. When ad_formats is omitted, it defaults to ["sponsored_message"] for contextual requests and ["sponsored_prompt"] for opener requests.

​
Available Formats

Formatad_formats valueStatus
Sponsored Messagesponsored_messageLive
Sponsored Promptsponsored_promptLive
CarouselcarouselComing soon
Sponsored Pollsponsored_pollComing soon
Use the ad_format field in the response to determine which format was returned and render accordingly. A native ad card displayed inline in the conversation. Includes a headline, description, optional image, and a call-to-action.
Sponsored message example
Response fields: ad_format, advertiser, domain, headline, description, cta_text, url, image_url 
{
  "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"
}
FieldDescription
ad_formatAlways "sponsored_message" for this format.
priceClearing price (CPM) in dollars — what the publisher earns.
advertiserBrand name of the advertiser (e.g. "Nike"). In rare cases this may return a domain (e.g. "nike.com") as a fallback when the brand name is not available. Your UI should handle both gracefully.
domainAdvertiser website domain (e.g. "nike.com").
headlineAd headline. Respects config.max_headline_chars when set.
descriptionAd body text. May be null.
cta_textCall-to-action text. May be absent — default to “Learn More” in your UI.
urlClick tracking URL. Always use this for clicks — it tracks the click and redirects to the landing page.
image_urlAd image URL. Only present when config.image_enabled is true (default) and a product image is available. Render without an image if absent.
dspWinning DSP identifier.
bidIdBid identifier for tracking and debugging.
A set of sponsored follow-up questions displayed as clickable prompts before or during a conversation.
Sponsored prompt example
Response fields: ad_format, advertiser, sponsored_prompt, url, logo_url The response returns an array of bids, each containing a sponsored prompt: 
{
  "bids": [
    {
      "ad_format": "sponsored_prompt",
      "bidId": "bid_sp_001",
      "advertiser": "Nike",
      "sponsored_prompt": "What are the best running shoes for marathon training?",
      "url": "https://ssp.thrads.ai/api/v1/tracking/redirect?token=sp1",
      "logo_url": "https://cdn.example.com/nike-logo.png",
      "view_url": "https://ssp.thrads.ai/api/v1/tracking/view?token=v1"
    }
  ]
}
Coming soon — contact us at contact@thrad.ai for early access.
A scrollable set of ad cards, each with its own headline, image, and link. Useful for showcasing multiple products in a single slot.
Sponsored carousel example
Coming soon — contact us at contact@thrad.ai for early access.
An interactive poll sponsored by an advertiser. Engages users with a question and multiple-choice answers, with optional click-through on results.
Sponsored poll example

​
Response Handling

​
No Bid Response

{
  "requestId": "api_req_124",
  "timestamp": "2025-11-24T21:51:52.240297Z",
  "totalTime": 0.095,
  "status": "success",
  "message": "No bids",
  "data": {
    "bid": null
  },
  "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 and should be handled gracefully in your UI.