> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.loreos.app/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.loreos.app/_mcp/server.

# API Reference

The LoreOS API is organized by resource. New here? Start with the
**[Quickstart](https://docs.loreos.app/getting-started/quickstart)**. If you want the platform model first, read
**[Why LoreOS](https://docs.loreos.app/getting-started/why-lore-os)** and **[Architecture](https://docs.loreos.app/platform/architecture)**.

**Conventions**

* **Base URL** — `https://api.loreos.app`
* **Auth** — `Authorization: Bearer <your key>` on every request
  (see [Authentication](https://docs.loreos.app/getting-started/authentication))
* **Envelope** — responses are `{ schema_version, data, next_actions }`;
  errors are `{ detail: { code, message, fix } }` (read `body.detail.code`)
* **Async replies** — send a message, then read the reply from the session's events
  (see [Core concepts](https://docs.loreos.app/getting-started/core-concepts))
* **Errors** — `{ detail: { code, message, fix } }`; which codes you'll hit, whether each
  is retryable, and the in-product fallback are in the
  [Errors and retries](https://docs.loreos.app/guides/errors-and-retries) catalog

## Public surface: only `/v1/*`

`/v1/*` is the **only** public, supported surface. Build your app against it exclusively.

The LoreOS server also hosts internal surfaces — most visibly `/admin/*` (the internal
operator cockpit) and `/cbt/*` (an internal user-facing chat surface). **These are not for
tenant apps.** They are unversioned, unscoped to your app, may change or disappear without
notice, and are not covered by this documentation. You may see them if you dump the raw
`/openapi.json` (it describes the whole server), but the published API Reference and SDKs
deliberately expose only `/v1`. If you find yourself reaching for an `/admin` or `/cbt`
route, the capability you want is either already on `/v1` or is not yet a supported
product surface — ask us rather than calling an internal route.

> **Warning**
>
> **Stability: preview.** `/v1` is versioned via the `schema_version` field on every
> success envelope and may evolve during preview. We add fields additively (clients
> should ignore unknown fields), but watch `schema_version` and re-check the OpenAPI
> when it changes. Account-plane setup routes for coding agents are documented in
> [Self-serve access](https://docs.loreos.app/getting-started/self-serve-access) and
> `GET /v1/llms.txt`, but are intentionally kept out of the generated runtime API
> Reference/SDK for now. Treat `lat_...` account tokens and app runtime keys as
> different credentials. Do not depend on `/admin` or `/cbt` behavior at all.

## Source of truth: which artifact is authoritative for what

LoreOS publishes the contract in a few forms; each is authoritative for a different thing.
When they appear to disagree, prefer them in this order:

| Artifact                                                   | Authoritative for                                                                                                                             | Audience                                    |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| **OpenAPI** — `GET https://api.loreos.app/v1/openapi.json` | The exact public **/v1** request/response schema — endpoints, fields, types, enums. This is the schema source of truth for tenant apps.       | Codegen, SDKs, request validation           |
| **`GET /v1/describe`**                                     | The **product / capability map** — what resources exist, how they fit together, the integration flow, and the authoring contract at a glance. | A coding agent learning the surface         |
| **`GET /v1/llms.txt`**                                     | An agent **quick-start guide** — the 3-calls-plus-poll path in plain text, designed to be the first context you hand an LLM.                  | An agent making its first calls             |
| **`docs.loreos.app`** (this site)                          | **Narrative + guides** — concepts, recipes, tutorials, and the reasoning behind the contract.                                                 | Humans and agents reading for understanding |

Because the preview contract may change (tracked by `schema_version`), **pin your
generated client to the OpenAPI schema** and regenerate when `schema_version` moves, rather
than hand-coding request shapes from the narrative docs.

**Sections**

* **Sandbox and reference** — issue a capped demo key and fetch the public OpenAPI
  schema.
* **Characters** — create and manage your characters; check readiness.
* **Imports** — stage one reviewable character bundle for either a fresh authored
  character or a transcript migration, then commit it into runtime state.
* **Character World** — upload or validate relationship graphs, manage NPCs, publish
  graph versions, author storylines, and steer daily arc influences.
* **Research and evidence** — submit evidence, run research, review candidates, and commit
  public-safe state updates.
* **Visual assets** — give a character a face, wardrobe, and accessories; probe and
  generate images.
* **Sessions** — run conversations: start a session, send messages, read replies.
* **Relationship evidence** — read public-safe snapshots, memories, open loops, life feed,
  identity continuity, reach-out reasons, proactive preferences, Telegram binding, and
  opt-in relationship scores.
* **End-users** — list your app's end-users, read one user, inspect that user's sessions,
  and manage usage/caps by `external_user_ref`.
* **Delivery channels** — connect Telegram. Use the BYO bot-token path when you
  already have one character bot. Use the official Managed Bots path when your
  product should create one Telegram contact per user-character relationship.
* **Evals** — check a character's quality before you ship.
* **Observability** — inspect redacted health, timeline, trace, delivery, runs, metrics,
  and rollback/version surfaces for app-owned resources.
* **Account** — your app identity, usage, and rates.

Character authoring itself is a guide-level concept, not a separate API Reference section:
use typed fields on `POST /v1/characters` and `PATCH /v1/characters/{slug}` for visible
bio, interests, voice, greeting, life rhythm, world context, relationship posture, and
baseline emotion.