API REFERENCE

Agents

/xapi/agents/xapi/agents/profile

The Agents resource provides information about learners (agents) derived from stored statements. Agent Profiles are document stores — similar to State, but scoped to an agent globally rather than per-activity. Use them for learner preferences or accessibility settings that apply across all games.

GET /xapi/agents — Person Object

Returns a Person object aggregating all known identifiers for a given agent across all stored statements.

http

GET /xapi/agents?agent={"mbox":"mailto:student@school.edu","objectType":"Agent"}
Authorization: Basic <base64(key:secret)>
X-Experience-API-Version: 1.0.3

// 200 OK
{
  "objectType": "Person",
  "mbox": ["mailto:student@school.edu"],
  "name": ["Jane Smith"]
}

// 404 Not Found — no statements stored for this agent

GET /xapi/agents/profile — Get Profile

Retrieve a single agent profile document by profileId, or list all profile IDs by omitting it.

http

// Get a specific profile document
GET /xapi/agents/profile?agent={"mbox":"mailto:s@school.edu","objectType":"Agent"}&profileId=preferences
Authorization: Basic <base64(key:secret)>
X-Experience-API-Version: 1.0.3

// 200 OK — the stored document
{
  "fontSize": "large",
  "colorblindMode": true,
  "language": "en-US"
}

// List all profile IDs for this agent
GET /xapi/agents/profile?agent={...}

// 200 OK
["preferences", "accessibility"]

PUT /xapi/agents/profile — Save Profile

http

PUT /xapi/agents/profile?agent={"mbox":"mailto:s@school.edu","objectType":"Agent"}&profileId=preferences
Authorization: Basic <base64(key:secret)>
Content-Type: application/json
X-Experience-API-Version: 1.0.3

{
  "fontSize": "large",
  "colorblindMode": true,
  "language": "en-US"
}

// Response: 204 No Content

DELETE /xapi/agents/profile — Delete Profile

http

// Delete a specific profile document
DELETE /xapi/agents/profile?agent={...}&profileId=preferences

// Delete all profiles for this agent
DELETE /xapi/agents/profile?agent={...}

// Response: 204 No Content

Agent Identification Forms

All agent endpoints accept any of the three xAPI agent identification forms:

json

// 1. Email (mbox)
{"objectType": "Agent", "mbox": "mailto:student@school.edu"}

// 2. OpenID
{"objectType": "Agent", "openid": "https://accounts.google.com/o/openid2/..."}

// 3. Account (recommended for privacy)
{"objectType": "Agent", "account": {"homePage": "https://edu.games", "name": "user_abc123"}}

← State Activities →