API¶

This section documents every HTTP endpoint the daemon serves. The dashboard is a client of this same API — anything you do by clicking, you can do with a request. A person can drive it with curl; a persona can drive it from her own desktop.

Base URL¶

http://localhost:5000

The daemon binds 5000 by default. If 5000 is already taken on your machine, it picks the next free port and prints which one on startup (Port 5000 was in use; using 5001 instead.). The port can also be set with the WEB_PORT environment variable or the --port flag on eternego daemon. Confirm the live port from the line printed at startup, or from the browser tab the app opens.

There is no authentication on localhost. The API is bound to the loopback interface and is meant to be reached only from the same machine. Do not expose the port to a network you don't trust.

The persona id¶

Every persona has a stable UUID — her id. It is assigned once at creation and never changes. It is the path parameter for nearly every endpoint:

/api/persona/{persona_id}/start
/api/persona/{persona_id}/update
/api/persona/{persona_id}/delete

List every id with GET /api/personas.

A real id looks like 6c17c83c-3158-450d-8e43-0e7efea717c1. The examples throughout this section use real (test) persona ids with secrets masked.

Two kinds of route¶

Whether an endpoint needs the persona to be running (served by a live agent) or only needs her files on disk determines what happens when she isn't running:

Kind	Works when she's stopped?	What it touches	Examples
Config / list	Yes	Her persisted files on disk	`GET /api/personas`, `POST .../update`, `POST .../delete`
Live-agent	No — returns 409	Her running agent in memory	`POST .../sleep`, `POST .../read`, `POST .../hear`, `POST .../attach`, `POST .../feed`, `POST .../pair`

The /api/... live-agent routes resolve the agent through manager.find(persona_id). If she isn't being served, they reject the request:

HTTP 409
{ "detail": "Persona is not active." }

Bring her up first with POST /api/persona/{persona_id}/start. The lifecycle routes themselves (start, stop, restart) and config routes do not require a running agent.

Error shape¶

Every error is a JSON object with a single detail key and the matching HTTP status code — the FastAPI convention:

{ "detail": "Persona not found." }

Status	Meaning
400	Bad request — validation failed downstream, or a model/channel couldn't be prepared. `detail` carries the reason.
404	No persona with that id (config routes), or that persona/model isn't running (where a live agent is required by id lookup).
409	The persona exists but isn't being served — a live-agent route was called while she's stopped.
415	Unsupported media type — an attached file's extension has no perception capability.
422	The request body failed Pydantic validation (missing or wrong-typed field). FastAPI's standard validation error; `detail` is a list of field errors.
500	Unhandled server error. `detail` is `"<ErrorType>: <message>"`.

What's where¶

Personas — GET /api/personas (every field of the persona view) and GET /api/config/providers.
Lifecycle — start, stop, restart, sleep, update status/organs, delete.
Create and migrate — bring a new persona into being, or restore one from a diary.
Perception — send her text, voice, and files.
Knowledge, Channels, WebSockets — the rest of the surface.
OpenAPI spec — the machine-readable contract.

Vocabulary — persona, organ, channel, the three status values.
For agents — the fast path if you're an agent operating her over HTTP.
The panel — every screen, with the API call behind each control.