---
name: Thrad
description: Use when integrating a Demand-Side Platform (DSP) with Thrad's
  conversational ad network, implementing OpenRTB 2.6 bidding, handling
  real-time auctions for chat-based ad placements, managing bid responses with
  native creative assets, tracking impressions and spend, and validating traffic
  quality.
metadata:
  mintlify-proj: thrad
  version: "1.0"
---

# Thrad DSP Skill

## Product Summary

Thrad DSP is an OpenRTB 2.6 integration that allows your Demand-Side Platform to bid on conversational ad placements within Thrad's publisher network. Your DSP receives real-time bid requests from active chat conversations, submits bids with native creative assets (sponsored messages), and receives win/loss/billing notifications. The platform operates on a first-price auction model with a 10% SSP commission. Key integration points: HTTPS bid endpoint, Bearer token authentication, Native 1.2 asset format, and reporting API for daily impressions and spend reconciliation. Primary documentation: https://docs.thrad.ai/dsp/introduction

## When to Use

Reach for this skill when:
- Integrating your DSP's bidding engine with Thrad's conversational ad network
- Implementing OpenRTB 2.6 bid request parsing and response generation
- Building native creative asset handling for sponsored message placements
- Setting up win/loss/billing notification handlers (nurl/lurl/burl)
- Configuring IVT (invalid traffic) detection and verification pixel firing
- Pulling daily delivery and spend reports for reconciliation
- Debugging bid rejections, creative rendering issues, or impression discrepancies
- Handling multi-bid responses and in-response loss notifications
- Implementing bid rounding, floor price logic, and timeout handling

## Quick Reference

### Bid Request/Response Essentials

| Element | Details |
|---------|---------|
| **Endpoint** | Your HTTPS URL, configured at onboarding |
| **Auth** | Bearer token (header) or pubid-in-URL pattern |
| **Timeout** | 3s in-conversation, 1s opener requests; read `tmax` per request |
| **Auction type** | First-price (`at: 1`), always USD |
| **Impression count** | Always 1 per request (`imp[].id = "1"`) |

### Native Asset Requirements (0-based IDs)

| Asset ID | Type | Image Mode | Text Mode | Required |
|----------|------|-----------|-----------|----------|
| 0 | Title | ✓ | ✓ | Yes |
| 1 | Description | ✓ | ✓ | Yes |
| 2 | Sponsor | ✓ | ✓ | Yes |
| 3 | Main image | Optional | Omitted | No |
| 4 | Logo/icon | Optional | Yes | Conditional |
| 5 | CTA text | ✓ | ✓ | Yes |

### Placement Modes (tagid)

| tagid | Slot | Mode | Asset 3 | Asset 4 |
|-------|------|------|---------|---------|
| `card_image` | In-conversation | Image preferred | Optional | Optional |
| `card_text` | In-conversation | Text only | Dropped | Required |
| `opener_image` | Pre-chat | Image preferred | Optional | Optional |
| `opener_text` | Pre-chat | Text only | Dropped | Required |

### Notification URLs

| URL | When | Use for | Macro |
|-----|------|---------|-------|
| `nurl` | Win, before render | Pacing, bid bookkeeping | `${AUCTION_PRICE}` |
| `lurl` | Loss | Price learning, tuning | `${AUCTION_LOSS}` |
| `burl` | Viewable impression | Spend recognition, billing | `${AUCTION_PRICE}` |

### Loss Reason Codes

| Code | Meaning |
|------|---------|
| 102 | Lost to higher bid (cross-DSP or in-response) |
| 100 | Bid below floor |
| 3 | Invalid response (unparseable price, missing id, bad markup) |
| 205 | Advertiser blocked (adomain in badv) |
| 209 | Category blocked (cat in bcat) |
| 215 | App blocked |

### Reporting API

```bash
GET https://api.thrad.ai/v1/dsp/report
Authorization: Bearer dk_...
?start=2026-09-01T00:00:00Z&end=2026-09-02T00:00:00Z
```

Returns: `sent_impressions`, `billable_impressions`, `spend` (string, parse as decimal)

## Decision Guidance

