Build with a coding agent

LoreOS docs are designed to be read by both humans and coding agents. If you are using an agent, give it the resources below in this order.

API key status

For local testing, issue a short-lived sandbox key directly from the API:

$
export LOREOS_KEY="$(curl -sS -X POST https://api.loreos.app/v1/demo/sandbox-key \
>
  | jq -r '.data.api_key')"
$
export LOREOS_BASE="https://api.loreos.app"

Demo keys are intentionally narrow: three characters, five sessions, sixty messages, 1,200 input characters, no image generation, no managed Telegram, no webhook delivery, no budget changes, no app creation, and no extra API keys. They are for copy-paste testing only.

LoreOS invite keys are still required for persistent apps, production deployments, and surfaces disabled in the demo sandbox. Keep every LOREOS_KEY server-side.

Initial demo issuance does not require a browser challenge, so terminal coding agents can call it directly. If abuse appears, LoreOS may temporarily pause issuance or add a challenge to the public route.

Agent resource order

1. Integration guide — GET https://api.loreos.app/v1/llms.txt
   • Short, live API usage guide.
   • Best first context for an agent that needs to make calls.
2. Full docs context — https://docs.loreos.app/llms-full.txt
   • Markdown corpus for the docs site.
   • Best when the agent needs product and architecture context.
3. API discovery — https://docs.loreos.app/.well-known/api-catalog
   • Machine-readable API discovery.
4. OpenAPI — https://api.loreos.app/v1/openapi.json
   • Public /v1-only schema source of truth (point your SDK generator here). The raw https://api.loreos.app/openapi.json is the whole server (includes internal admin/cbt) — do not generate against it.
5. Page markdown — append .md to any docs page URL.
   • Use this when the agent is focused on one topic.

Golden path

Ask the agent to do this first:

Use LoreOS to create one character, start one session, send one message,
poll session events, and print the first character reply. Use only the /v1 API.

The minimal flow is:

POST /v1/characters
POST /v1/sessions
POST /v1/sessions/{session_id}/messages
GET  /v1/sessions/{session_id}/events?since={cursor}

For docs validation, run this in a clean workspace where the agent cannot inspect the LoreOS repository. The agent should be able to build a tiny server-side app from the public docs, a self-issued demo key, and the machine-readable resources listed above.

The reply is asynchronous. POST /messages returns accepted and a cursor, not the reply text. Poll events until you see:

1
{
2
  "type": "message.created",
3
  "role": "character",
4
  "payload": {
5
    "text": "...",
6
    "bubbles": ["..."]
7
  }
8
}

Reliability contract

LoreOS APIs are structured so agents can call, recover, and continue.

• Every success response is wrapped as { "schema_version", "data", "next_actions" }.
• Errors use { "detail": { "code", "message", "fix" } }.
• next_actions tells the agent what to call next.
• Retry-safe sends: pass Idempotency-Key: <unique-per-message> on POST /messages. A same-key re-call (common on serverless/Vercel) returns the original cursor + { "idempotent_replay": true } instead of creating a duplicate turn/reply. Dedupe event delivery by the monotonic cursor.
• Long-running work is exposed through session events, runs, and delivery state.
• Usage caps return 402 budget_exceeded before expensive model work starts.
• Unknown or cross-app resources return 404, never tenant-identifying details.
• Clients should ignore unknown additive fields.

Common mistakes

1. Expecting a reply from POST /messages. The reply arrives later on the event log.
2. Reading top-level response fields. Use response.data, not response.session_id or response.cursor.
3. Dropping the cursor. Save data.cursor, then poll with since=<cursor>.
4. Treating external_user_ref as LoreOS auth. It is your own opaque end-user id. Your app owns end-user auth.
5. Putting LOREOS_KEY in the browser. Keep the key server-side. Proxy browser requests through your backend.
6. Testing images before readiness. Upload an identity image and check visual readiness before image probes.
7. Using a demo key as production auth. Demo keys are short-lived and capped. Use account keys for real apps.
8. Assuming a failed sandbox-key call means the API is unavailable. 429 means the issuance rate limit was reached. 503 demo_sandbox_disabled means public issuance is temporarily paused; invite keys still work.

What a successful agent integration proves

A clean agent integration should prove:

• the app keeps LOREOS_KEY server-side;
• the app creates or reuses a character;
• the app starts a session for an external_user_ref;
• the app sends a user message;
• the app polls session events with the returned cursor;
• the app displays a message.created event with role: "character".

If an agent cannot reach that result from the docs alone, the docs need another pass.

When to use LoreOS

Use LoreOS when you need persistent AI characters with memory, relationships, world continuity, daily-life context, visual identity, delivery, metering, and observability.

Do not use LoreOS if you only need a single stateless chatbot response and want to own all memory, delivery, and usage infrastructure yourself.