API reference
Empress Behavioral Substrate — Tenant API
10 endpoints — the sold surface, nothing aspirational. This page is generated at build time from the live OpenAPI spec (v1.0.0, rendered 2026-08-11), so it cannot drift from production.
Auth: every request carries
Authorization: Bearer emp_<slug>_… — your tenant key.
POST
/statements Emit a statement (immutable ledger; quota-enforced per tier)
Request body — Statement
| Property | Type | Required | Description |
|---|---|---|---|
actor | object | yes | xAPI Agent; account.name carries your platform identity |
verb | object | yes | |
object | object | yes | Activity; id convention https://empress.eco/objects/<publicId> |
result | object | no | |
context | object | no | |
timestamp | string (date-time) | no |
GET
/statements Read your tenant's recent statements (tenant-isolated)
| Parameter | In | Required | Description |
|---|---|---|---|
agent | query | no | Plain actor id (convenience) or spec IFI JSON |
activity | query | no | |
verb | query | no | |
since | query | no | |
until | query | no | |
limit | query | no |
GET
/export Export your entire ledger (NDJSON, cursor-paged; your data is portable by construction)
| Parameter | In | Required | Description |
|---|---|---|---|
since | query | no | Cursor from the previous page's X-Next-Since header |
limit | query | no |
POST
/analytics/trending Population play-counts over a window (test traffic excluded)
POST
/analytics/rerank Per-actor personalized ordering over your candidates
Request body — RerankRequest
| Property | Type | Required | Description |
|---|---|---|---|
actorId | string | yes | |
candidates | object[] | yes |
Response 200 — RerankResult
| Property | Type | Required | Description |
|---|---|---|---|
signal | boolean | no | false = no meaningful history; use your default order |
order | string[] | no | |
scores | object | no |
GET
/analytics/actor/{actorId}/stats An actor's aggregate stats (sessions, scores, skill profile)
| Parameter | In | Required | Description |
|---|---|---|---|
actorId | path | yes |
GET
/analytics/difficulty/{objectId} Population-derived difficulty for an object
| Parameter | In | Required | Description |
|---|---|---|---|
objectId | path | yes |
GET
/analytics/summary Tenant activity summary
GET
/belief/{actorId} Full FSRS belief map for an actor (spaced-repetition state per concept)
| Parameter | In | Required | Description |
|---|---|---|---|
actorId | path | yes |
GET
/belief/{actorId}/recommended What this actor should engage next (due reviews / ready-to-learn / at-boundary)
| Parameter | In | Required | Description |
|---|---|---|---|
actorId | path | yes | |
strategy | query | no |
Component schemas
Schemas
The reusable object shapes referenced above — from the same live spec, one level deep; nested references link back to their own definition.
SCHEMA
Statement | Property | Type | Required | Description |
|---|---|---|---|
actor | object | yes | xAPI Agent; account.name carries your platform identity |
verb | object | yes | |
object | object | yes | Activity; id convention https://empress.eco/objects/<publicId> |
result | object | no | |
context | object | no | |
timestamp | string (date-time) | no |
SCHEMA
RerankRequest | Property | Type | Required | Description |
|---|---|---|---|
actorId | string | yes | |
candidates | object[] | yes |
SCHEMA
RerankResult | Property | Type | Required | Description |
|---|---|---|---|
signal | boolean | no | false = no meaningful history; use your default order |
order | string[] | no | |
scores | object | no |