### When to Use Image vs Text Mode

| Condition | Action |
|-----------|--------|
| Publisher tagid ends in `_image` | Send asset 3 (hero image) if available; always include asset 4 (logo) as fallback |
| Publisher tagid ends in `_text` | Omit asset 3 entirely; asset 4 (logo) is required; asset 3 will be dropped server-side if sent |
| You have a product photo | Populate asset 3 (main image) — image mode preferred |
| You only have a logo | Populate asset 4 (logo) — text mode will render |
| You have neither | Bid will be rejected — do not submit |

### When to Use Multi-bid vs Single-bid Response

| Scenario | Approach |
|----------|----------|
| One buyer, one creative per opportunity | Single bid in one seatbid |
| Multiple buyers (agencies, trading desks) | Multiple seatbids, one per buyer; populate `seatbid[].seat` |
| Multiple creatives per buyer | Multiple bids in one seatbid; SSP picks highest-priced as representative |
| Testing price sensitivity | Multiple bids at different prices; all non-winners get lurl with code 102 |

### When to Fire Trackers

| Tracker | Condition | Behavior |
|---------|-----------|----------|
| Impression pixel (event=1) | Always include in `eventtrackers` | Fires from user device on viewability (50% 1s); only first URL fires |
| Viewable tracker (event=2) | Not supported | Do not send; will be discarded |
| JavaScript tracker (method=2) | Not supported | Do not send; only method=1 (image pixel) is fired |

## Workflow

### 1. Onboarding Setup
- Prepare HTTPS bid endpoint URL (public, TLS 1.2+)
- Choose auth method: Bearer token (header) or pubid-in-URL pattern
- Send endpoint URL and auth details to contact@thrad.ai
- Receive test traffic with `test: 1` in BidRequest
- Verify error/timeout/no-bid rates are stable
- Thrad flips to production (`test: 0`)

### 2. Parse Bid Request
- Read `tmax` per request (3s in-conversation, 1s opener); do not assume fixed timeout
- Extract placement mode from `imp[].tagid` (ends in `_image` or `_text`)
- Parse Native 1.2 request from `imp[].native.request` (JSON-encoded string)
- Extract conversation signals from `imp[].ext.thrad` (keywords, intent, task, iab_tier1)
- Check `regs.gdpr` and refuse to bid if your DSP requires TCF consent (not yet sent)
- Validate `imp[].bidfloor` and ensure bid ≥ floor

### 3. Build Bid Response
- Echo `BidRequest.id` in `BidResponse.id`
- Set `cur: "USD"`
- For each bid: populate required assets (0, 1, 2, 5), honor tagid mode (asset 3 optional in image mode, omitted in text mode), always include asset 4 (logo) as fallback
- Set `price` with 2 decimals (e.g., `7.50`); SSP rounds using ROUND_HALF_UP if needed
- Populate `adomain` (required, non-empty)
- Include `nurl`, `lurl`, `burl` with HTTPS URLs and macros (`${AUCTION_PRICE}`, `${AUCTION_LOSS}`)
- For impression tracking: add one URL to `eventtrackers[event=1, method=1]` (only first fires)
- Return 200 + BidResponse or 204 for no-bid

### 4. Handle Notifications
- **nurl**: Fires on win before render; use for pacing and bid bookkeeping
- **lurl**: Fires on loss with reason code; use for price learning and bid tuning
- **burl**: Fires on viewable impression (50% 1s); reconcile with your spend tracking
- All three are fire-and-forget GETs with ~2s timeout, no retry; errors are logged and swallowed

### 5. Reconcile Reporting
- Request reporting key from contact@thrad.ai (starts with `dk_`)
- Query `GET /v1/dsp/report` with UTC hour-aligned start/end timestamps
- Parse `spend` as decimal string, not float (e.g., `"161.46358"`)
- Compare `billable_impressions` with your `burl` count (should match)
- Compare `spend` with your bid total (should match within rounding)
- Reconcile on complete UTC days (numbers settle ~1 hour after day ends)

## Common Gotchas

