Event Tracking

Event tracking uses a dedicated REST endpoint rather than GraphQL. The endpoint uses application/x-www-form-urlencoded format, making it compatible with the browser sendBeacon API for reliable tracking that survives page navigation.

Endpoint

POST https://api.solenya.ai/v1/track/event

Authentication

Events are authenticated via an access_token form field (RFC 6750 §2.2), not the Authorization header. This avoids CORS preflight requests and makes sendBeacon compatible out of the box.

Request Fields

Field	Type	Required	Description
`access_token`	`string`	Yes	JWT bearer token
`solenya_user_uuid`	`UUID`	Yes	UUID identifying the end user (same as `Solenya-User-UUID` header)
`events`	`string` (JSON)	Yes	JSON-encoded list of event objects

Event Types

Events follow an action-object pattern using a type discriminator field.

`view_item`: User viewed a product

{
  "type": "view_item",
  "item": { "selector": "id", "eq": "SKU-001" }
}

`purchase_item`: User purchased a product

price must be in ISO 4217 format (e.g. "10.99 USD", "49.00 GBP"):

{
  "type": "purchase_item",
  "transaction_id": "TXN-001",
  "price": "99.99 USD",
  "item": { "selector": "item_group_id", "eq": "ADI_GN2901_BLANK" }
}

`view_experiment`: User was exposed to an A/B experiment

{
  "type": "view_experiment",
  "name": "checkout_v2",
  "variant": "treatment"
}

Device Metadata (Optional)

All event types accept an optional device object:

{
  "type": "view_item",
  "item": { "selector": "id", "eq": "SKU-001" },
  "device": {
    "category": "mobile",
    "language": "en-US",
    "screen_resolution": "1280x2856",
    "operating_system": "Android",
    "operating_system_version": "14",
    "model": "Pixel 9 Pro",
    "brand": "Google",
    "browser": "Chrome",
    "browser_version": "136.0.7103.60"
  }
}

Example

Open in Docs ↗

curl -X POST https://api.solenya.ai/v1/track/event \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'access_token=<access_token>' \
  -d 'solenya_user_uuid=<user_uuid>' \
  --data-urlencode 'events=[{"type":"view_item","item":{"selector":"id","eq":"SKU-001"}}]'

Response

Returns 202 Accepted:

{
  "success": true,
  "message": "Tracked 1 event(s).",
  "events_tracked": 1,
  "events_failed": 0
}

For the full REST reference including all fields and error codes, see the live docs at api.solenya.ai/v1/track/docs.