Events API

The Events API supports both synchronous and asynchronous event ingestion plus historical query/stats.

Auth

x-api-key is required for all endpoints on this page.

Endpoints

• POST /api/v1/events (sync)
• POST /api/v1/events/async (async queue)
• GET /api/v1/events
• GET /api/v1/events/:id
• GET /api/v1/events/stats

Ingest Event (Synchronous)

POST /api/v1/events

Request

{
  "eventName": "user.login",
  "eventCategory": "AUTHENTICATION",
  "customer": {
    "externalId": "user_123456",
    "email": "user@example.com",
    "metadata": {
      "loyalty_tier": "gold"
    }
  },
  "device": {
    "externalId": "device_abc123",
    "fingerprint": "fp_abcdef12345"
  },
  "ip": "203.0.113.42",
  "country": "US",
  "sessionId": "session_xyz789",
  "metadata": {
    "auth_result": "success"
  },
  "custom_fields": {
    "previous_login_count": 150
  }
}

Response

{
  "eventId": "evt_ckm9876543210",
  "decision": "ALLOW",
  "score": 15,
  "eventCategory": "AUTHENTICATION",
  "rulesEvaluated": 5,
  "receivedAt": "2026-04-16T10:30:00.000Z",
  "processingTimeMs": 42.5
}

Ingest Event (Asynchronous)

POST /api/v1/events/async

Returns 202 Accepted with a jobId:

{
  "status": "accepted",
  "jobId": "job_ckm1234567890",
  "eventName": "user.register",
  "receivedAt": "2026-04-16T10:30:00.000Z",
  "message": "Event queued for processing. Use the jobId to check status or configure a webhook for results."
}

Query Events

GET /api/v1/events

Key query params:

• page, limit
• eventName, eventCategory, decision
• customer, device, country
• from, to (Unix timestamp seconds)
• sortBy, sortOrder

Event Stats

GET /api/v1/events/stats

Returns aggregate counters such as:

• totalEvents
• blockedEvents
• eventsUnderReview
• uniqueCustomers
• uniqueDevices