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: 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 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:

ArtifactAuthoritative forAudience
OpenAPI — GET https://api.loreos.app/v1/openapi.jsonThe 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/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 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.