Thrad Server-to-Server API Integration¶

Production endpoint:

https://events.thrad.ai

Authentication¶

Both endpoints require:

Authorization: Bearer <YOUR_API_KEY>

If the key is missing, invalid, revoked, or expired, the API returns 401.

Common Headers¶

Required:

Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

Recommended:

Idempotency-Key: <unique_operation_key> for /v1/api/conversion

S2S Collect API¶

Canonical endpoint:

POST /v1/api/collect

Use this for general server-side events (for example page views, impressions, or custom funnel events) when you want authenticated ingestion.

Request Body¶

Required fields:

Field	Type	Notes
`event_name`	string	Event name such as `page_view`, `impression`, `signup_started`.

Optional fields:

Field	Type	Notes
`tag_id`	string	Tag/pixel identifier for source context.
`event_id`	string	Recommended dedupe key with `tag_id`.
`timestamp`	integer	Unix timestamp (seconds).
`page_url`	string	Event context URL.
`referrer`	string	Event context referrer.
`user_agent`	string	Client UA when available.
`channel`	string	Ignored for S2S collect; stored as `server`.
`session_id`	string	Optional session identifier.
`attribution_type`	string	e.g. `click`, `view`, `organic`.
`impression_id`	string	Impression identifier when available.
`click_id`	string	Click identifier when available.
`bid_id`	string	Bid identifier when available.
`impression_state`	string	e.g. `rendered`, `in_view`, `viewable`, `view_end`.
`view_time_ms`	integer	View time in milliseconds.
`consent`	object	Consent payload (GDPR/CCPA).
`params`	object	Free-form parameters.

Behavior notes:

Response is 204 No Content on success.
channel is always stored as server for this endpoint.
If tag_id is omitted/blank, Thrad derives it as site:<host> from page_url, then Origin, then Referer (fallback site:unknown).
Thrad stamps auth metadata into params:
integration: "partner_s2s"
partner_id
api_key_label
Dedupe applies when event_id is provided (by tag_id + event_id).

Example Request¶

curl -X POST "https://events.thrad.ai/v1/api/collect" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tag_id": "adv_001",
    "event_name": "page_view",
    "event_id": "pv-order-123-step-1",
    "timestamp": 1771879200,
    "page_url": "https://shop.example.com/checkout",
    "params": {
      "step": "shipping"
    }
  }'

S2S Conversion API¶

Canonical endpoint:

POST /v1/api/conversion

Use this when your backend reports a conversion tied to a Thrad click_id.

Request Body¶

Required fields:

Field	Type	Notes
`click_id`	string	Thrad click identifier (UUID format recommended).
`conversion_time`	ISO-8601 datetime	e.g. `2026-02-19T18:00:00Z`.
`conversion_value`	number	Conversion amount.
`currency`	string	3-letter ISO currency code, e.g. `USD`.

Optional fields:

Field	Type	Notes
`event_type`	string	Defaults to `purchase_completed` if omitted.
`order_id`	string	Recommended for dedupe and reconciliation.
`event_id`	string	Optional explicit event identifier.
`page_url`	string	Conversion context URL.
`referrer`	string	Conversion context referrer.
`user_agent`	string	Client UA when available.
`channel`	string	Defaults to `server` if omitted.
`session_id`	string	Optional session identifier.
`client_id`	string	Optional client/user identifier.
`tag_id`	string	Optional Thrad tag identifier.

Additional top-level fields are accepted and stored in sanitized form under params.extra.

Example Request¶

curl -X POST "https://events.thrad.ai/v1/api/conversion" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-123" \
  -d '{
    "click_id": "11111111-1111-4111-8111-111111111111",
    "conversion_time": "2026-02-19T18:00:00Z",
    "conversion_value": 49.99,
    "currency": "USD",
    "order_id": "order-123",
    "event_type": "purchase_completed",
    "customer_tier": "gold"
  }'

Responses¶

Success:

{ "status": "ok" }

Duplicate:

{ "status": "duplicate" }

Dedupe and Idempotency¶

Thrad dedupes S2S conversions using:

Idempotency-Key header or event_id field.
order_id (when provided) for the same click/event type.

If both Idempotency-Key and event_id are supplied, Idempotency-Key takes precedence.

Error Codes¶

HTTP	Meaning	Typical fix
`400`	Bad request / invalid data	Validate payload format and required fields.
`401`	Missing/invalid API key	Check Bearer token value and key status.
`404`	`click_id` not found (conversion API)	Ensure click id is captured and passed correctly.
`422`	Validation error	Fix field types/format.
`429`	Rate limit exceeded	Retry with backoff.
`5xx`	Server-side issue	Retry with backoff and idempotency.

Retry Guidance¶

Retry on network errors, 429, and 5xx.
Reuse the same Idempotency-Key for conversion retries of the same event.
Use exponential backoff with jitter.

Click ID Source¶

For click-through attribution, capture thrad_click_id from the advertiser landing URL after Thrad redirect and persist it through checkout/order flow.

Support¶

If you need field mapping help, higher throughput limits, or onboarding support, contact your Thrad integration owner.