Standard API

The Standard API is TRAX's xAPI-conformant LRS surface: the Statement, Activity, Agent, Document (State / Activity Profile / Agent Profile) and About resources, exactly as defined by the xAPI specification. A single store speaks xAPI 1.0.3 and 2.0 — the version is negotiated per request (see Version negotiation).

Authentication and error responses are common to all TRAX APIs, and the value types — Agent IFI, IRI, ISO-8601 date-time, UUID, MIME type — are defined once in the common reference.

This doc documents TRAX's surface and its specifics; it does not restate the resource semantics. For those (request/response bodies, statement structure, immutability, voiding rules, document merge behaviour, …) refer to the specification:

• xAPI 1.0.3 — ADL xAPI-Spec
• xAPI 2.0 — IEEE 9274.1.1 (and the xapi.ieee working docs)

Contents: Statements · Activities · Agents · Activity Profiles · Agent Profiles · States · About

Getting access

• Enable the API. Always enabled — the xAPI Standard API has no feature toggle (it is the core LRS surface).
• Client permission. The calling client must have the xapi/all permission enabled (Clients → edit → Permissions) for full read + write. Narrower options: xapi/all/read (read-only), or per-resource xapi/statements/read, xapi/statements/write, xapi/state, xapi/profile. Authentication is HTTP Basic — see Authentication.
• Base path. Copy your client's xapi_endpoint (…/stores/{store}/xapi) from the Clients page (the ⓘ info button) and append the resource paths below.

Base path

Every Standard API endpoint is reached under the machine-token gateway path:

/trax/api/gateway/clients/{client}/stores/{store}/xapi/<resource>

Path segments:

• {client} — your API client id (selects the auth credentials).
• {store} — the id of the store to read/write.

Every request to an /xapi/ endpoint (About excepted) must carry an X-Experience-API-Version header; the negotiated version is echoed on the response. All resources also accept HEAD (handled as GET, headers only).

Version negotiation

The X-Experience-API-Version request header is required on every /xapi/ resource. TRAX negotiates it as follows:

Request header	Negotiated version	Notes
2.0, 2.0.0, … (2.x)	2.0.0	2.0 behaviour (strong ETag concurrency, no alternate-request syntax).
1.0.0 … 1.0.3	1.0.3	1.0.x behaviour.
missing / malformed	—	400, response header X-Experience-API-Version: 0.9.

The negotiated version is returned in the response X-Experience-API-Version header. A store may be restricted to a subset of versions: a request negotiating a version the store does not support is rejected 400, with X-Experience-API-Version advertising the store's highest supported version as a retry hint. See About to discover a store's supported versions.

Alternate Request Syntax (tunnelling GET/PUT/DELETE through a POST with a method query-param) is honoured under 1.0.3 only, and only when method is the sole query parameter. Under 2.0 any request carrying method is rejected 400.

Statements

The xAPI Statement resource — store and retrieve statements.

POST   /trax/api/gateway/clients/{client}/stores/{store}/xapi/statements
PUT    /trax/api/gateway/clients/{client}/stores/{store}/xapi/statements
GET    /trax/api/gateway/clients/{client}/stores/{store}/xapi/statements

• POST — store one statement or an array of statements. Returns 200 with a JSON array of the stored statement UUIDs.
• PUT — store a single statement under a client-chosen id (statementId query param, a UUID, required). Returns 204.
• GET — query statements, or fetch one by id. Returns 200.

