API reference

Shared reference for the TRAX APIs: authentication, error responses, value/field types, and the query object. Each API doc references the relevant sections.

Authentication

HTTP Basic authentication, common to all TRAX gateway APIs. The {client} path segment selects the API client; that client's credentials are sent in the Authorization header:

Authorization: Basic <base64(username:password)>

Example:

curl -u "<username>:<password>" \
  "https://<host>/trax/api/gateway/clients/{client}/stores/{store}/statements"

Errors

On success each API returns its own body (see that API's doc); on failure the status and body follow this model:

Status	When	Body
400	Bad request — e.g. an unauthorized filter or option key.	Plain-text message.
401	Not authenticated — missing or invalid credentials.	Short message.
403	Authenticated, but not authorized for this store or operation.	Plain-text message.
404	Unknown client or store in the request path.	Standard not-found response.
422	A parameter value failed validation (e.g. a malformed IRI, date, or agent).	JSON { "message": …, "errors": { … } }.

Types

Agent IFI

An xAPI Inverse Functional Identifier — a JSON object identifying an agent or group, in exactly one of four mutually exclusive forms:

Form	Example
Email	{"mbox": "mailto:jane@example.com"}
Email SHA-1	{"mbox_sha1sum": "b29427ee6959c18f1ad7ee4096d65f78986a1866"} (40-hex SHA-1 of the mailto: URI)
OpenID	{"openid": "https://openid.example.com/jane"}
Account	{"account": {"homePage": "https://lms.example.com", "name": "jane"}}

Hashed ID

A 32-character lowercase hexadecimal xxh128 hash — hash('xxh128', <canonical string>). TRAX stores agents, activities, verbs and types by this hash and returns it in *_id / *_ids fields.

You normally never build these: the agent / verb / activity filters accept the plain IFI/IRI and hash it for you. Construct one only to match a raw column directly — the canonical string must be exact:

Kind	Canonical string	Worked example
Verb / activity / activity-type	the IRI	xxh128("http://adlnet.gov/expapi/verbs/completed") = 090a9e4b1fb4a1bc05302c32156c4390
Agent (by IFI)	<ifi-type>::<value>	xxh128("mbox::mailto:jane@example.com") = 53c7fae102d2a02964ad522cdd74ad5e

Agent canonical strings by IFI form: mbox::mailto:…, mbox_sha1sum::<sha1>, openid::<url>, account::<name>@<homePage>. Document / profile / state row ids share the same 32-hex form but are internal composite hashes — not meant to be reconstructed.

UUID

An RFC 4122 UUID — 8-4-4-4-12 lowercase hex, e.g. d3f4a1b2-1c2d-4e5f-8a9b-0c1d2e3f4a5b. TRAX-minted ids (e.g. a statement id the LRS assigns) are v4; a client-supplied registration may be any version.

ISO-8601 date-time

An ISO-8601 timestamp. Filters accept e.g. 2024-01-01T00:00:00Z; responses are UTC with microsecond precision, e.g. 2024-06-01T09:00:00.363058Z.

IRI

An Internationalized Resource Identifier (RFC 3987 — a URI superset), e.g. http://adlnet.gov/expapi/verbs/completed.

MIME type

An RFC 6838 media type — type/subtype, e.g. application/json, text/plain.

Query object

Both the data API (as query-string parameters) and the internal query layer (as a JSON object) share the same query structure. Fields (all optional):

Field	Shape	Purpose
filters	object {column: value}, or an array of such objects	Match conditions (the accepted content differs per API).
sort	array of strings — "col" asc, "-col" desc, "rel.col" for a relation	Ordering, e.g. ["-stored"].
limit	integer	Max rows (default 100).
skip	integer	Offset.
after / before	object {column: value} (a single column)	Keyset cursor.
distinct	array of column names	Distinct values of these columns.
relations / accessors	arrays of names	Eager-load relations / append computed attributes (rarely needed).
options	object	Behaviour toggles.

Pagination. The result carries no cursor / next-link — the caller builds the next request. Page by offset (skip + limit) or keyset (sort, then pass the last row's value as after / before).