REST API
Use the HTTP API to send events from any language or environment where no SDK is available.
Use the HTTP API to send events from any language or environment where no SDK is available.
Base URL
https://sdk-api.trichidata.comAuthentication flow
The API uses a two-step authentication model:
init_sdk— authenticate with your project API key (Authorization: Bearer). The server creates a session, returns its id asdata.sessionIdand also sets asdk_sessioncookie.- All other endpoints — authenticate with the session, either in the
X-TrichiData-Sessionheader or with thesdk_sessioncookie. No Bearer token required.
Session header
Send the sessionId from the init_sdk response in the X-TrichiData-Session header. This is the simplest option for servers, scripts, mobile apps and any client without a cookie store, and it is not affected by Safari ITP or third-party cookie blocking. When both are present, the header wins.
POST /api/v1/track_event
X-TrichiData-Session: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/jsonBrowsers may send the header cross-origin: it is allowed by CORS.
Session cookie
Cookie-based requests must include credentials:
fetch('https://sdk-api.trichidata.com/api/v1/track_event', {
method: 'POST',
credentials: 'include',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ ... }),
});Cookie attributes: httpOnly, sameSite: none, secure in production, 7-day TTL (configurable).
Response format
All endpoints return a consistent envelope.
Success:
{
"success": true,
"message": "Event tracked successfully",
"data": { "eventId": "550e8400-e29b-41d4-a716-446655440000" }
}Error:
{
"success": false,
"code": "VALIDATION_ERROR",
"message": "Validation error",
"errors": [
{ "field": "eventName", "message": "Required" }
]
}| Status | Code | Meaning |
|---|---|---|
400 | VALIDATION_ERROR / BAD_REQUEST | Invalid request body or properties |
401 | UNAUTHORIZED | Missing or invalid API key / session (header or cookie) |
403 | FORBIDDEN | Workspace event limit reached |
404 | NOT_FOUND | Session not found |
500 | INTERNAL_ERROR | Server error |
POST /api/v1/init_sdk
Initializes an SDK session. Call this once per client before tracking events.
Auth: Authorization: Bearer <apiKey>
Request
POST /api/v1/init_sdk
Authorization: Bearer prj_ak_xxxxxxxxxxxx
Content-Type: application/json
{
"timestamp": 1743878400000,
"device": {
"ip": "203.0.113.42",
"userAgent": "Mozilla/5.0 ...",
"locale": "en-US",
"timezone": "EET"
},
"tracking": {
"ga4": {
"clientId": "717831353.1785147356"
},
"metaPixel": {
"fbp": "fb.1.1753809500123.123456789",
"fbc": "fb.1.1753809500123.IwAR2Qx3AbCdEfGhIjKlMnOpQrStUvWxYz123456789"
}
},
"sdkVersion": "0.5.2"
}| Field | Type | Required | Description |
|---|---|---|---|
timestamp | integer | ✅ | Unix timestamp in milliseconds |
device.ip | string (IPv4) | ✅ | Client IP address |
device.userAgent | string | ✅ | User agent string |
device.locale | string | No | Defaults to "en-US" |
device.timezone | string | No | Defaults to "UTC" |
tracking | object | ✅ | GA4 / Meta Pixel identifiers |
tracking.ga4.clientId | string | ✅ | GA4 client id |
tracking.metaPixel.fbp | string | No | Meta _fbp cookie |
tracking.metaPixel.fbc | string | No | Meta _fbc / constructed from fbclid |
sdkVersion | string | ✅ | Semver, e.g. "0.5.2" |
Response
{
"success": true,
"message": "SDK initialized successfully",
"data": { "sessionId": "550e8400-e29b-41d4-a716-446655440000" }
}Pass sessionId in the X-TrichiData-Session header on the following requests. The response also sets a sdk_session cookie with the same id.
POST /api/v1/identify
Associates session context with the current session. At least one field is required. Omitted values default to "anonymous" for userId and "unknown" for appVersion in subsequent events.
Auth: X-TrichiData-Session header or sdk_session cookie
Request
POST /api/v1/identify
X-TrichiData-Session: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json
{
"userId": "usr_7f3a9b2c",
"appVersion": "2.4.1"
}| Field | Type | Required | Description |
|---|---|---|---|
userId | string | * | Anonymous user identifier from your system. Defaults to "anonymous" in events if omitted |
appVersion | string | * | Application version (e.g. "2.4.1"). Defaults to "unknown" in events if omitted |
* At least one of userId or appVersion must be provided.
Response
{
"success": true,
"message": "User identified successfully",
"data": { "userId": "usr_7f3a9b2c", "appVersion": "2.4.1" }
}POST /api/v1/track_event
Tracks a single event.
Auth: X-TrichiData-Session header or sdk_session cookie
Request
Every event shares these base fields:
| Field | Type | Required | Description |
|---|---|---|---|
eventName | string | ✅ | Reserved name or any custom string |
eventId | string | ✅ | Unique event ID (UUID recommended) |
timestamp | integer | ✅ | Unix timestamp in milliseconds |
page | object | No | Page context: title, name, url, referrer |
properties | object | ✅ | Always an object; use {} when there are no parameters |
Example — page view:
POST /api/v1/track_event
X-TrichiData-Session: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json
{
"eventName": "page",
"eventId": "660e8400-e29b-41d4-a716-446655440001",
"timestamp": 1710512520000,
"page": {
"title": "Pricing",
"url": "https://example.com/pricing"
},
"properties": {
"url": "https://example.com/pricing",
"referrer": "https://google.com"
}
}Example — order completed:
POST /api/v1/track_event
X-TrichiData-Session: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json
{
"eventName": "order_completed",
"eventId": "770e8400-e29b-41d4-a716-446655440002",
"timestamp": 1710512580000,
"properties": {
"orderId": "ord_123",
"total": 49.90,
"currency": "USD",
"items": [
{
"productId": "prod_456",
"name": "Widget",
"price": 49.90,
"quantity": 1
}
]
}
}Example — custom event:
{
"eventName": "promo_banner_click",
"eventId": "880e8400-e29b-41d4-a716-446655440003",
"timestamp": 1710512600000,
"properties": { "slot": "hero" }
}Reserved event names
If eventName matches a reserved name below, properties are validated against that schema. Any other eventName is treated as a custom event (properties is a free-form object, max 50 keys / 3 nesting levels).
eventName | properties | Required fields |
|---|---|---|
page | url?, referrer?, title? | — |
product_viewed | productId, name, category?, price?, currency? | productId, name |
product_added | productId, name, price, currency, quantity? | productId, name, price, currency |
product_removed | productId, name, price, quantity? | productId, name, price |
checkout_started | total, currency, items[], orderId?, coupon? | total, currency, items |
payment_info_entered | orderId?, paymentType?, total, currency, coupon?, items[] | total, currency, items |
order_completed | orderId, total, currency, items[], coupon?, shipping?, tax? | orderId, total, currency, items |
order_refunded | orderId, items?, total?, currency? | orderId |
signed_up | method? | — |
logged_in | method? | — |
lead_submitted | value?, currency? | — |
searched | query | query |
level_achieved | level | level |
tutorial_completed | success, contentId? | success |
achievement_unlocked | achievementId, description? | achievementId |
spent_credits | contentId, contentType?, amount, currency? | contentId, amount |
ad_impression | adType, revenue? | adType |
ad_clicked | adType | adType |
adType must be one of: banner, interstitial, rewarded_video, native.
ProductItem (used in items arrays)
| Field | Type | Required |
|---|---|---|
productId | string | ✅ |
name | string | ✅ |
price | number | ✅ |
quantity | integer | ✅ |
category | string | No |
brand | string | No |
variant | string | No |
Response
{
"success": true,
"message": "Event tracked successfully",
"data": { "eventId": "770e8400-e29b-41d4-a716-446655440002" }
}Workspace event limits are checked on this endpoint. If the limit is reached, the API returns 403 Forbidden.
POST /api/v1/track_events_batch
Tracks up to 500 events in a single request. Use it from servers and scripts to send events in bulk; the SDKs use it to flush their queue.
Each event is validated on its own: valid events are stored, invalid ones are returned in rejected and do not fail the request.
Auth: X-TrichiData-Session header or sdk_session cookie
Request
POST /api/v1/track_events_batch
X-TrichiData-Session: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json
{
"data": [
{
"eventName": "page",
"eventId": "880e8400-e29b-41d4-a716-446655440003",
"timestamp": 1710512600000,
"properties": { "url": "/pricing" }
},
{
"eventName": "product_viewed",
"eventId": "990e8400-e29b-41d4-a716-446655440004",
"timestamp": 1710512610000,
"properties": {
"productId": "prod_456",
"name": "Widget",
"price": 49.90,
"currency": "USD"
}
}
]
}| Field | Type | Required | Description |
|---|---|---|---|
data | array | ✅ | Array of event objects (same shape as /track_event), 1 to 500 items |
Response
{
"success": true,
"message": "Events tracked successfully",
"data": {
"count": 2,
"eventIds": [
"880e8400-e29b-41d4-a716-446655440003",
"990e8400-e29b-41d4-a716-446655440004"
],
"rejected": []
}
}If some events are invalid, the request still returns 200. count and eventIds cover the stored events, and each invalid one is listed in rejected with its position in data:
{
"success": true,
"message": "Events tracked successfully",
"data": {
"count": 1,
"eventIds": ["880e8400-e29b-41d4-a716-446655440003"],
"rejected": [
{
"index": 1,
"eventId": "990e8400-e29b-41d4-a716-446655440004",
"errors": [{ "field": "properties/price", "message": "Invalid input: expected number, received string" }]
}
]
}
}| Field | Type | Description |
|---|---|---|
count | number | Number of events stored |
eventIds | string[] | Ids of the stored events |
rejected | array | Invalid events: index in data, eventId when sent, and errors (field, message) |
Do not retry rejected events unchanged: fix the payload first. A request-level error (for example 401 or a body that is not an array of 1–500 items) rejects the whole batch.
Note: Workspace event limits apply to batches too. The stored events are counted against the limit; if the batch would exceed it, the request fails with
403and no events from it are stored.
Property constraints
| Constraint | Value |
|---|---|
| Max nested object depth | 3 |
| Max top-level property keys | 80 |
Typed events may include nested objects and arrays (e.g. items in checkout_started). Exceeding depth or key limits returns 400 Bad Request.
{
"success": false,
"code": "BAD_REQUEST",
"message": "Invalid properties: nested object depth exceeds maximum of 3.",
"errors": [
{ "field": "properties", "message": "Nested object depth exceeds maximum of 3" }
]
}Limits summary
| Limit | Value |
|---|---|
| Min events per batch | 1 |
| Max events per batch | 500 |
| Property nesting depth | 3 |
| Top-level property keys | 80 |
| Workspace event limit | Enforced on /track_event and /track_events_batch |