Skip to main content
Send events to Thrad directly from your backend — useful when the action happens server-side (subscription renewal, fulfillment, async lead qualification) or when you want delivery that survives ad-blockers and ITP. The payload shape mirrors the Tag’s event call — same event names, same free-form params bag — but you authenticate with a bearer API key and the server stamps channel = "server" on every row.

​
Endpoint

POST https://events.thrad.ai/api/collect
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

​
Request

curl -X POST https://events.thrad.ai/api/collect \
  -H "Authorization: Bearer $THRAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tag_id":     "<YOUR_TAG_ID>",
    "event_name": "items_added",
    "event_id":   "evt_42",
    "timestamp":  1748275200,
    "click_id":   "clk_xyz",
    "session_id": "sess_abc",
    "params": {
      "content_id": "sku_123",
      "quantity": 2,
      "value": 58.00,
      "currency": "USD"
    }
  }'

​
Body

Only event_name is required. Everything else is optional — pass what you have.
FieldTypeNotes
event_namestringRequired. Standard (see taxonomy) or custom.
tag_idstringYour tag ID. If omitted, the server derives one from page_url host.
event_idstringFor deduplication / idempotency.
timestampnumberUnix seconds. Defaults to server receive time.
page_url, referrer, user_agentstringBrowser context, when known.
session_id, client_idstringYour stable user identifiers.
click_id, impression_id, bid_idstringAttribution IDs captured from the original ad click.
attribution_typestringclick / view / organic.
consentobjectGDPR/CCPA consent flags.
paramsobjectFree-form properties. Stored as JSON; queryable in reporting.

​
Response

HTTP/1.1 204 No Content
Fire-and-forget. A 204 means the event was accepted for storage. There’s no per-event validation feedback beyond the basic shape check.

​
What the server adds

The server enriches every row before insert:
  • ip_address — from the request
  • geo_country, geo_region, geo_city, geo_lat, geo_lon — from IP lookup
  • ua_browser, ua_os, ua_device, … — parsed from your user_agent
  • channel = "server" — overrides whatever you passed

​
Idempotency

Pass a stable event_id to dedupe retries — used as the dedup key in reporting joins.