XP API

The XP API provides read access to the XP (experience points) ledger for students. XP entries are created automatically when your application submits GradeEvent Caliper events with scoreType: "XP". All endpoints require Authorization: Bearer <token> and scope events.readonly.

Base prefix: https://api.alpha-1edtech.ai/xp/1.0

---

GET /xp/1.0/users/:userId/entries

Returns a paginated list of XP entries for a student. Each entry represents one XP-earning event. Supports filtering by application and date range.

Scope: events.readonly

Path params

Name	Description
userId	Student UUID

Query params

Name	Description	Required
applicationId	Filter by application sourcedId	no
startDate	Start of the date range (ISO datetime). Alias: after	no
endDate	End of the date range (ISO datetime). Alias: before	no
offset	Number of records to skip (default 0)	no
limit	Maximum records per page (default 50, max 100)	no

Response

200 OK:

{
  "entries": [
    {
      "id": "12345",
      "value": 150,
      "userId": "22222222-2222-2222-2222-222222222222",
      "applicationId": "your-app",
      "sourceEventId": "urn:uuid:event-unique-id",
      "dateGenerated": "2026-01-15T14:30:00.000Z",
      "subject": "Math",
      "courseName": "Math Grade 5"
    }
  ],
  "offset": 0,
  "limit": 50,
  "total": 42
}

Field	Type	Description
id	string or integer	Entry identifier
value	number	XP value earned
userId	string	Student sourcedId
applicationId	string	Application that generated this XP
sourceEventId	string	Source identifier for idempotency
dateGenerated	string (ISO 8601)	When the entry was created
subject	string	Subject name
courseName	string	Course display name

400 Bad Request — Invalid query parameters (e.g., malformed dates).

404 Not Found — User not found.

Example

curl "https://api.alpha-1edtech.ai/xp/1.0/users/22222222-2222-2222-2222-222222222222/entries?startDate=2026-01-01T00:00:00Z&limit=20" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"