- **Bid rounding**: Bids with >2 decimals are rounded using ROUND_HALF_UP (e.g., 7.125 → 7.13). Submit 2 decimals to avoid surprises.
- **Asset ID mismatch**: Asset IDs are 0-based (title=0, not 1). Echo the exact IDs the request sent; mismatches cause silent bid rejection.
- **Text mode asset 3**: If tagid ends in `_text`, asset 3 is omitted from the request and will be dropped server-side if you send it. Always check tagid before populating asset 3.
- **Logo fallback**: Always populate asset 4 (logo) even in image mode — it's your fallback when the hero image fails to render or when the publisher switches to text mode.
- **Impression tracker firing**: Only the first tracker in `eventtrackers[event=1, method=1]` fires, and only from the user's device on viewability. Server-side trackers do not fire; use `burl` for server-side billing.
- **Timeout per request**: Read `tmax` on every request; do not hardcode 3s. Opener requests have 1s timeout.
- **Spend as string**: Reporting API returns spend as a decimal string (e.g., `"161.46358"`). Parse as decimal, not float, to avoid rounding errors.
- **No-bid response**: Return 204 (no content) for no-bid, not 200 + empty seatbid. Both are accepted, but 204 is lower overhead.
- **Multi-bid loss notifications**: When you submit multiple bids, all non-winning bids get `lurl` with code 102, even if your highest-priced bid wins overall. This is intentional — treat every bid uniformly in your pacing logic.
- **GDPR consent not sent**: `regs.gdpr=1` is set based on IP geo, but `user.ext.consent` (TCF string) is not yet sent. If your DSP requires consent to bid, refuse GDPR requests.
- **Viewability definition**: Billable impressions = 50% of ad on screen for 1 continuous second. Sent impressions may be higher; the gap is normal.
- **Bid floor includes downstream margin**: On resold supply, `imp.bidfloor` already includes Thrad's margin. Bid at or above it; do not add extra margin.

## Verification Checklist

Before submitting a bid response:
- [ ] `BidResponse.id` echoes `BidRequest.id` exactly
- [ ] `cur` is `"USD"` (envelope and per-bid)
- [ ] `price` is ≥ `imp.bidfloor` and has 2 decimals
- [ ] All required assets (0, 1, 2, 5) are populated with correct IDs
- [ ] Asset 3 (main image) is omitted if tagid ends in `_text`
- [ ] Asset 4 (logo) is populated (required in text mode, fallback in image mode)
- [ ] `adomain` is non-empty
- [ ] `nurl`, `lurl`, `burl` are HTTPS (non-HTTPS URLs are dropped)
- [ ] Impression tracker is in `eventtrackers[event=1, method=1]` (only first fires)
- [ ] No `event=2` or `method=2` trackers (not supported)
- [ ] Response body is <1 MB
- [ ] Response time is <3s (or <1s for opener requests)
- [ ] Return 200 + BidResponse or 204 for no-bid (not 200 + empty seatbid)

Before reconciling reporting:
- [ ] Reporting key starts with `dk_` (not your bid endpoint bearer token)
- [ ] Query uses UTC hour-aligned timestamps (e.g., `2026-09-01T00:00:00Z`)
- [ ] `spend` is parsed as decimal string, not float
- [ ] `billable_impressions` matches your `burl` count (within ~1 hour settlement window)
- [ ] Reconciliation is on complete UTC days (not today's partial day)

## Resources

- **Full page navigation**: https://docs.thrad.ai/llms.txt — comprehensive index of all Thrad documentation pages
- **OpenRTB Overview & Auction Flow**: https://docs.thrad.ai/dsp/guides/ortb/overview — first-price auction mechanics, multi-bid handling, loss notifications, pricing & commission
- **Bid API Reference**: https://docs.thrad.ai/dsp/api-reference/ortb-bid — complete BidRequest/BidResponse spec, Native 1.2 asset format, notification URLs, viewability definition
- **Reporting API**: https://docs.thrad.ai/dsp/guides/reporting — daily impressions, billable vs sent, spend reconciliation, settlement timing

---

> For additional documentation and navigation, see: https://docs.thrad.ai/llms.txt