There is no DELETE on this resource. To void a statement, POST a voiding statement (verb http://adlnet.gov/expapi/verbs/voided referencing the target) per the spec.

GET — single statement

Name	Type	Description
statementId	UUID	Fetch this statement. Mutually exclusive with voidedStatementId.
voidedStatementId	UUID	Fetch the voided statement with this id. Mutually exclusive with statementId.
format	enum	ids, exact, or canonical (xAPI statement format).
attachments	boolean	When true, return a multipart response including attachment data (see below).

GET — statement query

Name	Type	Description
agent	Agent IFI	Statements where this agent is the actor or object.
verb	IRI	Statements with this verb.
activity	IRI	Statements with this object activity.
registration	UUID	Statements with this registration.
related_activities	boolean	Broaden activity to any related activity (object, parent, grouping, category).
related_agents	boolean	Broaden agent to any related agent (actor, object, authority, instructor, team).
since	ISO-8601 date-time	Stored after (exclusive).
until	ISO-8601 date-time	Stored at or before (inclusive).
limit	integer (≥0)	Max statements to return.
format	enum	ids, exact, or canonical.
attachments	boolean	When true, multipart response with attachment data.
ascending	boolean	Return in ascending stored order (default descending).

Response shape (GET query)

{
  "statements": [ { "id": "…", "actor": {}, "verb": {}, "object": {} } ],
  "more": "/trax/api/gateway/clients/{client}/stores/{store}/xapi/statements?before[stored]=…&limit=…"
}

Activities

The xAPI Activity resource — fetch the full (canonical, merged) definition of one activity.

GET   /trax/api/gateway/clients/{client}/stores/{store}/xapi/activities

Read-only (POST/PUT/DELETE are not allowed).

Name	Type	Description
activityId	IRI	The activity to fetch. Required.

Response shape

{
  "objectType": "Activity",
  "id": "http://example.com/courses/intro",
  "definition": { "name": { "en": "Introduction" }, "type": "http://adlnet.gov/expapi/activities/course" }
}

When no stored definition exists for the IRI, definition is omitted.

Agents

The xAPI Agents resource — fetch the Person object combining every identifier known for an agent.

GET   /trax/api/gateway/clients/{client}/stores/{store}/xapi/agents

Read-only (POST/PUT/DELETE are not allowed).

Name	Type	Description
agent	Agent IFI	The agent whose Person object to return. Required.

Response shape — an xAPI Person object (arrays of the identifiers found for the agent):

{
  "objectType": "Person",
  "name": ["Jane Doe"],
  "mbox": ["mailto:jane@example.com"]
}

Activity Profiles

The xAPI Activity Profile document resource.

POST     /trax/api/gateway/clients/{client}/stores/{store}/xapi/activities/profile
PUT      /trax/api/gateway/clients/{client}/stores/{store}/xapi/activities/profile
GET      /trax/api/gateway/clients/{client}/stores/{store}/xapi/activities/profile
DELETE   /trax/api/gateway/clients/{client}/stores/{store}/xapi/activities/profile

Name	Type	Used by	Description
activityId	IRI	all	The owning activity. Required.
profileId	text	POST, PUT, DELETE, single GET	The profile document key. Required except on a multi-GET.
since	ISO-8601 date-time	multi-GET	List keys of profiles stored after this time. Mutually exclusive with profileId.

• GET with profileId → the document (its stored Content-Type, with ETag and Last-Modified). Without profileId → 200 with a JSON array of matching profileIds.
• POST merges JSON into an existing document (or creates it); PUT replaces it; DELETE removes the single document identified by profileId.

See Document concurrency for the ETag / If-Match behaviour.

Agent Profiles

The xAPI Agent Profile document resource.

POST     /trax/api/gateway/clients/{client}/stores/{store}/xapi/agents/profile
PUT      /trax/api/gateway/clients/{client}/stores/{store}/xapi/agents/profile
GET      /trax/api/gateway/clients/{client}/stores/{store}/xapi/agents/profile
DELETE   /trax/api/gateway/clients/{client}/stores/{store}/xapi/agents/profile

Name	Type	Used by	Description
agent	Agent IFI	all	The owning agent. Required.
profileId	text	POST, PUT, DELETE, single GET	The profile document key. Required except on a multi-GET.
since	ISO-8601 date-time	multi-GET	List keys of profiles stored after this time. Mutually exclusive with profileId.

Same GET / POST / PUT / DELETE behaviour as Activity Profiles; see Document concurrency.

States

The xAPI State document resource.

POST     /trax/api/gateway/clients/{client}/stores/{store}/xapi/activities/state
PUT      /trax/api/gateway/clients/{client}/stores/{store}/xapi/activities/state
GET      /trax/api/gateway/clients/{client}/stores/{store}/xapi/activities/state
DELETE   /trax/api/gateway/clients/{client}/stores/{store}/xapi/activities/state

Name	Type	Used by	Description
activityId	IRI	all	The owning activity. Required.
agent	Agent IFI	all	The owning agent. Required.
registration	UUID	all (optional)	The registration the state belongs to.
stateId	text	POST, PUT, single GET, DELETE	The state document key. Required on POST/PUT; on GET/DELETE, omit to target multiple.
since	ISO-8601 date-time	multi-GET	List keys of states stored after this time. Mutually exclusive with stateId.

• GET with stateId → the document; without → 200 with a JSON array of matching stateIds.
• POST merges, PUT replaces, DELETE removes the addressed state(s).

See Document concurrency.

Document concurrency

For all three document resources (State, Activity Profile, Agent Profile), single-document GETs return a strong ETag (a quoted SHA-1 of the content) and a Last-Modified header. Writes honour the standard If-Match / If-None-Match preconditions, but the required behaviour differs by version:

Operation	1.0.3	2.0
PUT (overwrite existing)	If-Match / If-None-Match required; missing → 409.	Same — a header-less overwrite is 409; a header-less create is accepted (204).
POST	Preconditions honoured if present; not required.	Preconditions honoured if present; not required.
DELETE (single doc)	Preconditions honoured if present.	A provided If-Match is honoured.

Precondition outcomes: a non-matching If-Match (or If-Match: * with no existing document, or If-None-Match: * with an existing document) → 412 Precondition Failed; a missing required precondition → 409 Conflict. A W/ weak-validator prefix on If-Match is tolerated.

About

The xAPI About resource — advertises the versions the store supports.

GET   /trax/api/gateway/clients/{client}/stores/{store}/xapi/about

No authentication or X-Experience-API-Version header is required. Returns 200:

{
  "version": ["1.0.3", "2.0.0"]
}

version lists exactly the versions this store accepts — use it to drive version negotiation. A store may be configured for 1.0.3 only, 2.0.0 only, or both.