The resident’s world.
Identity and canon. World state and time. Plans, possessions and simulated money. Social encounters, memories and causal history.
SKHERIA / DEVELOPERS
Build the experience.
Connect the world.
A persistent life behind every interaction. Work with resident state, events and intentions through one versioned contract.
Read the API reference RESIDENT ENGINE V118 LOCAL HTTP OPERATIONSCONTRACT 1.0.0
01 / THE CONNECTION
World context.
Your interface.
Read state when your app needs context. Request bounded catch-up for elapsed time. Submit supported actions. Render only the facts your application is permitted to receive.
The current API runs locally at http://127.0.0.1:8787. There is no hosted signup or public API credential.
- 01
Provision access
A trusted operator creates an app credential bound to a resident grant and an opaque relation.
- 02
Resolve the timeline
Call
/simulatewhen catch-up is needed. A state read alone does not advance the world. - 03
Build from committed facts
Use filtered state, events and plans in your experience. Your app keeps its accounts, private chats and notification policy.
02 / WORK WITH THE WORLD
A small request.
A life behind it.
These are the implemented request shapes. Set SKHERIA_URL to the local origin, and use your provisioned resident ID and backend token.
cURL
curl "$SKHERIA_URL/v1/residents/$RESIDENT_ID/state" \
-H "Authorization: Bearer $SKHERIA_TOKEN"Read the resident’s current state. Optional wallet, event, plan and inventory fields require their own scopes.
curl -X POST "$SKHERIA_URL/v1/residents/$RESIDENT_ID/simulate" \
-H "Authorization: Bearer $SKHERIA_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: catch-up-001" \
-d '{"until":"2026-09-26T09:12:00.000Z","reason":"app_open"}'Advance to an allowed time, no later than the trusted server clock. A 202 response means more work remains: continue with a new idempotency key.
curl "$SKHERIA_URL/v1/residents/$RESIDENT_ID/events?limit=20" \
-H "Authorization: Bearer $SKHERIA_TOKEN"Retrieve permission-filtered events. Pagination uses opaque cursors; private causes and another relation’s data remain excluded.
Authenticated by default
Bearer token + scopes + active grant + field visibility. Keep tokens on your backend.
Safe to retry
Every POST requires an Idempotency-Key. Authorization is checked again before replay.
Explicit progress
Simulation returns 200 when complete or 202 when pending. Continue pending work with a new key.
03 / THE IMPLEMENTED CONTRACT
One interface.
Connected systems.
Routes and required primary scopes below come from the repository’s OpenAPI artifact. Some operations and optional fields require additional scopes, as detailed in the full contract.
POST/v1/residents
Register the fixed reference profile with a world-bound provisioner.
PRIMARY SCOPE / residents:create
Requires a current credential and the appropriate binding. Read request, response and permission details in the full contract.
GET/v1/residents/{id}
Read a minimal resident profile.
PRIMARY SCOPE / resident:read
Requires a current credential and the appropriate binding. Read request, response and permission details in the full contract.
GET/v1/residents/{id}/state
Read consistent, permission-filtered resident state.
PRIMARY SCOPE / resident:read
Requires a current credential and the appropriate binding. Read request, response and permission details in the full contract.
GET/v1/residents/{id}/events
Page through approved world facts.
PRIMARY SCOPE / events:read
Requires a current credential and the appropriate binding. Read request, response and permission details in the full contract.
POST/v1/residents/{id}/simulate
Process bounded catch-up to an allowed time.
PRIMARY SCOPE / simulation:advance
Requires a current credential and the appropriate binding. Read request, response and permission details in the full contract.
POST/v1/residents/{id}/actions
Submit GIFT_SKR, CREATE_PURCHASE_PLAN or CARRY_ITEM.
PRIMARY SCOPE / actions:write
Requires a current credential and the appropriate binding. Read request, response and permission details in the full contract.
GET/v1/residents/{id}/plans
Read plans belonging to the credential’s relation.
PRIMARY SCOPE / plans:read
Requires a current credential and the appropriate binding. Read request, response and permission details in the full contract.
GET/v1/plans/{id}
Read an accessible plan and available alternatives.
PRIMARY SCOPE / plans:read
Requires a current credential and the appropriate binding. Read request, response and permission details in the full contract.
POST/v1/plans/{id}/respond
Choose BUY_ALTERNATIVE or CANCEL with a version check.
PRIMARY SCOPE / plans:respond
Requires a current credential and the appropriate binding. Read request, response and permission details in the full contract.
GET/v1/residents/{id}/wallet
Read SKR balance, held funds and available funds.
PRIMARY SCOPE / wallet:read
Requires a current credential and the appropriate binding. Read request, response and permission details in the full contract.
GET/v1/residents/{id}/transactions
Read filtered financial records.
PRIMARY SCOPE / wallet:read
Requires a current credential and the appropriate binding. Read request, response and permission details in the full contract.
GET/v1/residents/{id}/financial-summary
Read ledger-derived totals for a required from/to period.
PRIMARY SCOPE / wallet:read
Requires a current credential and the appropriate binding. Read request, response and permission details in the full contract.
GET/v1/residents/{id}/inventory
Read owned items and their approved properties.
PRIMARY SCOPE / inventory:read
Requires a current credential and the appropriate binding. Read request, response and permission details in the full contract.
GET/v1/residents/{id}/contact-intents
Read eligible structured contact intentions.
PRIMARY SCOPE / contact:read
Requires a current credential and the appropriate binding. Read request, response and permission details in the full contract.
POST/v1/contact-intents/{id}/ack
Record delivered or suppressed handling.
PRIMARY SCOPE / contact:ack
Requires a current credential and the appropriate binding. Read request, response and permission details in the full contract.
POST/v1/external-relations/{id}/signals
Set typed, expiring signals for the bound relation.
PRIMARY SCOPE / relation:signal
Requires a current credential and the appropriate binding. Read request, response and permission details in the full contract.
GET/v1/outbox
Poll currently authorized, unacknowledged deliveries.
PRIMARY SCOPE / outbox:read
Requires a current credential and the appropriate binding. Read request, response and permission details in the full contract.
POST/v1/outbox/{id}/ack
Persist a delivery receipt.
PRIMARY SCOPE / outbox:ack
Requires a current credential and the appropriate binding. Read request, response and permission details in the full contract.
OpenAPI currently specifies request schemas and object response envelopes. Detailed response fields and permission rules are documented in the full contract.
04 / CLEAR OWNERSHIP
One shared world.
Careful boundaries.
The human experience.
Human accounts and private conversations. Intimate preferences. Relationship stages, consent and notification delivery.
A contact intent is context for your application—not permission to notify someone. SKR is closed-loop virtual currency; real payments and redemption are not implemented.
05 / DEVELOPMENT STATUS
Built locally.
Deliberately scoped.
The Resident Engine and local API are implemented and locally tested. Production access and client integration remain separate steps.
- Resident state, time & events
- Implemented locally
- Plans, economy & inventory
- Implemented locally
- App authorization & privacy
- Implemented locally
- Transactional outbox polling
- Implemented locally
- Hosted API & remote webhooks
- Not available
- Public character creation & real payments
- Not available