XP | Amba Docs

XP rules map engagement events to XP awards; they're evaluated by the engagement-event pipeline on every POST /client/events write. This module also exposes read endpoints over user_xp.

Source: apps/api/src/routes/admin/xp.ts.

Endpoints

Method	Path	Description
POST	`/admin/projects/:projectId/xp`	Create an XP rule.
GET	`/admin/projects/:projectId/xp`	List XP rules.
PATCH	`/admin/projects/:projectId/xp/:ruleId`	Partial update.
DELETE	`/admin/projects/:projectId/xp/:ruleId`	Delete a rule.
GET	`/admin/projects/:projectId/xp/users/:userId`	Fetch a single user's XP.
GET	`/admin/projects/:projectId/xp/users`	Paginated leaderboard-style list of users by total XP.

POST /admin/projects/:projectId/xp

Request

Field	Type	Required	Default
`name`	string	yes	—
`event_name`	string	yes	—
`xp_amount`	number	yes	—
`max_per_day`	number \| null	no	null
`cooldown_seconds`	number	no	0

Response 201

{
  "data": {
    "id": "…",
    "name": "…",
    "event_name": "workout_completed",
    "xp_amount": 10,
    "max_per_day": null,
    "cooldown_seconds": 0
  }
}

Try it:

POST/admin/projects/%7B%7BprojectId%7D%7D/xp

developer auth

curl -X POST 'https://api.amba.dev/admin/projects/%7B%7BprojectId%7D%7D/xp'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X POST '${BASE_URL}/admin/projects/{projectId}/xp' \
  -H 'Authorization: Bearer ${DEV_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

GET /admin/projects/:projectId/xp

{ "data": [{ "id": "…", "name": "…", "event_name": "…", "xp_amount": 10 }] }

Try it:

GET/admin/projects/%7B%7BprojectId%7D%7D/xp

developer auth

curl -X GET 'https://api.amba.dev/admin/projects/%7B%7BprojectId%7D%7D/xp'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET '${BASE_URL}/admin/projects/{projectId}/xp' \
  -H 'Authorization: Bearer ${DEV_TOKEN}'

PATCH /admin/projects/:projectId/xp/:ruleId

Allowed fields: name, event_name, xp_amount, max_per_day, cooldown_seconds, is_active.

Errors

404 NOT_FOUND.
500 UPDATE_FAILED.

Try it:

PATCH/admin/projects/%7B%7BprojectId%7D%7D/xp/%7B%7BruleId%7D%7D

developer auth

curl -X PATCH 'https://api.amba.dev/admin/projects/%7B%7BprojectId%7D%7D/xp/%7B%7BruleId%7D%7D'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X PATCH '${BASE_URL}/admin/projects/{projectId}/xp/{ruleId}' \
  -H 'Authorization: Bearer ${DEV_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

DELETE /admin/projects/:projectId/xp/:ruleId

{ "data": { "deleted": true } }

Try it:

DELETE/admin/projects/%7B%7BprojectId%7D%7D/xp/%7B%7BruleId%7D%7D

developer auth

curl -X DELETE 'https://api.amba.dev/admin/projects/%7B%7BprojectId%7D%7D/xp/%7B%7BruleId%7D%7D'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X DELETE '${BASE_URL}/admin/projects/{projectId}/xp/{ruleId}' \
  -H 'Authorization: Bearer ${DEV_TOKEN}'

GET /admin/projects/:projectId/xp/users/:userId

Response 200

{ "data": { "app_user_id": "…", "total_xp": 1234, "level": 12, "updated_at": "…" } }

Errors

404 NOT_FOUND — user has no user_xp row yet.

Try it:

GET/admin/projects/%7B%7BprojectId%7D%7D/xp/users/%7B%7BuserId%7D%7D

developer auth

curl -X GET 'https://api.amba.dev/admin/projects/%7B%7BprojectId%7D%7D/xp/users/%7B%7BuserId%7D%7D'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET '${BASE_URL}/admin/projects/{projectId}/xp/users/{userId}' \
  -H 'Authorization: Bearer ${DEV_TOKEN}'

GET /admin/projects/:projectId/xp/users

Paginated list ordered by total_xp DESC.

Query

Param	Default
`limit`	50
`offset`	0

Response 200

{
  "data": [
    {
      "app_user_id": "…",
      "total_xp": 1234,
      "level": 12,
      "app_users": { "display_name": "…", "avatar_url": "…" }
    }
  ],
  "total": 1234,
  "offset": 0,
  "limit": 50
}

Try it:

GET/admin/projects/%7B%7BprojectId%7D%7D/xp/users

developer auth

curl -X GET 'https://api.amba.dev/admin/projects/%7B%7BprojectId%7D%7D/xp/users'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET '${BASE_URL}/admin/projects/{projectId}/xp/users' \
  -H 'Authorization: Bearer ${DEV_TOKEN}'

XP

On this page