Skip to Content
TrichiDataTrichiData

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.com

Authentication flow

The API uses a two-step authentication model:

  1. init_sdk — authenticate with your project API key (Authorization: Bearer). The server creates a session, returns its id as data.sessionId and also sets a sdk_session cookie.
  2. All other endpoints — authenticate with the session, either in the X-TrichiData-Session header or with the sdk_session cookie. 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/json

Browsers may send the header cross-origin: it is allowed by CORS.

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" }
  ]
}
StatusCodeMeaning
400VALIDATION_ERROR / BAD_REQUESTInvalid request body or properties
401UNAUTHORIZEDMissing or invalid API key / session (header or cookie)
403FORBIDDENWorkspace event limit reached
404NOT_FOUNDSession not found
500INTERNAL_ERRORServer 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"
}
FieldTypeRequiredDescription
timestampinteger✅Unix timestamp in milliseconds
device.ipstring (IPv4)✅Client IP address
device.userAgentstring✅User agent string
device.localestringNoDefaults to "en-US"
device.timezonestringNoDefaults to "UTC"
trackingobject✅GA4 / Meta Pixel identifiers
tracking.ga4.clientIdstring✅GA4 client id
tracking.metaPixel.fbpstringNoMeta _fbp cookie
tracking.metaPixel.fbcstringNoMeta _fbc / constructed from fbclid
sdkVersionstring✅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"
}
FieldTypeRequiredDescription
userIdstring*Anonymous user identifier from your system. Defaults to "anonymous" in events if omitted
appVersionstring*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:

FieldTypeRequiredDescription
eventNamestring✅Reserved name or any custom string
eventIdstring✅Unique event ID (UUID recommended)
timestampinteger✅Unix timestamp in milliseconds
pageobjectNoPage context: title, name, url, referrer
propertiesobject✅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).

eventNamepropertiesRequired fields
pageurl?, referrer?, title?—
product_viewedproductId, name, category?, price?, currency?productId, name
product_addedproductId, name, price, currency, quantity?productId, name, price, currency
product_removedproductId, name, price, quantity?productId, name, price
checkout_startedtotal, currency, items[], orderId?, coupon?total, currency, items
payment_info_enteredorderId?, paymentType?, total, currency, coupon?, items[]total, currency, items
order_completedorderId, total, currency, items[], coupon?, shipping?, tax?orderId, total, currency, items
order_refundedorderId, items?, total?, currency?orderId
signed_upmethod?—
logged_inmethod?—
lead_submittedvalue?, currency?—
searchedqueryquery
level_achievedlevellevel
tutorial_completedsuccess, contentId?success
achievement_unlockedachievementId, description?achievementId
spent_creditscontentId, contentType?, amount, currency?contentId, amount
ad_impressionadType, revenue?adType
ad_clickedadTypeadType

adType must be one of: banner, interstitial, rewarded_video, native.

ProductItem (used in items arrays)

FieldTypeRequired
productIdstring✅
namestring✅
pricenumber✅
quantityinteger✅
categorystringNo
brandstringNo
variantstringNo

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"
      }
    }
  ]
}
FieldTypeRequiredDescription
dataarray✅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" }]
      }
    ]
  }
}
FieldTypeDescription
countnumberNumber of events stored
eventIdsstring[]Ids of the stored events
rejectedarrayInvalid 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 403 and no events from it are stored.


Property constraints

ConstraintValue
Max nested object depth3
Max top-level property keys80

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

LimitValue
Min events per batch1
Max events per batch500
Property nesting depth3
Top-level property keys80
Workspace event limitEnforced on /track_event and /track_events_batch

On this page