API REFERENCE

State

/xapi/activities/state

State documents store arbitrary data (any content type, typically JSON) against a unique activityId + agent + stateId key. Unlike statements, state documents are mutable — you can overwrite or delete them. Use them for learner progress, bookmarks, and game configuration.

Required Query Parameters

Parameter	Required for	Description
activityId	All	IRI identifying the activity (your game or level URL)
agent	All	JSON Agent object, e.g. {"mbox":"mailto:x@y.com","objectType":"Agent"}
stateId	GET/PUT/DELETE single doc	Identifies the specific state document
since	GET list only	ISO 8601 — only return IDs of documents changed after this time

PUT Save State Document

Creates or replaces a state document. The entire body is stored as-is.

http

PUT /xapi/activities/state?activityId=https://your-game.com&agent={"mbox":"mailto:s@school.edu","objectType":"Agent"}&stateId=progress
Authorization: Basic <base64(key:secret)>
Content-Type: application/json
X-Experience-API-Version: 1.0.3

{
  "currentLevel": 5,
  "totalScore": 1240,
  "completedLevels": [1, 2, 3, 4],
  "lastSaved": "2026-06-27T10:30:00.000Z"
}

// Response: 204 No Content

GET Get State Document

Returns the state document body. The response Content-Type matches what was stored.

http

GET /xapi/activities/state?activityId=https://your-game.com&agent={"mbox":"mailto:s@school.edu","objectType":"Agent"}&stateId=progress
Authorization: Basic <base64(key:secret)>
X-Experience-API-Version: 1.0.3

// 200 OK — body is the stored document
{
  "currentLevel": 5,
  "totalScore": 1240,
  ...
}

// 404 Not Found — no document for this key

GET List State IDs

Omit stateId to retrieve all document IDs for an agent+activity combination.

http

GET /xapi/activities/state?activityId=https://your-game.com&agent={"mbox":"mailto:s@school.edu","objectType":"Agent"}
Authorization: Basic <base64(key:secret)>
X-Experience-API-Version: 1.0.3

// 200 OK
["progress", "settings", "bookmarks"]

DELETE Delete State Document(s)

With stateId: deletes that specific document. Without stateId: deletes all documents for the agent+activity.

http

// Delete one document
DELETE /xapi/activities/state?activityId=https://your-game.com&agent={...}&stateId=progress

// Delete all documents (e.g. reset game progress)
DELETE /xapi/activities/state?activityId=https://your-game.com&agent={...}

// Response: 204 No Content

← Statements Agents →