Skip to main content

Record event

POST 
/events/record

Records a gameplay event and evaluates it against the configured server-side game definition sequence.

Field rules:

  • definition_key: exactly 8 alphanumeric characters
  • event_name: required string
  • event_data: JSON object (default {})
  • idempotency_key: required string; use a unique key per event send attempt

Request​

Responses​

Successful Response

Request body​

{
  "definition_key": "Ab12Cd34",
  "event_name": "game.level.completed",
  "event_data": {
    "level": 3,
    "result": "win"
  },
  "idempotency_key": "session-777:event-15"
}

Typical responses​

Sequence started:

{
  "status": "sequence_started",
  "definition": "daily-win-sequence"
}

Final step matched and reward credited:

{
  "status": "matched",
  "rewarded": true,
  "gems_credited": 3,
  "new_balance": 156,
  "transaction_id": 9001
}

Rejected:

{
  "status": "rejected",
  "reason": "wrong_step"
}

cURL example​

curl -X POST "http://localhost:8001/events/record" \
  -H "x-client-id: <client-id>" \
  -H "x-client-secret: <client-secret>" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"definition_key":"Ab12Cd34","event_name":"game.level.completed","event_data":{"level":3,"result":"win"},"idempotency_key":"session-777:event-15"}'