Thrad S2S API Quickstart¶

This guide is for clients sending authenticated server-to-server events and conversions to Thrad production APIs.

Production base URL:

https://events.thrad.ai

Canonical endpoints:

POST /v1/api/collect
POST /v1/api/conversion

1) Get your API key¶

Request a partner API key from your Thrad integration owner.

export THRAD_PARTNER_TOKEN="<your_partner_api_key>"

2) Send an S2S collect event (optional)¶

Use collect for server-side events like page_view, impression, and custom funnel events.

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

Expected response: HTTP 204 No Content.

3) Send an S2S conversion¶

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

curl -X POST "https://events.thrad.ai/v1/api/conversion" \
  -H "Authorization: Bearer $THRAD_PARTNER_TOKEN" \
  -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"
  }'

Expected response:

{"status":"ok"}

Repeat the same call with the same Idempotency-Key:

{"status":"duplicate"}

4) Common errors¶

401 Missing bearer token: no Authorization header
401 Invalid API key: bad/revoked/expired key
404 Click not found: click_id does not exist
422 Validation error: invalid payload type/format

5) Notes¶

For /v1/api/collect, tag_id is optional. If omitted or blank, Thrad derives site:<host> from page_url, then Origin, then Referer.
Extra top-level conversion fields are sanitized and stored under params.extra.
For conversion retries, always reuse the same Idempotency-Key.