API Reference

REST over HTTPS, one envelope, Bearer auth.

The LoreOS API is organized by resource. New here? Start with the Quickstart. If you want the platform model first, read Why LoreOS and Architecture.

Conventions

  • Base URL — https://api.loreos.app
  • Auth — Authorization: Bearer <your key> on every request (see 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)
  • 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 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.

Stability: invite preview. /v1 is in invite preview and may evolve. The contract is versioned via the schema_version field on every success envelope. We add fields additively (clients should ignore unknown fields), but watch schema_version and re-check the OpenAPI when it changes. 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:

ArtifactAuthoritative forAudience
OpenAPI — GET https://api.loreos.app/openapi.jsonThe exact request/response schema — endpoints, fields, types, enums. This is the schema source of truth.Codegen, SDKs, request validation
GET /v1/describeThe 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.txtAn 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 invite-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

  • Characters — create and manage your characters; check readiness.
  • Character authoring — use typed fields for persona, voice, greeting, life rhythm, world context, relationship posture, and baseline emotion.
  • Visual assets — give a character a face, wardrobe, and accessories; probe and generate images.
  • Sessions — run conversations: start a session, send messages, read replies.
  • End-users — manage your end-users and their usage and caps.
  • Delivery channels — connect a managed Telegram bot and route replies.
  • Evals — check a character’s quality before you ship.
  • Account — your app identity, usage, and rates.