Server API Reference

The TRACIO Server API lets you query identification events, look up a visitor's history, and manage webhooks. It is workspace-scoped and authenticated with the dashboard session (Clerk) — this is the same API the TRACIO dashboard uses internally.

Note: There is no separate API-only host and no standalone API secret. The API is served on the application host (for example https://app.tracio.ai/api/v1) and authenticated with your Clerk session JWT. Every request is additionally checked against your workspace role (RBAC), so a token only grants access to data in workspaces you can see.

Base URL

https://app.tracio.ai/api/v1

All event, visitor, and webhook endpoints are scoped to a workspace and live under /subscriptions/:id, where :id is the workspace ID.

Authentication

Send your Clerk session JWT in the Authorization header:

curl -H "Authorization: Bearer <clerk-session-jwt>" \
  https://app.tracio.ai/api/v1/subscriptions/:id/events/:requestId

The caller must have the analytics-read permission for the target workspace. Requests that pass authentication but lack the permission return 403.

Endpoints

See Webhooks for the webhook payload and signature details.

Response Envelope

Every response is wrapped in a consistent envelope.

Success:

{
  "ok": true,
  "data": {}
}

Error:

{
  "ok": false,
  "error": {
    "code": "not_found",
    "message": "event not found"
  }
}

GET /subscriptions/:id/events/:requestId

Retrieve a single identification event by its request ID.

Request:

GET /api/v1/subscriptions/:id/events/1710432000_abc123def
Authorization: Bearer <clerk-session-jwt>

Response (200 OK):

{
  "ok": true,
  "data": {
    "request_id": "1710432000_abc123def",
    "visitor_id": "X7fh2Hg9LkMn3pQr",
    "workspace_id": "b201f2ba-…",
    "timestamp": "2024-03-12T16:00:00Z",
    "url": "https://your-app.com/login",
    "ip": "94.142.239.124",
    "user_agent": "Mozilla/5.0 …",
    "confidence": 0.95,
    "bot_result": "human",
    "bot_type": "",
    "browser_name": "Chrome",
    "browser_version": "120.0",
    "os_name": "macOS",
    "os_version": "14.3",
    "device_type": "desktop",
    "incognito": false,
    "ip_country": "CZ",
    "ip_city": "Prague",
    "ip_latitude": 50.05,
    "ip_longitude": 14.4,
    "ip_timezone": "Europe/Prague",
    "linked_id": "user_12345",
    "tag": "login",
    "origin": "https://your-app.com",
    "raw_signals": "{ … }"
  }
}

The event object is a flat, snake_case JSON document. Fields that have no value are returned as their zero value (empty string, 0, or false).

Note: Richer decision, risk, and network signal fields — decision, risk_score, suspect_score, bot_score, and the is_vpn/is_proxy/ is_tor/is_datacenter flags — are present in this read-API JSON, but the read query does not currently populate them, so they always serialize as their zero/empty values. The populated, enriched values are delivered through webhooks, which carry the full payload.

Core fields

raw_signals is an opaque, advanced field: a serialized blob of raw detection signals used by the dashboard's deeper analysis views. Its shape is not stable and is intended for internal analysis — integrate against the core fields above, not against raw_signals.

The decision, risk, and network signal fields (decision, risk_score, suspect_score, bot_score, is_vpn, is_proxy, is_tor, is_datacenter) are present in this read-API JSON, but the read query does not currently populate them — they always serialize as their zero/empty values here. The table above lists the fields that carry meaningful values from this endpoint. To consume the populated decision, risk, and network signals, use webhooks.

GET /subscriptions/:id/events/search

List events for the workspace, most recent first.

Query parameters:

Response (200 OK):

{
  "ok": true,
  "data": {
    "events": [{ "request_id": "…", "visitor_id": "…", "timestamp": "…", "bot_result": "human" }],
    "paginationKey": "2024-03-12T15:59:58.123456789Z"
  }
}

Each object in events has the same full shape as the single-event endpoint above (all core fields including raw_signals); the example here is abbreviated for brevity — search is not a lightweight projection.

Results are ordered by timestamp descending. To fetch the next page, pass the returned paginationKey back as the paginationKey query parameter. When the last page is reached, paginationKey is omitted from the response.

GET /subscriptions/:id/visitors/:visitorId

Retrieve the recent event history for a single visitor. The response uses the same event object as GET /events/:requestId.

Error Responses

Errors use the standard envelope with a machine-readable code.

403 Forbidden

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "insufficient permissions"
  }
}

404 Not Found

{
  "ok": false,
  "error": {
    "code": "not_found",
    "message": "event not found"
  }
}

500 Internal Server Error

{
  "ok": false,
  "error": {
    "code": "internal",
    "message": "internal server error"
  }
}