Quickstart

Every command on this page runs against the production API. There is no sandbox with different behavior — what you test is what you ship against.

1. Get a key

Empress is in private beta; keys are provisioned by hand. Email [email protected] 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.

---

Go deeper: Concepts · Tenant integration · Verbs · Identity · Export · API reference · SDK reference