Tenant integration

Every tenant integrates the same way: an API key, xAPI statements over HTTPS, and reads that are isolated to you by construction. This page is the whole contract.

Keys and auth

Keys look like emp_<your-slug>_… and travel as Authorization: Bearer on every request. The key IS your tenant scope — there is no tenant parameter to get wrong. Keys are provisioned by hand during the private beta: [email protected].

The emission contract

Send well-formed xAPI: an actor (use account with a stable name — never an email you’d regret indexing), a verb (any URI; your vocabulary is welcome), an object (a stable URI for the thing acted on), and optionally result, context, and extensions. Empress validates the shape, stores the statement forever, and never rejects a verb it hasn’t seen.

POST https://empress-api.jdnyzio.workers.dev/statements
Authorization: Bearer emp_yourslug_...
Content-Type: application/json

{
  "actor":  { "account": { "name": "user-42", "homePage": "https://your-app.example" } },
  "verb":   { "id": "https://your-app.example/verbs/completed" },
  "object": { "id": "https://your-app.example/tasks/17" },
  "result": { "success": true, "score": { "raw": 87 } }
}

Identity advice

Pick one canonical ID per actor and use it everywhere — the ledger is permanent, so identity drift is the one mistake that compounds. If your users can act before signing up, give devices stable anonymous IDs and keep an alias map on your side; read the union when you query. Full detail: Identity.

Quotas

Finite tiers enforce a monthly statement quota at ingestion: exceeding it returns HTTP 429 — nothing is silently dropped, and reads and exports keep working. Enterprise tenants are structurally unlimited.

Taking your data home

GET https://empress-api.jdnyzio.workers.dev/export
Authorization: Bearer emp_yourslug_...
# → your entire ledger, cursor-paged NDJSON

Export is total and always available. It’s also the honest answer to most compliance questions: hand your auditors the raw ledger in an open format. More: Export & evidence.

The computed layer

Once statements flow, the analytics endpoints work with zero configuration: /analytics/trending, /analytics/difficulty/:objectId, /analytics/actor/:actorId/stats, /analytics/rerank, and the belief surface at /belief/:actorId. Full shapes: the API reference, generated from the live spec.

---

Next: Quickstart · Concepts · openapi.json