Events API
Emit custom events from your application. Events are processed synchronously and can trigger challenge evaluations, badge unlocks, and other automated actions based on your configured rules.
Authentication: All endpoints require an
X-API-Key header. Base URL: https://YOUR_API_DOMAIN/api/v1/gamify| Method | Endpoint | Description |
|---|---|---|
| POST | /gamify/events | Emit a single event (synchronous processing). |
| POST | /gamify/events/batch | Batch emit up to 100 events. |
| GET | /gamify/participants/{pid}/events | Query event history with filters. |
Emit a Custom Event
POST /api/v1/gamify/events
{
"participant_id": "user_123",
"event_name": "purchase_completed",
"properties": {
"amount": 49.99,
"currency": "USD",
"product_id": "prod_abc"
},
"timestamp": "2026-02-14T10:00:00Z",
"idempotency_key": "purchase_ord_001"
}
// Response
{
"event_id": "evt_uuid",
"fact_id": "fact_uuid",
"status": "processed"
}Query Event History
GET /api/v1/gamify/participants/user_123/events?event_name=purchase_completed&page=1&page_size=20
{
"participant_id": "user_123",
"events": [
{
"id": "evt_uuid",
"event_name": "purchase_completed",
"properties": { "amount": 49.99, "currency": "USD" },
"occurred_at": "2026-02-14T10:00:00Z"
}
],
"total": 156,
"page": 1,
"page_size": 20
}