Quickstart

1. Get a key

Empress is in private beta; keys are provisioned by hand. Email hello@empress.eco with a line about what you want to observe. Keys look like emp_<your-slug>_… and scope every request to your tenant.

2. Emit your first statement

A statement is a fact: actor did verb to object, in xAPI shape. Empress accepts any verb — structure is validated, vocabulary is yours.

curl -X POST https://empress-api.jdnyzio.workers.dev/statements \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "actor": { "account": { "name": "agent-7", "homePage": "https://empress.eco" } },
    "verb": { "id": "https://empress.eco/verbs/completed" },
    "object": { "id": "https://your-app.example/tasks/42" },
    "result": { "success": true }
  }'

3. Read it back

curl "https://empress-api.jdnyzio.workers.dev/statements" \
  -H "Authorization: Bearer YOUR_API_KEY"

You only ever see your tenant's statements — isolation is enforced at the substrate and machine-verified in both directions by a repeatable production test.

4. Take everything home

curl "https://empress-api.jdnyzio.workers.dev/export" \
  -H "Authorization: Bearer YOUR_API_KEY" > ledger.ndjson

Cursor-paged NDJSON of your whole ledger. This endpoint is the no-lock-in guarantee made concrete.

Concepts, briefly

The ledger is immutable

Statements are never rewritten or deleted. Interpretation happens at query time.

Any-verb

Unknown verbs are stored, not rejected. Meaning lives in analytics, not ingestion gates.

Derived truths are endpoints

Difficulty, trending, actor stats, and belief state are computed by Empress from statements — you read them from /analytics/* and /belief/* instead of rebuilding them.

Belief

An FSRS-based memory model per actor and concept: GET /belief/:actorId tells you what an actor knows and what's due.

Full surface: API reference · machine-readable: openapi.json