Skip to content

HTTP API ​

Every somora client talks to the same server over HTTP, Server-Sent Events and WebSockets: the terminal client, the web client, the mobile app and anything you build yourself. This page lists every route and every stream event, so you can write your own client from it.

What you get ​

  • One surface for all clients. What the shipped clients can do, your client can do: there are no private routes.
  • Send and follow. Post a message, then read the reply as it is written, tool call by tool call.
  • Everything about a session: history, queue, model, thinking level, project, unread state.
  • The machinery behind the agents: memory search, wiki, dream phases, triggers, browser, media, voice.
  • One key. Send the server's key with every request. "Access model" says how.

First request ​

List the agents, open the stream of one session, then send a message. The reply arrives on the stream.

bash
BASE=https://<your-host>:18737
KEY=$(somora key)        # on the server; elsewhere paste the key

# 1. Who is there?
curl -H "Authorization: Bearer $KEY" $BASE/agents

# 2. Follow the session (keep this running)
curl -H "Authorization: Bearer $KEY" -N "$BASE/chat/stream?agent=<your-agent>&session=main" &

# 3. Send a message
curl -H "Authorization: Bearer $KEY" -X POST $BASE/chat/send \
     -H 'Content-Type: application/json' \
     -d '{"agent":"<your-agent>","session":"main","text":"What is on today?"}'
# → 202 { "ok": true, "turnId": "…" }

On the stream you now see user_message, agent with phase: "start", chat deltas, perhaps tool events, a chat event with state: "final" and agent with phase: "end".

A fuller client usually does this:

WhenCalls
On startGET /agents, GET /sessions, GET /version, one GET /activity/stream
Per open chat windowGET /chat/history?limit=200, one GET /chat/stream
On inputPOST /attachments per file, then POST /chat/send
On StopPOST /chat/abort
To show the queueGET /agents/:agent/sessions/:session/work

If you do not want to handle a stream, POST /chat/send-sync waits for the turn and returns the reply in the response.

Conventions ​

TopicRule
Base URLhttps://<your-host>.<your-tailnet>.ts.net:18737 with HTTPS set up, else http://127.0.0.1:18737. The web client is under /web/, the mobile app under /mobile/.
BodiesJSON in, JSON out (Content-Type: application/json), unless a route says otherwise. Uploads are raw bytes or multipart/form-data, as noted per route.
ErrorsA non-2xx response carries { "error": "<message>" }. The message is written for a person. Some routes add fields, noted per route.
Unknown agent or session404 on every route that takes one, except POST /chat/abort.
Agent being renamed409 with error: "agent '<name>' is being renamed — try again in a moment" on every route under /agents/:agent/ except reads (GET), and on POST /chat/send and POST /chat/send-sync, for the old and the new name. Retry in a moment.
TimesEpoch milliseconds as numbers, or ISO 8601 strings. The examples show which.
StreamsServer-Sent Events with named events. data is always JSON.

Session references ​

A session id has the form <YYYYMMDD>-<HHMMSS>_<slug>. Every agent also has the session main, which always exists. Where a route takes :session or a session field, it accepts a reference and resolves it in this order:

  1. main
  2. an exact id
  3. a session stored under exactly that name
  4. the newest session with that slug

An unknown reference is refused. It is never resolved to a similar name. Responses carry the resolved id.

Polling ​

Routes that report live state only read memory and are cheap. The shipped clients poll the dream loop every 2 seconds, the dream phases every 30 seconds and the session list every 60 seconds. Prefer the two streams where they cover what you need.

Access model ​

The server has one key, in ~/.somora/server.key. Every request needs it, also from the same machine and over Tailscale. There are no user accounts and no per-route permissions: the key opens everything.

ClientHow it sends the key
A programAuthorization: Bearer <key>, or X-Somora-Key: <key> where a tool cannot set Authorization.
A browserA cookie from POST /auth/login. It rides along on every request, stream and WebSocket.
A script an agent writes-H "Authorization: Bearer $(somora key)". The key is not in the shell's environment, so env does not show it, unless the command was started with inherit_agent_env: true.

somora key prints the key on the server. Never put it in a URL query: it would end up in logs and histories.

Without the key, or with a wrong one, the server answers 401:

json
{ "error": "somora needs its key. Programs: send \"Authorization: Bearer <key>\"; on the server \"somora key\" prints it …", "kind": "auth" }

Ten wrong keys from one address within five minutes block that address for a minute (429). Requests from the server's own machine are not blocked. A request without any key does not count.

Open without the key: GET /healthz, the /auth/* routes below, the files of the web and mobile clients under /web/ and /mobile/, which hold no data, and the A2A paths (Agent Cards, /a2a/files/<token>, POST /a2a/agents/:agent), which check peer tokens themselves.

With server.auth: off in config.yaml the server asks for no key. Then access is decided by the network alone.

A browser request that another website makes in the background is refused with 403 and a plain-text body, not JSON: refused: <reason>. …. A browser that reaches somora under a name of its own needs that name in server.allowedHosts. Programs that are not browsers are never checked. The security page explains the rule.

Warning

Never expose the port to the public internet, with or without the key. The key protects a private network, it is not built to face the internet.

The API can do what an agent can do: write memory, switch models, start dream runs, run tools. The security page describes the trust boundary and how to check your setup.

GET /auth/status ​

Open without the key. Says whether the key is switched on and whether this request carries it.

json
{ "auth": "on", "signedIn": false }

With server.auth: off, signedIn is always true.

POST /auth/login ​

Open without the key. Signs a browser in. Body { "key": "somora_…" }.

StatusBody
200{ "ok": true }, plus the cookie somora_key (HttpOnly, SameSite=Strict, Secure over HTTPS, one year).
401{ "error": "wrong key — …" }
429Too many wrong keys from this address.

The cookie holds a value derived from the key, not the key. A new key (somora key rotate) signs every browser out.

POST /auth/logout ​

Open without the key. Removes the cookie. Answers { "ok": true }.

Stability ​

  • The version from GET /version is calendar based and valid semver: 2026.1001.2 is the second build of 1 October 2026.
  • The routes on this page are used by the shipped clients and are kept stable.
  • A route marked experimental may change shape in any build. Pin a somora version if your client depends on one.
  • New fields may appear in any response and any event. Ignore what you do not know.

Core ​

GET /version ​

The running version and what the daily update check found.

json
{ "version": "2026.1001.2",
  "update": { "latestVersion": "2026.1005.1", "available": true, "note": "update Node first" } }
FieldMeaning
versionThe running build.
updatenull until the first check has answered, or when the check is switched off.
update.latestVersionThe newest published version.
update.availabletrue when latestVersion is newer than version.
update.noteOptional hint that comes with the release.

GET /inbox ​

What the web client's inbox shows: a newer version, somora.ai's note, and conditions that need a person (a broken config.yaml, an expired login, the certificate, failing dream runs, a tool server or model gone for a day, a Sentinel check that stopped or used up its wakes for the day, a subagents.tools.deny entry that names no tool).

json
{ "entries": [ { "key": "config", "kind": "config", "level": "important",
    "title": "config.yaml has a mistake", "text": "…",
    "firstSeen": 1791821926940, "lastSeen": 1791822226940, "count": 1 } ],
  "unread": 1, "muted": [] }
FieldMeaning
keyStable per thing, e.g. update:<version>, news:<hash>, config, login:claude-cli, login:openai-compatible:<provider>, login:mcp:<server>, tls, rem:<agent>, deep:<agent>/<slug>, lucid, mcp:<server>, model:<provider/id>, sentinel:<triggerId>, config:subagents-deny, config:rem-model (agents that dream without a REM model), dream:switch (the one-time rewrite to the dreams switch).
kindupdate, news, config, login, tls, dream, mcp, model, sentinel, a2a.
levelinfo, warning, important.
title, text, url?Plain text. url is https:// only.
firstSeen, lastSeen, countEpoch ms; count counts events, a checked state stays 1.
readAt?, resolvedAt?, muted?muted is until-resolved or forever. Resolved entries stay a day.

POST /inbox/read ​

Body { "keys": [...] }, or {} for all. Answers { ok, unread }.

POST /inbox/mute · POST /inbox/unmute ​

Body { "key": "…", "mode": "until-resolved" | "forever" } for mute, { "key": "…" } for unmute. mode defaults to until-resolved. Both answer { ok, unread }, or 404 for an unknown key.

GET /themes ​

The themes for the web client: the ones that come with somora and the ones in ~/.somora/themes/. Each folder is read and checked on every request, see Themes for the format.

json
{ "themes": [ { "id": "ocean", "name": "Ocean", "source": "bundled", "versions": {
      "dark": { "tokens": { "--accent": "#4fb3e6", "--accent-rgb": "79, 179, 230", "--on-accent": "#0a1010" },
                "grid": false, "wallpaperUrl": "/themes/ocean/dark/wallpaper?v=1791821926940" },
      "light": { "tokens": { "--accent": "#1c74b8", "--accent-rgb": "28, 116, 184", "--on-accent": "#ffffff" },
                 "grid": true, "wallpaperUrl": null } } } ],
  "invalid": [ { "id": "draft", "error": "unknown colour token \"--font\"" } ] }
FieldMeaning
idThe folder name.
sourcebundled for a theme that comes with somora, own for one in ~/.somora/themes/. A folder of yours with the same name replaces the bundled theme.
versionsdark, light or both, as the theme's theme.json has them.
tokensThe version's colours plus the ones derived from them (--accent-rgb, --bg-0-rgb, --bg-1-rgb, --on-accent).
wallpaperUrlnull without a wallpaper. v changes when the file does.
invalidFolders that are not a valid theme, with the reason and source.

No themes folder answers two empty lists.

GET /themes/:id/:version/wallpaper ​

The wallpaper of a valid theme's dark or light version, as image/png, image/jpeg or image/webp. The file has to lie in the theme's own folder, also after following links, and has to be the image type its name says. A theme folder that is itself a link is not read. 404 for an unknown theme, version or wallpaper, 422 with the reason for an invalid theme.

GET /healthz ​

Liveness probe. Answers the plain text ok with status 200. Use it to wait for the server to come up. Open without the key.

GET /health ​

A snapshot for diagnosing a session that seems stuck: which session is busy, since when, what waits behind it, and when the last event went out. Read-only and cheap.

json
{
  "ok": true,
  "serverPid": 12345,
  "serverBootedAt": 1778756948428,
  "serverUptimeMs": 5142,
  "lockfilePid": 12345,
  "lockfileStartedAt": "2026-05-14T11:09:08.429Z",
  "activeSessions": 1,
  "totalKnownSessions": 3,
  "claudeAuth": { "enabled": true, "userExists": true, "somoraExists": true,
                  "identical": true, "userExpiresAt": 1785503549000,
                  "somoraExpiresAt": 1785503549000,
                  "lastSyncResult": "noop", "lastSyncAt": 1785496349000 },
  "memoryEmbedder": { "state": "ok", "provider": "local", "model": "all-MiniLM-L6-v2",
                      "dim": 384, "error": null, "since": 1785496350120,
                      "attempts": 1, "loadMs": 2373 },
  "sharedIndex": { "state": "ready", "role": "owner",
                   "path": "/home/me/.somora/index/shared.db",
                   "files": 626, "chunks": 1466, "built_by": "sweep" },
  "sessions": [
    {
      "agent": "<your-agent>", "session": "main",
      "busy": true, "activePriority": "user",
      "activeSince": 1778757036447, "activeAgeMs": 1024,
      "activeCallId": null, "activeTurnId": "b5b7a734-…",
      "queueLength": 1, "userWaiting": 0, "agentWaiting": 1,
      "queued": [
        { "id": "3f0c2b1e-…", "kind": "agent",
          "preview": "Can you check whether the build log mentions …",
          "enqueuedAt": 1778757040112, "position": 1 }
      ],
      "lastEngineEventAt": 1778757036900, "lastEngineEventAgoMs": 571,
      "subscriberCount": 2,
      "lastPublishOkAt": 1778757036900, "lastPublishOkAgoMs": 571
    }
  ]
}

Per session:

FieldMeaning
busy, activeSince, activeAgeMsWhether a turn runs, and for how long.
activePriorityuser for a person typing or dictating, agent for everything else. A label only: the queue is first in, first out.
activeTurnIdSet for every running turn, whatever started it. Stop it with POST /chat/abort.
activeCallIdThe call id when the running turn is another agent's question, else null.
queueLength, userWaiting, agentWaitingHow many turns wait, in total and by label.
queuedThe waiters in order: id, origin kind, the first 160 characters as preview, enqueuedAt, position (1 is next). Any id can go to DELETE /chat/queue/:id.
lastEngineEventAt, lastEngineEventAgoMsWhen the engine last produced an event. A value that keeps growing during a chat turn means the turn hangs. The engine watchdog then aborts it (engineWatchdog in the config).
subscriberCountClients connected to this session's stream.
lastPublishOkAt, lastPublishOkAgoMsWhen an event last reached the subscribers. If it grows while subscriberCount is above 0, one client is stuck. The next event removes it after sse.publishTimeoutMs.

Top-level blocks:

BlockMeaning
claudeAuthState of the login shared between ~/.claude and somora's own Claude folder. Expiry times only, never tokens. identical: false with both sides present means they have drifted apart. If that stays, run somora claude status.
memoryEmbedderThe embedding model behind memory search. state is idle, loading, ok or failed. With failed, error says why and every search is keyword only until a retry succeeds.
sharedIndexThe search index over vault and wiki that all agents share. state is opening, building, ready, disabled (no vault configured) or failed with error. built_by is seed:<agent> or sweep. null until the server has opened it.

GET /host-stats ​

CPU load and memory of the machine somora runs on.

json
{
  "cpu": { "loadAvg1": 0.42, "cores": 6, "percent": 7.0 },
  "mem": { "totalBytes": 25186074624, "availableBytes": 23197777920,
           "usedBytes": 1988296704, "percent": 7.9 }
}
FieldMeaning
cpu.percentThe 1-minute load average divided by the core count, as a percentage. Not capped: above 100 means overload.
mem.availableBytesMemory the system can hand out without swapping. Linux reads MemAvailable from /proc/meminfo, macOS adds free, inactive and speculative pages from vm_stat. Elsewhere it is the free memory the runtime reports.
mem.usedBytestotalBytes minus availableBytes.

GET /env ​

The environment overrides the running server resolved at start. One entry per variable, each {value, isDefault, note?}.

FieldMeaning
valueWhat is in force.
isDefaultThe variable was unset or invalid.
noteExplains a fallback, for example that an unset SOMORA_PORT means server.port from config.yaml.

The variables: SOMORA_HOME, SOMORA_PORT, SOMORA_LOG_LEVEL, SOMORA_CLAUDE_BIN, SOMORA_CODEX_BIN, SOMORA_CODEX_TOOL_TIMEOUT_SEC, SOMORA_COMPACTION_TRIGGER_RATIO, SOMORA_COMPACTION_SAFETY_PAIRS, SOMORA_COMPACTION_MODEL, SOMORA_COMPACTION_WORKERS.

GET /tui-config · GET /mobile-config ​

Display preferences for clients, read from config.yaml by the server so that no client parses the file itself.

RouteReturnsConfig block
GET /tui-config{show: {memory, tools}, verbose: {tools, memory, system, thinking}}tui:
GET /mobile-config{show: {tools, memory}}mobile:

A custom client may use either as its own defaults.

GET /mobile-agent-order · PUT /mobile-agent-order ​

The order of the agent tiles in the /mobile client, the same on every device. Kept in ~/.somora/mobile/agent-order.json.

RouteBodyReturns
GET /mobile-agent-order{order: ["agent", …]}, an empty list when none was saved
PUT /mobile-agent-order{order: ["agent", …]}the saved {order}. 400 when order is not a list of agent names, names one twice or holds more than 500.

Agents missing from the list come after it, by name.

GET /logs ​

The tail of the server log for one day.

QueryDefaultMeaning
daynewest fileYYYY-MM-DD. A day, never a path.
minLevelnoneLowest level to include: 20 debug, 30 info, 40 warn, 50 error.
qnoneSubstring to find in the raw line, case-insensitive.
agentnoneOnly lines of this agent.
limit300At most 2000.

Returns {day, days, lines: [{ts, level, msg, agent?, session?, fields}], offset, truncated}. days lists every day that has a file, newest first. offset is the byte position to continue from. truncated says older lines lay outside the window: only the last 512 KiB of the file are read.

GET /logs/since ​

What was appended to the log after a position: the follow path for a log view.

QueryMeaning
offsetByte position from the last response. Default 0.
day, agent, q, minLevelAs for GET /logs.

Returns {lines, offset, day}. When the file shrank, the offset snaps back to its real size.

Config and restart ​

GET /config/status ​

Whether config.yaml changed on disk since the server loaded it, whether the file is valid, and whether the server can restart itself.

json
{ "invalid": null,
  "path": "/home/me/.somora/config.yaml",
  "loadedAt": "2026-05-14T11:09:08.429Z",
  "changedOnDisk": false,
  "restartRequiredSections": ["server", "memory", "obsidian", "wiki", "mcp",
    "browser", "claudeCli", "codexCli", "stt", "tts", "sentinel", "updateCheck",
    "tmux", "web", "mobile"],
  "restartAvailable": true }

restartRequiredSections are the config sections that are read at start and only change after a restart. restartAvailable is true when somora runs as a background service (systemd user unit on Linux, LaunchAgent on macOS).

invalid is null while the file on disk validates. Otherwise it is {since, message}: the file does not validate, somora keeps running on the last valid version, since is when this version of the file was first seen and message lists the problems. The route checks the file on every call.

POST /config/reload ​

Reads config.yaml again. The file is checked first: on any error the running config stays in force.

StatusBody
200{ok: true, changed: [...], restartRequired: [...], loadedAt}. changed lists the sections that differ, restartRequired those of them that need a restart.
400{ok: false, error} with the schema problems. Nothing was changed.

A reload also forgets every "model unavailable" mark, like POST /models/availability/reset, and every cached provider catalog of image and video models: the next request reads them fresh.

Settings ​

The settings window's routes (web.md "The settings window"). Keys and passwords never leave the server: in values they are {secret: true, set}, in the YAML text •••• (set).

GET /settings ​

{path, hash, valid, issues?, groups, restartSections, fields, values, inFile, envSet, refOptions?}.

FieldContent
hashThe file's state; POST /settings/apply needs it back.
groups{id, title, icon, sections, ready}. A group that is not ready is read only.
fieldsOne per setting: {path, kind, section, default?, enum?, min?, max?, minExclusive?, nullable?, required?, valueKind?, info?}. kind is boolean, integer, number, string, enum, strings, one-or-many, boolean-or-strings (on, off or a list of names), object, map or list. * in path stands for an entry name. valueKind belongs to a map of plain values and says what each value is (string, number, integer or boolean; a header is a string). info is {label, help, more?, level, sensitive?, unit?, docs?, placeholder?, locked?, retired?, ref?}: locked gives the reason a setting is not changed here, retired marks one somora no longer reads.
valuesThe configuration in force, defaults filled in; null when the file does not validate.
inFileDotted paths the file itself sets, entries of lists by index.
envSetSettings an environment variable overrides, as {path: variable}. They cannot be changed here.
refOptionsThe names a reference can take, by kind: model (aliases and provider/id), provider, image-model, video-model, decision-model. A field's info.ref names its kind. Sent only when the file validates.

POST /settings/test-model ​

Body {provider, model} (the model's id); without both, 400. Asks an openai-compatible model of the saved configuration one short question, with the model's saved reasoning default and sampling, as a chat turn sends them: {ok, ms, reply?, error?}. A provider or model that is not in the saved configuration gives {ok: false, error} without ms. For a model on another engine {ok: false, note}; it is not asked.

GET /settings/yaml ​

{path, hash, text}: the file as it is on disk, keys blanked.

POST /settings/apply ​

Body {hash, changes: [...]}, each change {path, value}, {path, reset: true} (back to the default: the line is removed) or {path, secret}.

A path may name an entry of a map or list (mcp.servers.<name>, imageGen.models.3) to add it with an object value or remove it with reset, or a field inside one (mcp.servers.<name>.headers.Authorization). List indexes mean the entries as the file has them; a name with a dot of its own is written with %2E (toolCatalog.models.gpt-5%2E5).

A value carrying {secret: true, set} is refused, and so is a change that removes a model, provider or named model still in use (an agent's model, fallback or own REM worker models, or a setting that names it); issues says who uses it.

Only the changed lines are written; comments and layout stay. Before writing, the file is saved to ~/.somora/config-backups/ (the last 20 stay); after it, the configuration is reloaded as by POST /config/reload.

StatusBody
200{ok: true, hash, backup, reload}. reload is the answer of the reload. Changes that leave the file as it was give {ok: true, hash, unchanged: true}: nothing written, no backup.
400{error, issues: [{path, message}]}: an unknown setting, one of a group that is not ready, one an environment variable sets, a locked setting (also when its whole block is sent), a retired setting changed other than by reset, a change with none of value, reset or secret, a value the schema refuses, or the removal of a name still in use. An edit the file cannot take gives {error} alone. Nothing was written.
409{error, hash}: the file changed since hash. Nothing was written.

GET /settings/backups ​

{backups: [{name, at, bytes}], keep}, newest first.

POST /settings/restore ​

Body {name, hash}, both required. Writes that backup back after the same checks as apply, keeps the current file as a backup too, and reloads. 400 for a missing hash, a name that is not a backup, a version that does not validate, or one that would change a locked setting or remove a model or provider still in use; 404 for a backup that is not there, 409 as above.

POST /server/restart ​

Restarts the server through its service manager: the systemd user unit on Linux, the LaunchAgent on macOS. Without a body the restart happens at once.

StatusBody
200{ok: true, via: "systemd" | "launchd", expectedDowntimeSeconds: 8}
409{ok: false, error}: somora was started by hand, so nothing would bring it back. Restart it the way you started it.

A restart requested from inside a turn ​

An agent that restarts somora from its own turn would cut that turn off. The route therefore takes the requester in the body and waits.

bash
curl -H "Authorization: Bearer $KEY" -X POST $BASE/server/restart \
     -H 'Content-Type: application/json' \
     -d '{"agent":"<your-agent>","session":"main","reason":"config change"}'
# → { "ok": true, "deferred": true, "via": "systemd", "message": "…" }
FieldRequiredMeaning
agentyesThe agent that asks.
sessionyesThe session it asks from.
reasonnoFree text, at most 300 characters. Shown to the agent after the restart.

What happens:

  1. The request is written to ~/.somora/restart-intent.json.
  2. The server waits until that session's turn has ended, at most 10 minutes.
  3. Turns in other sessions get 30 more seconds. What still runs is cut and marked in its session.
  4. The server restarts.
  5. After start, the session is woken with a turn whose text begins [system: restart] and says the restart is done. Its origin is {kind: "wake", about: "system", cause: "restart"}.
StatusBody
200{ok: true, deferred: true, via, message}
200{ok: true, deferred: true, already: true, via, requestedBy, message} when a restart is already scheduled
404{ok: false, error} for an unknown agent
409{ok: false, error} when somora does not run as a service

somora server restart and somora update send this request when an agent runs them through exec. The tool sets SOMORA_AGENT and SOMORA_SESSION for the command, so the agent has nothing else to do.

A turn that was cut by a restart it caused itself, for example a raw systemctl restart somora or launchctl kickstart among its tool calls, is woken after start too and told not to run the command again. Other agents whose question or helper was cut are told as well.

A session is woken at most twice in ten minutes, so an agent that answers the wake with another restart cannot loop. The setting server.resumeAfterRestart (requested, all or off) widens this or switches it off.

Chat ​

A turn is one message into a session and everything the agent does to answer it. Each session runs one turn at a time. Whatever arrives while a turn runs waits in that session's queue.

POST /chat/send ​

Sends a message and returns at once. The turn runs in the background and its events arrive on GET /chat/stream. A message from the person answers an open question that does not wait and removes it (question_answered with by: "message").

FieldTypeRequiredMeaning
agentstringyesAgent name. When left out, the alphabetically first agent is used, so pass it.
textstringyesThe message.
sessionstringnoSession reference. Default main.
attachmentsarrayno{hash, name, mime, size} objects from POST /attachments.
steerbooleannoHand the text to the turn that is running now. See "Steering". Ignored together with agent_ask_call_id.
input_modality"text" or "voice"novoice when the client filled the text from its microphone. Stored as user_message.input.modality. A condition for a spoken reply.
stt_providerstringnoFree tag naming the speech-to-text path used.
auto_play_requestedbooleannoThe client wants a spoken reply (assistant_audio). Only honoured together with input_modality: "voice".
from_agentstringnoThe turn is written by another agent. Used by the agent_ask tool.
from_sessionstringnoThe session the asking agent wrote from. Ignored without from_agent.
agent_ask_call_idstringnoCorrelation id of an agent's question. With from_agent the call is registered, so GET /a2a/ask-result finds it while the turn waits or runs.
subagent_depthnumbernoNesting depth when the turn is a sub-agent brief. The turn's origin becomes {kind: "subagent"}.
StatusBody
202{ok: true, turnId}. Keep turnId to match the later turn_queued and user_message events to the bubble you drew.
202{ok: true, steered: true, steerId, turnId} when steer went into the running turn. turnId is that turn's.
202{ok: true, turnId, steered: false} when steer was set but nothing could take it. The message was queued.
400No agent is configured.
404Unknown agent or session.
409The agent is being renamed. Retry in a moment.

Steering ​

With steer: true a message goes into the running turn instead of waiting behind it. The server keeps it until the agent's next step: after the tools of the current round have returned and before the next model call. The model reads it as a message that was sent while it was working. A running tool call is never interrupted.

What a client sees, in order:

  1. The 202 response with steerId.
  2. A steer_queued event on the stream, so other windows can show the pending message.
  3. A user_message event with steer: true and the same steer_id, once the model has been given the text. The message is now in the session history, at the place where the model read it.
CaseResult
Engine openai-compatible, claude-cli, codex-cli or grok-cliThe message is steered.
Any other engine, or no turn runningIt is queued as a turn of its own (steered: false).
The turn is already finishingIt becomes an ordinary queued turn. Nothing is lost.
The message carries agent_ask_call_idNever steered: such a question needs a turn of its own.

On claude-cli and grok-cli a message steered while the model writes its final answer is answered in the same turn. The model finishes the answer, then replies to the message in a new paragraph. The turn ends once every steered message has had its answer.

Grok does not say when it hands a message to the model. somora reads that from Grok's own session record, so on grok-cli the user_message event can arrive a second or two after the model read the text.

Sub-agent and voice turns can be steered like any other. The web client offers a steer or queue switch next to Send. Its starting position is the agent's steering: setting in agent.yaml, reported by GET /agents.

Queuing ​

A message for a session that is busy is queued, not refused. Each session has one queue, first in, first out. Every kind of turn goes through it: typed and dictated messages, questions from other agents, sub-agent briefs, sentinel fires, tmux and browser wakes, voice consults and wake-ups. None jumps ahead. A running turn always finishes before the next one starts.

You want toUse
Show "queued" on a messageThe turn_queued event
See what runs and what waitsGET /agents/:agent/sessions/:session/work
Take a waiting turn backDELETE /chat/queue/:id
Stop the running turnPOST /chat/abort

POST /chat/send-sync ​

Sends a message, waits for the turn to finish and returns the result. This is also the route the agent-to-agent tools use.

It takes agent, session, text, attachments, from_agent, from_session, agent_ask_call_id and subagent_depth as on POST /chat/send, plus:

FieldTypeMeaning
modelstringAn alias or provider/id that answers this one turn instead of the session's model.
max_roundsnumberOverrides agentLoop.maxRounds for this turn.
create_sessionbooleanWhen session is a slug that does not exist on the target, create it and deliver the message there. Only slugs: an exact id or a sub-* name answers 400.
create_modelstringWith create_session: the model pinned on the session if this call creates it. Ignored when the session exists; the response then carries session_note.
waiter_agent, waiter_sessionstringThe turn that blocks on this request. Registers the wait in the deadlock guard. Set both or neither.
detachbooleanWith from_agent and agent_ask_call_id: hand the message over and return at once. The asker is woken when the reply lands. This is agent_ask with wait: false.

Response 200, the turn result:

json
{ "finalText": "…", "outcome": "completed", "tool_calls": 3, "rounds": 2,
  "usage": { "tokens_in": 18200, "tokens_out": 640 },
  "contextWindow": 200000, "provider": "anthropic", "model": "claude-opus-4-7",
  "thinkingActive": false, "ms": 8421,
  "session_id": "20260511-093251_research-notes" }
FieldMeaning
finalTextThe reply.
outcomecompleted, partial, degraded or failed. outcome_reason and error explain the last three.
tool_calls, rounds, msHow much work the turn was. For a builder sent back to open work, tool_calls, files_written and tools_used cover the follow-up turns too, and finalText is the last turn's report (Builder).
files_written, mediaFiles and generated media of the turn, when there are any.
tools_usedThe tools the turn called, each once, by their registry name.
engine, agentKindThe engine that ran the turn (claude-cli, codex-cli, grok-cli, openai-compatible) and the agent's kind (chat or builder).
follow_upsTexts that reached the caller after the report. See GET /spawn-result.
usage, contextWindow, provider, modelTokens and the model that answered. fallback is added when a backup model answered.
thinkingActive, thinkingLevelWhether a thinking level was applied.
session_idThe resolved session id.
session_created, session_modelPresent when this call created the session.
session_notePresent when create_model was ignored.

Other answers:

StatusBodyWhen
202{call_id, state: "pending", session_id, session_created?, session_model?, session_note?}detach was set.
200{finalText: "", outcome: "failed", dequeued: true, error: "removed from the queue by the user before it started", session_id}A person removed the waiting call from the queue.
400{error, known_models}create_model names an unknown model. Nothing was created.
404{error, known_sessions: [...]}Unknown session. The list holds the target's live session slugs, so a caller can correct itself.
409{error, circular_wait: true, chain: [...]}With waiter_*: the target already waits on the caller, directly or through others.
409{error}The agent is being renamed. Retry in a moment.
500{error}The turn could not run.

A session created through create_session is told so beside its first message: who created it and on which model it runs. A message with from_agent is shown to the target with a header naming the agent and its session. Neither is part of the stored text.

POST /chat/abort ​

Stops the turn that is running on a session, whatever started it. Agent and session go in the query string.

bash
curl -H "Authorization: Bearer $KEY" -X POST "$BASE/chat/abort?agent=<your-agent>&session=main"
QueryDefaultMeaning
agentfirst agentAgent name.
sessionmainSession reference.
turnIdnoneStop only this turn, the turnId from POST /chat/send. Another turn running on the session is left alone.

Returns {agent, session, aborted: true, ms_running}, or {agent, session, aborted: false} when nothing was running (or, with turnId, when that turn is not the one running). Safe to call twice. An unknown agent or session also gets aborted: false, not 404. 400 when no agent is configured.

  • Only the running turn is stopped. Queued turns keep their place.
  • A command the turn runs through exec is killed with it. Its result says killed: the turn was stopped.
  • Whoever asked for the turn learns why it ended: another agent's question and a sub-agent task report state: "failed" with error: "stopped by the user". A sentinel fire is recorded as error with the same text.

DELETE /chat/queue/:id ​

Takes a waiting turn out of the queue before it starts. Nothing is written to the session.

:id is the id the queue views show:

Waiting entryIts id
A typed messageThe turnId from POST /chat/send
Another agent's questionThe call_id
A sub-agent brief or a sentinel fireThe task_id
Body fieldMeaning
noneThe request acts as the person and may remove anything.
requesting_agentActs as that agent, which may remove only what it asked for itself. This is what agent_ask_cancel sends.
withdraw_runningWith requesting_agent: if the call already runs, withdraw it instead of answering 409.
StatusBodyMeaning
200{ok: true, id, turnId, kind, agent, session, text?, attachments?}Removed. For a typed message (kind: "human"), text and attachments come back so the client can put them into its input field. The attachment refs stay valid.
200{ok: true, state: "withdrawn", id, turnId, agent, session, steered, steerId?, stopped?, ranMs}A running call was withdrawn. Its result no longer wakes the asker. With steered: true the target was told to stop through a steered message. The turn is not aborted, except on an external agent: there it is stopped, and stopped says whether a turn was running. turnId and ranMs may be null.
403{ok: false, reason: "forbidden", id, error}The entry does not belong to requesting_agent.
404{ok: false, reason: "unknown", error}Nothing waits under that id.
409{ok: false, reason: "already_started", id, turnId}The turn is running. Use POST /chat/abort.

Who is told about a removed entry:

RemovedWhat its requester sees
Another agent's questionstate: "failed" with error: "removed from the queue by the user before it started", as the tool result, in agent_ask_result and in GET /a2a/ask-result. An asker that had stopped waiting is woken with an [agent answer] turn.
A sub-agent briefcancelled with the same error in subagent_status, subagent_result and GET /spawn-status. The parent is woken with a [subagent attention] turn.
A sentinel fireThe trigger's history records it as skipped with skipReason: "removed from the queue by the user".
A wake-up turnDropped quietly. The result it was bringing stays readable.

On success every client on the session gets a turn_dequeued event, followed by fresh turn_queued events for the typed messages that moved up.

GET /chat/history ​

The stored events of a session, oldest first. Clients load this when a chat window opens.

QueryRequiredMeaning
agentyesAgent name.
sessionyesSession reference.
limitnoReturn only the last N events (1 to 2000, default 200 once paging is used).
beforenoEpoch ms. Return events older than this. Pass the oldestTs of the previous page.

Without limit and before the whole session is returned, with hasMore: false. Events with the same ts are never split across pages, so a page can hold a few more than limit. oldestTs is left out when the page is empty.

json
{ "agent": "<your-agent>",
  "session": "20260511-093251_research-notes",
  "events": [ { "kind": "user_message", "ts": 1715512000000, "text": "…" } ],
  "hasMore": true,
  "oldestTs": 1715512000000 }

Every event has kind and ts. The kinds:

kindWhat it is
user_messageThe message that started a turn, with text, origin and the fields described under "The user_message event". The stored row also has ephemeral.
assistant_messageThe reply text.
thinking_messageThe model's reasoning: {text, truncated?}. Stands directly before its assistant_message.
tool_call, tool_resultA tool call and its result. Tool names are in short form (memory_search).
engine_metaA side note of the engine or of somora: raw itemType and payload. See "Engine notes".
model_fallbackA backup model answered. Stands before the assistant message it produced.
assistant_audio, assistant_mediaSpoken audio and generated media of a turn, paired by turnId.
project_switchedThe session's project changed.
errorAn error text. contextOverflow: true when the conversation did not fit the model's window even after compacting; a backup model with a window no larger is then skipped.
turn_start, turn_endBookkeeping around a turn.

400 when agent or session is missing or before is not a number.

GET /agents/:agent/sessions/:session/work ​

What the session is doing right now, what waits behind it, which answers are about to arrive and what it started elsewhere. Only the first 160 characters of each text are exposed.

json
{
  "asOf": 1789300000000,
  "agent": "<your-agent>",
  "session": "20260913-101500_main",
  "busy": true,
  "active": {
    "id": "1f3a…", "kind": "agent", "state": "running",
    "preview": "Can you check whether the release notes mention …",
    "target": { "agent": "<your-agent>", "session": "20260913-101500_main" },
    "requester": { "agent": "<other-agent>", "session": "20260910-083000_main" },
    "enqueuedAt": 1789299990000, "startedAt": 1789299991000, "turnId": "1f3a…"
  },
  "queued": [
    { "id": "b5b7…", "kind": "human", "state": "queued",
      "preview": "and the changelog too",
      "target": { "agent": "<your-agent>", "session": "20260913-101500_main" },
      "requester": { "human": true },
      "enqueuedAt": 1789299995000, "position": 1 }
  ],
  "pendingWakes": [
    { "id": "9d2c…", "kind": "agent", "about": "a2a", "state": "done",
      "preview": "Which of the three drafts …",
      "target": { "agent": "<other-agent>", "session": "20260910-083000_main" },
      "requester": { "agent": "<your-agent>", "session": "20260913-101500_main" },
      "enqueuedAt": 1789299900000, "startedAt": 1789299901000,
      "finishedAt": 1789299999500 }
  ],
  "children": [
    { "id": "task-…", "kind": "subagent", "state": "running",
      "preview": "Summarise the three …",
      "target": { "agent": "<your-agent>", "session": "sub-<your-agent>-20260913-101700" },
      "requester": { "agent": "<your-agent>", "session": "20260913-101500_main" },
      "enqueuedAt": 1789299970000, "startedAt": 1789299971000 }
  ]
}

The four lists:

ListHolds
activeThe running turn, or null. When a turn runs without an entry, the response carries activeTurnId instead.
queuedThe waiters in order, each with position (1 is next). Remove one with DELETE /chat/queue/:id.
pendingWakesWork this session asked for that has finished and whose wake-up turn is scheduled. about is a2a, subagent or job. The delay is agentLoop.wakeGraceMs.
childrenSub-agents and questions to other agents that this session started and that still wait or run.

Every entry has the same fields:

FieldMeaning
idThe work id: a turnId, a call_id, a task_id (also an A2A task's), the consult id of a question from a call, or a video job id.
kindWhere it came from: human, agent, subagent, sentinel, tmux, browser, voice, peer or wake. A wake also has about (a2a, subagent, job or system).
statequeued, running, done, failed, cancelled or dequeued.
previewThe first 160 characters of the text, line breaks folded to spaces.
targetThe {agent, session} the turn runs on.
requesterWho asked: {agent, session}, {human: true} or {voiceCall}. Absent for sentinel, tmux and browser turns.
enqueuedAt, startedAt?, finishedAt?Epoch ms.
turnId?, error?The turn id once it runs. The error for failed, cancelled and dequeued.

This view lives in memory and is empty after a restart.

Streams ​

GET /chat/stream ​

The live events of one session, as Server-Sent Events. Open one per chat window.

bash
curl -H "Authorization: Bearer $KEY" -N "$BASE/chat/stream?agent=<your-agent>&session=main"
QueryDefaultMeaning
agentfirst agentAgent name.
sessionmainSession reference.

400 when no agent is configured, 404 for an unknown agent or session. The first event is status with {msg: "connected", session}, where session is the resolved id.

All events:

EventWhenData
statusOn connect, and for error notices (error: …, turn failed: …){msg}
heartbeatEvery sse.heartbeatMs (20 s)The current time in ms
user_messageA turn's message was stored: the turn has started. Also for a steered message.See "The user_message event"
turn_queuedA message has to wait behind another turn{turnId, ahead, workId?, kind?}
turn_dequeuedA waiting entry was removed with DELETE /chat/queue/:id{turnId, workId?}
steer_queuedA steered message was accepted for the running turn{steerId, text, ts, turnId, origin}
turn_startedThe engine opened the turn{turnId}
agentThe model call starts and ends{phase: "start"|"end", usage?, contextWindow?, provider?, model?, thinking?, fallback?, external?}. external: {system} marks an external agent's turn; external.unprompted: true a message it sent on its own, outside a turn.
memoryAfter agent start: what recall put into the turn{count, topScore?, refs, fullText}
thinkingThe model's reasoning text{state: "delta"|"final", text, truncated?}
chatThe reply text{state: "delta"|"final", text}
toolA tool is called, returns or fails{phase: "call"|"result"|"error", tool, callId, summary?, details?, error?}. callId pairs a result with its call.
engine_metaA side note of the engine or of somora{engine, itemType, label, summary?, payload}
model_fallbackA backup model takes over the turn{requested, actual, reason, hops?}
turn_errorThe turn ended with an error{turnId?, message, engine}
assistant_audioSpoken audio for the reply is ready{turnId, url, mime, durationMs?, cacheKey}
assistant_mediaImages or videos made during the turn{turnId, media: [{type, id, prompt, mime, filename, url, thumbUrl?, durationSec?}]}
session_modelThe session's model was set or cleared{model, resolved?, source}
projectThe session's project changed{from, to, via}
builder_stateA builder session's mode, phase or plan file changed{mode, phase, planPath}
todo_updatedA builder replaced its task list{todos: [{content, status, priority?}], by?}
acceptance_updatedA builder wrote its acceptance list, an item was reviewed, or the list became required or optional{items: [{id, requirement, status, evidence?, updatedAt, review?}], required, by?}. by is the builder, person or the reviewing agent; absent when only required changed.
question_askedAn agent asks the person{questionId, question, header?, options, multiple, expiresAt, kind?, from?, async?, parts?, source?, details?}. kind: "permission" and from: "external" mark an external agent asking to run something; each option's description is then its kind (allow_once, reject_once, …). async: true marks a question that does not wait (expiresAt is 0); parts lists several questions asked at once, source is ask_user, or codex for Codex's own question tool. details is what the person decides on, in full (markdown), shown on the card.
question_answeredThe open question was answered, replaced or ran out of time{questionId?, answered, choice?, by?}. by: "message": a question that does not wait, answered by writing something else.

Details where the table is not enough:

chat and thinking. Deltas are cumulative: each delta carries the whole text so far, so replace what you show instead of appending. The final event carries the complete text. The thinking final comes before the chat final of the same turn. Thinking is only sent by engines that expose it, and not at all with thinkingContent.capture: false.

agent. The start event carries provider, model and thinking ({level, active}). The end event adds usage, contextWindow and, when a backup model answered, fallback and the model that really answered.

usage fieldMeaning
tokens_in, tokens_outWhat the turn spent, summed over every request it made. A turn with tools can exceed the context window several times over.
tokens_in_cachedThe part of tokens_in read from the provider's cache.
tokens_out_reasoning, tokens_out_reasoning_estimatedReasoning tokens, and whether the number is an estimate.
context_tokensThe prompt size of the turn's last request. This is the only value to compare with contextWindow. Optional.

tool. Tool names are in short form: memory_search, not mcp__somora__memory_search. summary is one line made for display. details is the input or the output as pretty-printed JSON. A result with nothing worth showing sends no result event.

turn_queued. ahead counts the turns before this one, including the running one, at the moment it was queued. It is not updated as the queue drains, except after a DELETE /chat/queue/:id. Show "queued" until the user_message with the same turnId arrives.

turn_started. This turnId is the engine's own id (t-…). It is the one that assistant_media, assistant_audio, turn_error and the stored turn_end carry. Mark the reply you are about to draw with it, so that late audio, media and errors land on the right turn.

model_fallback. Model names are provider/modelId. requested is the agent's first model, actual the one answering now, reason the failure. With a chain of backups one event is sent per hop. hops lists every model that failed so far as [{model, reason}]. The event is stored in the history too.

memory. refs are source/slug in score order. fullText is the block the model was given. count is 0 when recall found nothing.

session_model. Sent to every client on the session, because a switch is often made from elsewhere. source is session-override, or persona-default with model: null after a clear.

project. from and to are project slugs or null. via is slash_command for a change through the API and tool when the agent changed it during a turn.

heartbeat. The server watches these writes. One that fails, or stays unfinished for sse.deadAfterMs (60 s), ends the stream. Over HTTPS the connection is also pinged (sse.h2PingIntervalMs, sse.h2PingTimeoutMs). A client should reconnect when heartbeats stop.

The user_message event ​

json
{ "text": "and the changelog too", "ts": 1789299995000, "turnId": "b5b7…",
  "origin": { "kind": "human", "via": "chat" } }
FieldMeaning
textThe message as it is kept: what a person typed, what an agent asked, what a trigger's prompt says, or the one-line statement of a wake-up.
tsEpoch ms.
turnIdLive event only. The id from POST /chat/send. Match it to the bubble you drew.
originWhere the turn came from. See below.
input{modality?: "text"|"voice", source?: "stt"|"realtime"} when the turn was not typed. stt is dictation, realtime a sentence from a call.
steer, steer_idsteer: true marks a message that went into the running turn turnId. steer_id matches the steer_queued event.
from_agent, from_session, agent_ask_call_idOlder fields, derived from an agent origin.
attachmentsStored row only. {hash, name, mime, size} of the files sent with the message.
attachment_descriptionsStored row only. The vision worker's description of each attachment the model could not see, one string per file.
from_systemOlder field, derived from the origin: sentinel, tmux, browser, voice, peer, or for a wake its about (a2a, subagent, job, system). The shipped clients draw these as a divider, not as a bubble.

origin is one of:

ts
origin?:
  | { kind: 'human';    via: 'chat' | 'voice-stt' }
  | { kind: 'agent';    from: { agent: string; session?: string }; callId?: string }
  | { kind: 'subagent'; parent?: { agent: string; session: string }; taskId?: string; depth: number }
  | { kind: 'sentinel'; triggerId: string; taskId: string; triggerName?: string }
  | { kind: 'tmux';     tmuxSession: string; tmuxKind?: string }
  | { kind: 'browser';  viewId: string; cause: 'handoff' | 'activity'; handoffId?: string }
  | { kind: 'voice';    callId?: string; consultId: string }
  | { kind: 'wake';     about: 'a2a' | 'subagent' | 'job' | 'system'; ref: string; depth?: number; cause?: string }
  | { kind: 'peer';     peer: string; contextId: string; taskId: string };
kindThe turn was started by
humanA person typing (chat) or dictating (voice-stt).
agentAnother agent's question, or its follow-up on one (callId is the original call).
subagentA brief running in its own sub-… session.
sentinel, tmux, browser, voiceA trigger, a coding agent in tmux that finished or stopped at a dialog, a browser window handed back, a question from a voice call.
wakeSomething the agent started earlier has finished: a late answer (about: "a2a", ref is the call id), a sub-agent (subagent, task id) or a video (job, job id).
peerA task from another agent system over A2A (A2A).
wake with about: "system"somora itself speaks. cause names the occasion. Today that is restart, and the text begins [system: restart].

Stored rows from old sessions may have no origin. Read the from_* fields then.

What the model is told about a turn, such as who wrote it and what to do with it, is not part of text. It is kept in the stored row's ephemeral field together with the recalled memory, and is not on the stream event.

Engine notes ​

engine_meta carries notes that are not part of the reply. label is a display name chosen by the server, payload the original item, and most notes have a readable payload.text.

itemTypeMeaning
todo_listCodex's own plan or checklist (label plan).
error, reconnecting, transport_fallbackCodex reported an error, reconnects a dropped stream by itself, or switched to HTTPS after retries. The last two are not failures.
model_switchThe Codex thread continues under a new model.
thread_recreatedThe Codex thread was gone. A new one was started with the history replayed.
tools_changedThe agent's tool set changed, so a new Codex thread was started with the history replayed.
mcp_server_renamedThe engine session was rebuilt (label session restarted).
context_compactedThe history was compacted: by somora before a turn (payload.reason: "auto", with contextBefore, contextAfter and contextWindow in tokens; for a builder also builderTarget, reachedTarget and freeTokens), during a turn, after the backend refused the prompt ("context_overflow"), when the first request did not fit even trimmed and the turn starts over on the same model ("context_budget"), or by the engine itself ("engine_side"). A compaction by hand has engine somora, see below.
context_trimmedThe oldest tool results of the running turn were shortened to fit the window. The turn goes on.
attachments_unsupportedThe engine cannot pass attachments on.
session_modelAn agent switched this session's model (label model switched).
voice_handover, voice_spokenA call was handed to or from another agent. What a call said out loud, in older sessions.
voice_call_recordOne realtime voice call (engine voice, label call record), written when the call ends and, for the part before a move, into the session it left. Off with realtimeVoice.keepTranscript: false. payload has text (one line: length, line count, reason), startedAt, endedAt (ms), reason, voice and lines: {at, who, text} with at in ms since the call started and who caller, voice or event (interruptions, questions to the agent, notices, errors). A voice line of an interrupted answer ends in (cut off).
reasoning_effort_adjusted, sampling_droppedThe backend refused a parameter and the turn was retried without it.
doom_loop_notice, doom_loop_stopThe same tool calls three rounds in a row: the model was told to change course (label loop noticed). Five rounds: the turn was stopped (loop stopped).
budget_checkpointA builder used 75 % of its turn budget and was told to save its progress and keep working. payload has round, toolCalls, maxRounds (null without a round cap) and maxToolCallsPerTurn.
open_tasks_noticeA builder on openai-compatible wanted to end its turn with open items on its task list and was told to continue or to name the blocker (label open tasks). Also when acceptance items are open or the required list is missing. payload has round, open (task items), acceptanceOpen, acceptanceMissing (only when true) and attempt (1 or 2). On claude-cli, codex-cli and grok-cli the builder gets a follow-up turn instead: a user_message with origin {kind: "wake", about: "system", cause: "open items"}.
answer_cut_offA builder's answer was cut off by the output limit and it was told to continue where it stopped (label answer cut off). payload has round and attempt (1 or 2).

An unknown itemType keeps its raw name as label.

GET /activity/stream ​

One stream for the whole server: which sessions are working and which have something unread. It also reports sessions that no client has open. Open one per client.

bash
curl -H "Authorization: Bearer $KEY" -N $BASE/activity/stream
EventWhenData
statusOn connect{msg: "connected"}
heartbeatEvery sse.heartbeatMsThe current time in ms
streamingA turn starts or ends on any session. Right after status, one start for every session already working.{agent, session, phase: "start"|"end"}
turnSomething a person should read arrived in a session{agent, session, unreadAt}
seenA client marked a session as seen{agent, session, seenAt}

A turn event is sent for a finished reply (chat with state: "final") and for a user_message that carries from_agent or from_system. Messages a person typed, tool events and the start and end of a model call do not count.

A session is unread when unreadAt is later than seenAt, or seenAt is null. Both are ISO timestamps kept with the session, so the state survives a restart. The session lists return them.

POST /sessions/:agent/:session/seen ​

Tells the server that the person is looking at this session now. Other clients get a seen event and clear their badge.

Body fieldRequiredMeaning
tsnoISO timestamp of when the session was looked at. Default: now.

The body may be empty. The server keeps the later of the stored value and ts, so the marker never moves backwards.

json
{ "ok": true, "agent": "<your-agent>", "session": "main", "seenAt": "2026-05-27T14:00:00.000Z" }

Sessions ​

A session is one conversation of an agent. Every agent has main and any number of named sessions.

GET /agents/:agent/sessions ​

The sessions of one agent.

QueryMeaning
include_archived=trueAlso return archived sessions. They are left out by default.
json
[
  {
    "id": "20260511-093251_research-notes",
    "slug": "research-notes",
    "isMain": false,
    "createdAt": "2026-05-11T09:32:51.000Z",
    "lastActivity": "2026-05-12T14:08:22.000Z",
    "messageCount": 47,
    "isArchived": false,
    "byteSize": 18923,
    "engine": "claude-cli",
    "dreamCoverageTs": 1715520120000,
    "dreamLagEvents": 4,
    "unreadAt": "2026-05-12T14:08:22.000Z",
    "seenAt": "2026-05-12T13:55:00.000Z"
  }
]
FieldMeaning
dreamCoverageTs, dreamLagEventsHow far REM has read this session, and how many events it has not read yet. dreamCoverageTs is null when REM never ran; dreamLagEvents is always a number (then all of the session's events).
unreadAt, seenAtUnread state, see GET /activity/stream.
archivedAt, archiveReasonPresent on archived sessions.
projectSlugPresent when a project is pinned.

GET /sessions ​

The sessions of all agents in one list.

QueryMeaning
include_archived=trueAlso return archived sessions.

Returns {sessions: [...]}. The session_list tool reads this route. Each row has the fields above with the id as sessionId, plus:

FieldMeaning
agent, agentColor, agentIconThe agent the session belongs to.
liveSubscribersClients connected to its stream right now.
dream{status, coverageTs, lagEvents} with status dreamed, partial or never. Replaces the two dream* fields.
busy, queueLength, activeSinceWhether a turn runs, how many wait, and since when (ms, null when idle).

POST /agents/:agent/sessions ​

Creates a named session.

Body fieldRequiredMeaning
slugyesThe name. Must match [A-Za-z0-9_-]+.
StatusBody
201{id, slug, agent}
400The slug is missing, invalid, or main.
409{error, id, slug, agent, exists: true}: a live session already has this name. id is that session, so a client can switch to it.

Archiving or resetting a session frees its name.

POST /agents/:agent/sessions/:session/archive ​

Hides a session from the default lists without deleting anything.

Body fieldRequiredMeaning
reasonnoFree text, kept with the session.

Returns {archived: true, agent, session}. 400 when the session cannot be archived. main cannot: reset it instead.

POST /agents/:agent/sessions/:session/unarchive ​

Brings an archived session back as a normal session, also one that /reset archived. Returns the state after the call:

StatusBody
200{archived: false, agent, session, slug}. slug is the name the session is listed under.
409{error, archived: true}. The session is still archived.

A reset archive keeps its id and is listed under the name in that id, for example main-archive or trip-archive. The original name stays with the fresh session. The history is untouched, and REM does not read the archived part a second time.

The web client's Sessions window, the mobile app's session sheet and the TUI's /unarchive all use this route.

POST /agents/:agent/sessions/:session/compact ​

Compacts the session now, on the engine of its model. See Compact by hand.

Body fieldRequiredMeaning
instructionsnoWhat the summary should keep. Used on openai-compatible and claude-cli, at most 2000 characters.
StatusBody
200{agent, session, status: "compacted", engine, tokensBefore?, tokensAfter?, note?}. note says when the engine ignored the instructions (codex-cli, grok-cli).
200{agent, session, status: "nothing_to_compact", engine, note}. The session is too short, or the engine has no conversation for it yet.
400{status: "unsupported", engine, note}. The engine cannot compact by hand.
409{error, busy: true}. A turn or another compaction is running.
502{error}. The engine failed while compacting.

A finished compaction is stored as an engine_meta row with engine somora and itemType: "context_compacted", and sent to every client on the session. Its payload holds text, manual: true, the engine, the token counts and the focus.

POST /agents/:agent/sessions/:session/reset ​

Archives the session's content and starts the session empty. If REM is enabled for the agent, it reads the archived content in the background.

json
{ "agent": "<your-agent>", "session": "main",
  "archivedId": "20260512-140822_main-archive",
  "dreamSpawned": true }

The reset waits for a running turn to finish. An empty session answers {agent, session, archivedId: null, reason}. Follow the REM run with GET /dream-states.

GET /agents/:agent/sessions/:session/export ​

Downloads the session as a file.

formatContent typeContent
markdown (default)text/markdownA readable transcript: messages as sections, tool calls as collapsible blocks, plans as task lists. Bookkeeping events are left out.
jsonapplication/x-ndjsonThe stored events, one JSON object per line, complete. Use this for backups.

Both set Content-Disposition: attachment. 400 for another format.

bash
curl -H "Authorization: Bearer $KEY" "$BASE/agents/<your-agent>/sessions/main/export?format=markdown" -o main.md
curl -H "Authorization: Bearer $KEY" "$BASE/agents/<your-agent>/sessions/main/export?format=json" -o main.jsonl

Models and thinking ​

Each session can override the agent's model, thinking level and sampling. Without an override the agent's own setting applies.

GET /models ​

Every model in config.yaml.

json
[ { "provider": "anthropic", "id": "claude-opus-4-20250514",
    "alias": "claude-opus-4-7", "engine": "claude-cli",
    "contextWindow": 200000, "capabilities": ["text", "image", "reasoning"],
    "ref": "claude-opus-4-7" } ]
FieldMeaning
refThe handle to pass to the model routes: the alias, else <provider>/<id>.
unavailable{since, until, reason} in epoch ms. Present while the model is marked unreachable after a host error. Fallback chains skip such models for fallback.retryUnavailableMinutes.

POST /models/availability/reset ​

Forgets every "unavailable" mark, so the first-choice models are tried again. Returns {ok: true, cleared, retryUnavailableMinutes}.

POST /decisions/evaluate ​

Asks the configured decision model, the same one the decision_evaluate tool uses, for scripts, skills and other programs. It needs the login key like every route. The body is the tool's input, with images as base64 instead of file paths.

Body fieldRequiredMeaning
stateyesWhat the questions are about: text, a JSON object or array. Only this is evaluated.
questionsyesQuestion id → {type: "boolean"|"choice"|"score", instructions?, criteria?}, 1 to 256. Same rules as the tool.
imagesnoUp to 4 images as base64, with or without a data:image/…;base64, prefix. Only for a model with the image capability.
bash
curl -H "Authorization: Bearer $(somora key)" -X POST $BASE/decisions/evaluate \
     -H 'Content-Type: application/json' \
     -d '{"state":["Invoice overdue, pay by tonight","Newsletter"],
          "questions":{"urgent":{"type":"boolean","instructions":"Does any of these need an answer today?"}}}'

A success is a 200 with the result the decision models page describes (status: "ok", answers, usage). When the decision model could not answer, the response keeps the tool's reason and guidance and adds error.

A request somora refuses before asking (a body that does not validate, bad base64, an unusable image, over 24 MB) gets only error.

Images are PNG, JPEG or WebP, at most 4 MB and 16 megapixels each after scaling and 8 MB together. The status code follows the reason:

StatusReasons
400A body that does not validate, an image that cannot be used, images-unsupported, unsupported-input.
413too-long, truncated, or a body over 24 MB.
429rate-limited.
502authentication, not-ready, transport, invalid-response.
503not-configured.
504deadline.

GET /agents/:agent/sessions/:session/model ​

The model the session's next turn will use.

json
{ "agent": "<your-agent>", "session": "main",
  "provider": "anthropic", "modelId": "claude-opus-4-20250514",
  "alias": "claude-opus-4-7", "engine": "claude-cli", "contextWindow": 200000,
  "source": "session-override", "override": "claude-opus-4-7",
  "personaDefault": "claude-sonnet-4-5" }

source is session-override or persona-default. 500 when the agent's model cannot be resolved.

PUT /agents/:agent/sessions/:session/model ​

Sets the session's model. It applies from the next turn: a running turn keeps the model it started with. This is safe on every engine.

Body fieldRequiredMeaning
modelyesAn alias or <provider>/<id>, as ref in GET /models.
by_agent, by_sessionnoWho switched, when an agent did it. Sent by the session_model tool.

Returns {agent, session, model, resolved: "<provider>/<modelId>"}. 400 for a missing or unknown model; the error lists the known ones.

Every client on the session gets a session_model event. A switch with by_agent is also written into the conversation as an engine_meta note naming who switched to what. A switch by a person leaves no note.

DELETE /agents/:agent/sessions/:session/model ​

Clears the override. Takes the same optional by_agent and by_session. Returns {agent, session, cleared: true} and sends session_model with model: null.

GET /agents/:agent/sessions/:session/thinking ​

The thinking level in force.

FieldMeaning
effectiveThe level that applies: off, low, medium, high, or null when nothing is set and the model decides.
override, personaDefault, modelDefaultThe session's setting, the agent's, and the active model's reasoning.default, or null.
sourcesession-override, persona-default, model-default, or engine-default (nothing set: nothing is sent; show it as "model decides", not "off").
modelSupportsReasoningWhether the current model uses the setting at all.
wireThe value actually sent when it differs from the level, for example xhigh for high. Else null.

PUT /agents/:agent/sessions/:session/thinking ​

Sets the level. Body {"level": "off" | "low" | "medium" | "high"}. Returns {agent, session, level}. Anything else is a 400. Which word is sent to the model for a level is set per model under reasoning.levels in the config.

DELETE /agents/:agent/sessions/:session/thinking ​

Clears the override. Returns {agent, session, cleared: true}.

GET /agents/:agent/sessions/:session/sampling ​

The sampling values in force. Only the openai-compatible engine applies them.

FieldMeaning
effectiveModel defaults, agent defaults and session override merged, or null.
override, personaDefault, modelDefaultThe three layers, each an object or null.
sourcesession-override, persona-default, model-default or engine-default.
engineSupportsSamplingWhether the setting has any effect on the current model.

PUT /agents/:agent/sessions/:session/sampling ​

Merges keys into the session's override. A key set to null is dropped.

bash
curl -H "Authorization: Bearer $KEY" -X PUT $BASE/agents/<your-agent>/sessions/main/sampling \
     -H 'Content-Type: application/json' -d '{"temperature":0.7}'

Keys: temperature, top_p, top_k, min_p, frequency_penalty, presence_penalty, repetition_penalty, seed, stop. Returns {agent, session, override}; override is null once the last key is gone. 400 names an unknown key or a value out of range.

DELETE /agents/:agent/sessions/:session/sampling ​

Clears the override. Returns {agent, session, cleared: true}.

Agents ​

GET /agents ​

The configured agents.

json
[ { "name": "<your-agent>", "description": "scribe and personal assistant",
    "icon": "📝", "color": "#6366f1", "role": "Scribe",
    "steering": true, "kind": "chat" } ]
FieldMeaning
icon, color, roleOptional display values from the agent's AGENTS.md.
steeringThe agent's default for a message typed while a turn runs: true steers, false queues.
kindchat, builder or external.
externalOnly for an external agent: {system, label, badge, badgeImage, version}. label names the agent system ("OpenClaw"), badge is the sign for the tile corner, badgeImage the URL of a badge image when one is configured, version what the agent reported once connected.

GET /agents/:agent/system-prompt ​

The agent's own part of the system prompt: SOUL.md, AGENTS.md and USER.md under somora's headings. Returns {agent, systemPrompt}. For the complete prompt use the next route.

GET /agents/:agent/prompt-preview ​

The system prompt exactly as the next turn would send it. No turn runs and nothing is changed.

QueryDefaultMeaning
sessionmainThe session to build the prompt for.
json
{ "agent": "<your-agent>", "session": "main", "text": "…", "chars": 16210,
  "parts": [ { "key": "self", "label": "Self-pointer", "chars": 900 },
             { "key": "persona", "label": "Persona (SOUL.md · AGENTS.md · USER.md)", "chars": 9340 },
             { "key": "team", "label": "Team block", "chars": 2652 } ],
  "tools": { "count": 41, "schemaChars": 26510, "names": ["exec"] },
  "budgets": { "teamBlockChars": 3000, "personaFileChars": 8000, "personaTotalChars": 14000 },
  "notIncluded": ["tool schemas (…)", "memory recall injected per turn"] }
FieldMeaning
partsThe pieces of text in prompt order: self-pointer, persona, team, tool reminder, wiki overview, skills, session, project.
toolsThe tools this agent would see on that session's model, and the size of their schemas. They travel beside the prompt, not in text.
tools.catalogopenai-compatible only: what the request carries. `{mode: "catalog"
budgetspromptBudgets from the config.
notIncludedWhat a turn sends in addition.

GET /agents/:agent/persona ​

The agent's persona files with what is needed to edit them.

Returns {agent, kind, dreams, files, budgets, totals: {personaChars}}. dreams is the same object GET /agents/:agent/dreams returns. Each file is {name, exists, content, hash, chars, bytes, mtime, readOnly}. The files are AGENTS.md, SOUL.md, USER.md and, read-only, agent.yaml.

GET /agents/:agent/dreams · PUT /agents/:agent/dreams ​

The agent's dreams switch: REM, Deep, the dream tools and the wiki writing tools, see Who dreams.

FieldMeaning
agentThe agent.
onWhether it dreams.
remModelThe model REM runs on, or null when it does not dream or no model is set.
remModelFromagent (its own rem.model), config (rem.model in config.yaml) or null.
problemOnly when it dreams but REM cannot run, for example without any REM model.

PUT takes {on: boolean}, writes dreams: into the agent's agent.yaml (an old rem.enabled goes, the previous file is kept as a backup) and answers {ok: true, …the fields above}. It applies at once: REM starts or stops for the agent, the next Deep run follows it, and the tools follow from the agent's next turn. 400 for a wrong body, 404 for an unknown agent, 500 when the file cannot be written.

PUT /agents/:agent/persona/:file ​

Saves one persona file. :file is AGENTS.md, SOUL.md or USER.md.

Body fieldRequiredMeaning
contentyesThe new text.
baseHashyesThe hash you read. The save only goes through when the file on disk still has it.
StatusBody
200{ok: true, hash, backup, chars}. The next turn uses the new text.
400Wrong body, an unknown file, or an AGENTS.md without a readable header, with a name that does not match the agent, or without a body.
409{error, currentHash, currentContent}: the file changed meanwhile. Agents edit these files too, so reload and merge.

The previous version is kept beside the file as <file>.bak-<timestamp>. The last five are kept.

GET /tools ​

Every tool registered on the server.

Returns {count, tools: [{name, toolset, description, inputSchema, maxResultSizeChars, hasAvailabilityCheck}]}. inputSchema is the tool's JSON Schema. maxResultSizeChars is null for the default cap. hasAvailabilityCheck says the tool is checked at run time and may be hidden from some agents.

GET /agents/:agent/tools · PUT /agents/:agent/tools ​

Which tools an agent may use.

GET returns:

FieldMeaning
agent, kindThe agent and its kind.
kindDefaultsFor a builder: the tool names its kind allows by default. Else null.
gatingThe agent's tools: section as {deny, allow}, or null.
hasPatternRulesAlways false. Kept for older clients; the Abilities window is always editable.
handWrittenRulesPatterns in the section that are not a family rule (toolset:<tag>), a server rule (mcp__<server>__*) or *. They apply; the window lists them as a note.
dreamsThe agent's dreams switch.
tools[{name, toolset, mcpServer?, description, visible, availableNow, lockedBy?}]: every tool, built in or from an external MCP server. visible says whether the agent may use it. lockedBy: "dreams" marks the dream tools and the wiki writing tools: they follow the dreams switch, not the rules.

PUT takes {deny: string[], allow: string[]} and rewrites only the tools: block of the agent's agent.yaml. Returns {ok: true}. 400 for a wrong body or a failed write, 404 for an unknown agent. It applies from the agent's next turn and keeps the previous file as a backup, like a click.

POST /agents/:agent/tools/toggle · POST /agents/:agent/skills/toggle ​

One click in the Abilities window. The server works out the rules, so every client edits the same way. Body:

FieldMeaning
namesThe tools or skills to switch, at least one.
visibletrue to switch them on, false to switch them off.
grouptrue when the names are one whole family (a toolset, an MCP server, or all skills). Off then writes one rule for the family, so tools it gains later stay off.

Returns {ok: true, gating} with the rules now in agent.yaml. Only the named entries change state. 400 for a wrong body, an unknown name, or a builder-only tool (todo_write, plan_write, acceptance_write) for a chat agent. 409 with lockedBy: "dreams" for a tool that follows the dreams switch. 404 for an unknown agent. Clicks on one agent run one after another, and each write keeps the previous agent.yaml as a backup (the newest five stay).

GET /agents/:agent/skills · PUT /agents/:agent/skills ​

Which skills an agent sees.

GET returns {agent, kind, gating, hasPatternRules, skills}. Each skill is {name, description, available, unavailableReason?, visible}. gating is the agent's skills: section as {deny, allow} or null. hasPatternRules is always false, kept for older clients.

PUT takes {deny: string[], allow: string[]} and rewrites only the skills: block of agent.yaml. Empty lists remove the block. Names are skill names ([a-z0-9-]), plus * under deny for every skill. Returns {ok: true}, 400 on a wrong body, 404 for an unknown agent. It applies from the next turn and keeps the previous file as a backup.

POST /agents/:agent/tools/:name ​

Runs one tool as the agent, without a chat turn. The body is the tool's input, the response its result.

bash
curl -H "Authorization: Bearer $KEY" -X POST $BASE/agents/<your-agent>/tools/memory_search \
     -H 'Content-Type: application/json' \
     -d '{"query":"voice satellites","limit":3}'

The agent's own tool rules apply, as in a chat turn: a tool switched off in the Abilities window or under tools: in its agent.yaml answers 403 with {ok: false, error} and does not run. The same goes for the builder-only tools on a chat agent. See Choosing tools per agent.

StatusMeaning
200The tool ran; the body is its result.
400The tool reported a failure, or no tool has this name (with the nearest names).
403The tool is turned off for this agent, or it is a dream or wiki writing tool and the agent does not dream.
404No such agent.

Team ​

The team file ~/.somora/team.yaml says who reports to whom. It can be read and written here or edited by hand.

GET /team ​

The team as written and as resolved.

FieldMeaning
enabledA valid team is in force.
path, exists, validThe file, whether it is there, whether it parses.
issues[{path, message}] when it is invalid. The last valid team stays in force.
fileThe document as written.
principal, rulesThe person at the top and the team rules.
agentsBy name: {name, title, reportsTo, involveFor, notFor, notes?, children, depth}.
orderThe agents from the top down.
unlisted, missingAgents on disk that the file does not name, and file entries without an agent.
warningsThings worth fixing that do not make the file invalid.

GET /team/preview/:agent ​

The team text that agent gets in its system prompt. Returns {agent, enabled, block, chars, softMaxChars}, or {agent, enabled: false, block: ""} without a team.

GET /team/check ​

What somora team check prints, without the persona scan. Returns {exists, valid, issues, warnings, unlisted, missing, blocks: [{agent, chars, overSoftMax}], softMaxChars}.

PUT /team ​

Replaces the team file. The body is the whole document as JSON: {version: 1, principal, rules?, agents}, the shape GET /team returns under file.

StatusBody
200{ok: true, backup, …} plus everything GET /team returns.
400{error, issues: [{path, message}]}. Nothing was written.

The previous file is kept as team.yaml.bak-<timestamp> (last five). Agents see the change on their next turn.

POST /team/init ​

Writes a first team file in which every agent reports to the principal. Body {principal?: string}. Returns {ok: true, …} with the fields of GET /team. 409 when a file exists: this route never overwrites. 400 when there are no agents.

POST /team/preview ​

Renders a draft for one agent without saving it. Body {file, agent}. Returns {agent, valid, issues, warnings, block, chars, softMaxChars}. An invalid draft comes back with valid: false and its issues.

Agent to agent ​

These routes carry the agent_ask and sub-agent tools. A custom client can use them to follow such calls or to run background tasks.

GET /a2a/ask-result ​

The outcome of one agent's question to another, by call id.

QueryRequiredMeaning
call_idyesThe id of the call.
wait_until_doneno1 blocks until the call finishes or timeout_ms passes.
timeout_msnoDefault agentLoop.longTaskDefaultTimeoutMs, capped at agentLoop.longTaskMaxTimeoutMs.
waiter_agent, waiter_sessionnoWho waits. Registers the wait in the deadlock guard.
agent, sessionnoThe target. Needed after a restart, when the call is no longer in memory: the answer is then read from the target's history.
json
{ "call_id": "…", "state": "done", "target_agent": "<other-agent>",
  "target_session": "20260906-172957_research", "started_at": 1788000000000,
  "finished_at": 1788000042000, "response": "…", "outcome": "completed",
  "model": "<provider>/<model>", "source": "registry" }
FieldMeaning
statequeued, running, done or failed. Read from history it can also be unknown: the turn never ended.
response, outcomeThe reply and the turn's outcome, once done.
modelprovider/model that produced the reply. Read from history, it comes from the turn's end.
fallback{requested, reason} when a backup model answered instead of the one asked for. Absent otherwise.
errorWhy it failed. stopped by the user and removed from the queue by the user before it started mean a person intervened. An agent should not retry those by itself.
sourceregistry (in memory) or history (read from the target session).

404 when the call is unknown and no agent and session were given, or when the target session has no such call. 409 with circular_wait: true and chain when waiting would close a cycle.

Reading a result cancels the wake-up the asker would otherwise get. A done call may later be followed by one more message from the target, when work it had started finishes after its reply. That follow-up arrives as a normal turn with an agent origin and the same callId.

GET /a2a/turn-origin/:agent/:session ​

Who started the turn that is running on a session. agent_ask uses it to send a reply back to the session the question came from.

json
{ "origin": { "agent": "<other-agent>", "session": "20260906-172957_research", "kind": "a2a" } }
kindMeaning
a2aAnother agent asked.
subagentThe session is a sub-agent's. The origin is the parent that started it.
wakeThe turn is a wake-up. The origin is the agent and session whose answer caused it.

{"origin": null} when the turn was started by a person or a trigger.

The agent_ask result names the rule that chose the target session as routing_reason:

routing_reasonMeaning
explicitThe caller named a session.
reply_to_originNo session was named and the target is the origin agent, so the message went to the origin session. The result also has session_inferred: true.
default_mainNeither applied: the message went to main. A routing_note is added when the caller sits in another session.

Sub-agent tasks ​

Every sub-agent runs as a task: a brief that runs in a session of its own and reports back. These routes are what spawn_subagent and the subagent_* tools call. Tasks live in memory and are gone after a restart.

POST /spawn-async ​

Starts a task and returns at once.

Body fieldRequiredMeaning
agentyesThe agent that does the work.
sessionyesThe session to run in. A slug that does not exist is created. An exact id that does not exist answers 404.
textnoThe brief.
parent_agent, parent_sessionnoWho is told when the task ends. Default: from_agent, else the agent itself.
from_agentnoMarks the turn as written by that agent.
subagent_depthnoNesting depth.
modelnoModel for this task.
max_roundsnoOverrides agentLoop.maxRounds.
attentionnofalse suppresses the parent's wake-up when the task ends.
attachmentsnoRefs from POST /attachments.

Returns 202 {task_id}. 400 when agent or session is missing, 429 when the agent already runs as many sub-agents as allowed.

GET /spawn-status?task_id=… ​

The state of a task.

json
{ "task_id": "task-…", "state": "running",
  "parent_agent": "<your-agent>", "parent_session": "20260913-101500_main",
  "target_agent": "<your-agent>", "target_session": "sub-<your-agent>-20260913-101700",
  "started_at": 1789299970000 }

state is running, done, failed or cancelled. finished_at and error appear when they apply. 404 for an unknown id.

GET /spawn-result?task_id=… ​

The result of a finished task.

QueryMeaning
task_idRequired.
wait_until_done1 blocks until the task ends or timeout_ms passes.
timeout_msCapped at agentLoop.longTaskMaxTimeoutMs.
waiter_agent, waiter_sessionWho waits. Joins the deadlock guard.

Returns {task_id, state, target_agent, target_session, result?, error?}. result is the turn result described under POST /chat/send-sync.

result.follow_ups holds texts that reached the parent after the report: the outcome of work the sub-agent started and did not wait for. Each one is announced to the parent with a [subagent attention] wake-up.

StatusMeaning
409{task_id, state: "running", error}: not finished yet. With circular_wait: true and chain: the task waits on the caller.
404Unknown id.

Reading a finished result cancels the parent's pending wake-up.

GET /spawn-list?parent_agent=… ​

Every task that agent started since the server came up. Returns {tasks: [...]} with entries as in GET /spawn-status. 400 without parent_agent.

POST /spawn-cancel ​

Cancels a task and every task it started. A running turn is aborted, a waiting one is taken out of its queue. Files it wrote stay.

Body fieldRequiredMeaning
task_idyesThe task.
requesting_agentnoActs as that agent, which must be the one that started the task (403 otherwise). Without it the request acts as a person and the parent reads stopped by the user.
reasonnoFree text, added to the reason the parent reads.

Returns {cancelled: [task_ids], skipped: [{task_id, state}]}. Tasks that had already ended are skipped. 404 for an unknown id.

Builder sessions ​

Agents of kind builder keep a mode, a phase, a plan file and a task list per session, and at most one open question to the person. The web client's task panel uses these routes, and so do the builder's own tools todo_write, plan_write and acceptance_write.

POST …/ask (the ask_user tool) serves every agent. A builder waits, 30 minutes by default. For a chat agent: in a turn nobody watches it returns {answered: false} at once; in a turn a person started it returns at once and the question stays open; in a task from another system over A2A it waits, 10 minutes by default.

GET /agents/:agent/sessions/:session/builder ​

The builder state of a session.

json
{ "agent": "<your-agent>", "session": "20260913-101500_main", "kind": "builder",
  "state": { "mode": "attended", "phase": "plan",
             "planPath": "/home/me/code/acme/PLAN.md",
             "todos": [ { "content": "Write the parser", "status": "pending" } ] },
  "acceptance": { "required": true,
                  "items": [ { "id": "A01", "requirement": "A rejected result is never shown as completed",
                               "status": "passed", "evidence": "npm test gate.test: rejected → failed",
                               "updatedAt": 1789299998000 } ] },
  "writeAllow": [],
  "question": null,
  "turn": { "turnId": "…", "startedAt": 1789299991000, "toolCalls": 7,
            "lastTool": "file_write", "lastToolAt": 1789299999000 } }
FieldMeaning
state{mode, phase, planPath, todos, orderer?}, or null before the session's first turn. mode is attended or unattended, phase is plan or build.
acceptance{items, required}: the acceptance list (see below) and whether the session requires it.
writeAllowFolders the builder may write in besides the project: set by the orderer or by "Allow this folder for the session".
question{questionId, question, header?, options: [{label, description?}], multiple, askedAt, expiresAt} or null. Also carries the question a builder raises before writing outside its project folder.
turnProgress of the running turn, else null.

PATCH /agents/:agent/sessions/:session/builder ​

Changes mode, phase or plan file. Sends builder_state, and acceptance_updated when acceptanceRequired is in the body.

Body fieldMeaning
modeattended or unattended.
phaseplan or build.
planPathAn absolute path, or null to clear it.
orderer{agent, session?}: the agent that handed the order over. Set by builder_dispatch, or else by the first agent that writes into the session.
acceptanceRequiredtrue makes the acceptance list required for this session, false optional. The panel's list switch sends it. A message from another agent turns it on by itself (agent_ask, builder_dispatch, an A2A peer).
writeAllowAbsolute folders the builder may also write in, added to those already allowed. At most 4 per request. Each must exist and be narrow: not /, not the home folder, not a folder holding the project, not inside somora's home. Needs a pinned project. Set by builder_dispatch write_allow.

Returns {agent, session, state}. 400 for a value outside these.

POST /agents/:agent/sessions/:session/builder/go ​

Approves the plan: sets the phase to build and starts a turn that tells the builder to carry it out.

Body fieldMeaning
noteOptional text added to that message.
StatusBody
202{agent, session, state, turnId}
202{agent, session, state, turnId, callId, wakes} when the state has an orderer. The turn then runs as that agent's question, and wakes names who gets the report.
409{error, busy}: another builder's turn is working in the session's folder.

PUT /agents/:agent/sessions/:session/todos ​

Replaces the whole task list. Sends todo_updated.

Body fieldMeaning
todos[{content, status?, priority?}], at most 100. status defaults to pending. Each content is cut at 500 characters.
by_agentOptional: who wrote it.

Returns {agent, session, todos}.

GET /agents/:agent/sessions/:session/acceptance ​

The acceptance list: {agent, session, items, required}. Each item is {id, requirement, status, evidence?, updatedAt, review?}. status is open, passed, failed or not_run. review is {verdict: "accepted" | "rejected", by, note?, at}.

PUT /agents/:agent/sessions/:session/acceptance ​

Writes the list. Used by acceptance_write, sends acceptance_updated.

Body fieldMeaning
items[{id, requirement?, status, evidence?}], at most 60. A new item needs requirement.
by_agentWho writes it. Another agent than the builder gets 403.

The answer is {items, required, warnings}. The merge keeps the list whole:

  • an item left out stays,
  • an existing requirement keeps its first wording,
  • accepted or rejected as a status is refused,
  • a new status or new evidence clears the item's review,
  • when required is true, passed or failed without evidence, or not_run without the reason in evidence, is refused: the item keeps its status and evidence.
  • an item sent again with the same status and no evidence keeps its evidence and its review.

warnings names each of these. Without required, passed or failed without evidence is only a warning. 400 for a chat agent.

POST /agents/:agent/sessions/:session/acceptance/review ​

Reviews one item. Sends acceptance_updated.

Body fieldMeaning
idThe item. 404 when the list has no such item.
verdictaccepted or rejected.
noteOptional, up to 1000 characters.
by_agentOptional. Without it the review is the person's (by: "person"). With it, it must be the session's orderer; the builder itself and any other agent get 403. An item the person reviewed gets 409 until the builder sends new evidence.

PUT /agents/:agent/sessions/:session/plan ​

Writes the session's plan file. Body {content}.

The path is the session's plan path. Without one it is PLAN.md in the session's working folder, which is the pinned project's folder or the workspace. Returns {path, bytes, archived?, note?}. Sends builder_state.

If a plan was already there and this session did not write it, it is moved aside first to PLAN-<date>-<session>.md and archived names that file. 400 when the write policy forbids the path.

POST /agents/:agent/sessions/:session/ask ​

Asks the person a question and blocks until they answer or the wait runs out. Sends question_asked. A chat agent's question in a turn a person started does not block: it returns at once with {asked: true, questionId, note} and stays open on the session (see the question routes).

Body fieldRequiredMeaning
questionyesThe question, at most 2000 characters.
optionsyes2 to 6 of {label, description?}.
headernoA short title, at most 40 characters.
multiplenotrue allows several answers.
detailsnoWhat the person decides on, in full (markdown, at most 8000 characters): the text to approve, the drafts to pick from. Shown on the card; blank is left out.
timeout_msnoDefault 30 minutes for a builder, 10 for a chat agent; at most 4 hours.

Returns {answered, answers: string[], text?}. A second question on the same session replaces the first, which returns unanswered.

POST /agents/:agent/sessions/:session/answer ​

Answers the open question. Sends question_answered.

Body fieldRequiredMeaning
questionIdyesFrom question_asked or the builder state.
answersnoThe chosen labels.
textnoA free-text answer.

Returns {ok: true}. 404 when no such question is open.

GET /builders ​

The builder agents and the folders each is working in right now. Returns {builders: [{name, role, description, busy: [{session, workdir, since}]}]}.

GET /builders/busy ​

Whether a running builder turn claims a folder.

QueryMeaning
workdirA path. The check also covers its parent and child folders.

Returns {workdir, busy} where busy is {agent, session, turnId, workdir, since, reason} or null. Without workdir it returns {claims: [...]}.

POST /lsp/diagnostics ​

Asks the language server about a file a builder just wrote. This is what file_write and file_patch call.

Body fieldRequiredMeaning
agent, sessionyesThe builder session.
pathyesAbsolute path of the file.
touchnotrue only starts the server and returns {diagnostics: null, touched: true}.

Returns {diagnostics} with {server, errors, errors_in_other_files} or null. For an agent that is not a builder, or with language servers switched off, it is {diagnostics: null, reason}.

GET /lsp/status ​

The language servers somora knows. Returns {enabled, waitMs, servers: [{id, title, extensions, enabled, command, source}], running}.

Memory ​

Each agent has its own notes. A shared vault and the wiki can be searched with them.

GET /agents/:agent/memory/notes ​

The agent's indexed notes. Returns {agent, count, notes}.

GET /agents/:agent/memory/search ​

Searches the agent's notes and the shared vault and wiki index by keyword and by meaning. It is the search the memory_search tool uses.

QueryDefaultMeaning
qrequiredThe search text.
limit51 to 50.
minScore00 to 1. Hits below it are dropped. Recall during a turn uses autoInject.minScore instead.
bash
curl -H "Authorization: Bearer $KEY" "$BASE/agents/<your-agent>/memory/search?q=voice+satellites&limit=5"

Returns {agent, query, limit, minScore, count, hits}. Each hit:

FieldMeaning
slug, sourceThe note, and where it lives: memory, wiki or vault.
scoreThe combined score, scaled within this query's results. It is a rank, not a similarity.
vecScore, bm25ScoreThe meaning score and the keyword score.
startLine, endLine, filePath, textThe matching passage.

For the whole note, call the memory_get tool through POST /agents/:agent/tools/:name.

POST /agents/:agent/memory/recall-preview ​

What a turn would recall for a message, without running a turn. Use it to try a recall setting before changing the config.

Body fieldRequiredMeaning
textyesThe message.
historynoEarlier messages, oldest first: {kind, text} with kind user_message or assistant_message. Other entries are ignored.
autoInjectnoOverrides any memory.autoInject setting for this call only.
json
{ "text": "and who else is in the family?",
  "history": [
    { "kind": "user_message", "text": "what can you tell me about Karl?" },
    { "kind": "assistant_message", "text": "Karl is …" } ],
  "autoInject": { "historyWeight": 0.4 } }

Returns {agent, text, historyTurns, injectedCount, hits, ephemeralContextChars}. The hits have slug, source, score, vecScore, bm25Score, startLine and endLine.

Wiki explorer ​

Read access to the shared wiki. Every route except the status answers 503 unless wiki.enabled and obsidian.vault are both set. Pages are addressed by slug, never by path, so a request can only name pages the wiki index already found.

GET /wiki/status ​

Whether the wiki is on. Returns {enabled, root?}. Ask this once to decide whether to show a wiki view.

GET /wiki/tree ​

The folder tree with all pages.

json
{ "root": "/path/to/vault/somora", "pages": 262, "builtAt": 1784750000000,
  "nodes": [
    { "type": "dir", "name": "people", "path": "people",
      "children": [
        { "type": "page", "slug": "people/muster-family",
          "name": "muster-family.md", "title": "Muster family",
          "description": "…", "mtimeMs": 1784700000000 } ] } ] }

A page's title is its first # H1, else title from its header, else the file name.

GET /wiki/page?slug=<slug> ​

One page with its links.

json
{ "slug": "projects/somora", "title": "somora", "folder": "projects",
  "mtimeMs": 1784700000000,
  "markdown": "## Current state\n…",
  "frontmatter": { "type": "project" },
  "links":      [ { "slug": "people/nina-muster", "title": "Nina" } ],
  "backlinks":  [ { "slug": "agents/<your-agent>", "title": "Your agent" } ],
  "unresolved": ["people/muster-family"],
  "linkTargets": { "people/nina-muster": "people/nina-muster", "muster-family": null } }

linkTargets maps every [[target]] in the text to a slug, or to null when nothing matches. A target matches by exact slug, by slug without regard to case, or by a file name that exists only once. A file name that exists several times resolves to null.

400 without slug, 404 for an unknown page.

GET /wiki/graph?scope=local&slug=<slug> · ?scope=global ​

The link graph around one page, or of the whole wiki.

json
{ "scope": "local",
  "nodes": [ { "id": "projects/somora", "label": "somora", "folder": "projects", "degree": 41 } ],
  "edges": [ { "from": "agents/<your-agent>", "to": "projects/somora", "type": "wikilink" } ],
  "truncated": false }
ScopeReturns
local (default)The page, what it links to, what links to it, and the links among those. Needs slug.
globalThe whole wiki, capped at the 400 best-connected pages. truncated says whether the cap applied.

degree always counts links in the whole wiki. Edge type is wikilink for a [[link]] in the text and related for a related: entry in the header. index.md is left out: it links to everything.

400 when local has no slug, 404 for an unknown page.

POST /wiki/refresh ​

Rebuilds the wiki index now. Returns {pages, builtAt}. Ordinary edits show up without it: the index is kept for 10 seconds and then re-reads only files that changed.

Dream system ​

The three dream phases, REM, Deep and Lucid, turn conversations into memory and wiki pages. These routes show their state and start them by hand.

GET /dream-states ⚠ experimental ​

The state of all three phases.

json
{ "rem": { "<your-agent>": { "active": false, "pendingCount": 3 } },
  "deep":  { "active": false },
  "lucid": { "active": false, "pendingRuns": 0, "pendingFindings": 0 } }
FieldMeaning
rem.<agent>.activeA REM dream is running for that agent.
rem.<agent>.pendingCountFinished REM dreams that wait for review.
deep.active, lucid.activeA run is in progress.
lucid.pendingRuns, lucid.pendingFindingsLucid runs and findings that wait for review. oldestPendingAt is added when there are any.
lucid.loopHolderThe agent that is reviewing Lucid findings right now, when one is.

GET /dream/loop-state ​

Whether an agent is reviewing Lucid findings right now.

json
{ "active": true, "agent": "<your-agent>", "dreamId": "lucid-…",
  "startedAt": "…", "lastActivityAt": "…" }

{ "active": false } when nobody is.

POST /agents/:agent/dream/run-rem ​

Starts REM for one agent now, without waiting for the agent to go quiet. It always runs in the background, and chat activity pauses it as usual.

json
{ "agent": "<your-agent>", "outcome": "started", "started": true, "message": "…" }

outcome is started, busy (already running) or nothing_to_do. 409 with reason: does-not-dream when the agent's dreams switch is off, no-model when no REM model is set, neither in its agent.yaml nor in config.yaml.

POST /dream/run-deep ​

Starts a Deep run.

Body fieldDefaultMeaning
waitfalsetrue waits for the run and returns its result.
forcefalsetrue re-reads every memory file, also those the skip cache would leave out.

Without wait: {started: true, wait: false, force, message}. With it: {wait: true, force, candidatesSeen, cachedSkips, durationMs, counts, outcomes}. 400 when the wiki is off.

POST /dream/run-lucid ​

Starts a Lucid run. Same body as POST /dream/run-deep. While an earlier run still has findings waiting for review, no new run starts unless force is true.

Without wait: {started: true, wait: false, message}. With it: {wait: true, runId, findingsCount, pagesScanned, durationMs, status}. 400 when the wiki is off.

Wiki migration ​

These routes move a grown wiki onto the folder template, in steps: plan, refine, approve, execute. Plan ids look like 20260929-104047. Each plan has a folder under ~/.somora/wiki-migration/<id>/. The write routes answer 400 when the wiki is off (all but approve) or the id is malformed.

POST /wiki/migration/plan ​

Step one. Reads the whole wiki and writes down what a migration would do. Nothing in the wiki is touched.

json
{ "id": "20260929-104047",
  "plan": "/home/me/.somora/wiki-migration/20260929-104047/plan.md",
  "pagesTotal": 991, "foldersTotal": 71,
  "summary": { "move_folder": { "items": 19, "pages": 40 },
               "unite_twins": { "items": 19, "pages": 38 },
               "fold_report": { "items": 190, "pages": 190 },
               "review_pages": { "items": 37, "pages": 447 },
               "describe_folder": { "items": 0, "pages": 0 },
               "unclear": { "items": 0, "pages": 0 } },
  "durationMs": 1830 }

POST /wiki/migration/refine ​

Step two. The Lucid model, or else the Deep model, judges every page the plan is unsure about or would move: keep, move, fold into another page, or unclear. Still nothing is written into the wiki.

Body fieldDefaultMeaning
idrequiredThe plan id.
waitfalsetrue returns the result in the response.
batchSize25Pages per model call.

Without wait: {id, started: true, message}. With it: {id, refined, pagesJudged, batchesTotal, batchesFailed, groups: [{action, target, pages}]}. The result is also written as refined.md and refined.json beside the plan. 404 for an unknown plan, 409 while a refine for it runs.

GET /wiki/migration/plans/:id ​

The plan, the progress of a running step and the approvals.

json
{ "id": "20260929-104047", "dir": "…/wiki-migration/20260929-104047",
  "plan": { "pagesTotal": 991, "foldersTotal": 71, "summary": {}, "createdAt": "…" },
  "refine": { "started": "…", "done": 12, "total": 27 },
  "execute": null,
  "approvals": { "planId": "…", "groups": { "move:rules": { "status": "approved", "at": "…" } }, "twins": {} },
  "refined": { "model": "…", "pagesJudged": 943, "batchesTotal": 38, "batchesFailed": 0,
               "createdAt": "…",
               "groups": [ { "action": "move", "target": "rules", "pages": 50 } ] } }

refine and execute are null when that step has not run since the server started. A finished step has finished, a failed one error.

POST /wiki/migration/plans/:id/approve ​

Step three. Marks groups of the refined plan.

Body fieldMeaning
groupsGroup keys such as move:rules or fold:projects/somora.
actionmove, fold or unclear: every group of that action.
twinsNames of twin pages to unite, or "all".
statusapproved (default), dismissed or pending.
json
{ "id": "…", "status": "approved", "touched": 3,
  "approvedGroups": 12, "approvedPages": 310, "approvedTwins": 19 }

404 until the plan has a refined result.

POST /wiki/migration/plans/:id/execute ​

Step four. Runs the approved part.

Body fieldDefaultMeaning
dryRuntrueA dry run writes dry-run.md beside the plan and touches nothing.
confirmnoneA real run needs {"dryRun": false, "confirm": "move my wiki"}.
waitfalsetrue returns the result in the response.

A real run first copies the whole wiki into backup-<time>/ under the plan and does not start when the copy is incomplete.

Without wait: {id, dryRun, started: true, message}. With it:

json
{ "id": "…", "dryRun": false, "report": "…/execution-20260929-131500.md", "steps": 768,
  "counts": { "move": 207, "fold": 540, "unite": 19, "failed": 2, "skipped": 0 },
  "linksRewritten": 812, "foldersRemoved": 51, "backupDir": "…/backup-20260929-131412",
  "reindex": { "indexed": 610, "skipped": 380 } }

404 without a refined result, 409 while a run for that plan is going.

POST /wiki/migration/plans/:id/relink ​

Goes over every page again with the renames a finished run recorded. [[links]] and related: entries that still name a moved, folded or united page are pointed at its new place. Safe to repeat. Body {"dryRun": true} only counts.

json
{ "id": "…", "dryRun": false, "renames": 819, "refsRewritten": 393, "pagesTouched": 224 }

404 when the plan has no finished run.

POST /wiki/migration/reindex ​

Runs one full pass of the shared search index now. somora wiki migrate undo calls it after putting a backup back. Returns {indexed, skipped}. 503 when the index cannot run it yet.

Projects ​

A project links a session to a folder, links and a description. The feature is opt-in: every route except the first answers 503 when projects.enabled is false.

GET /projects/feature ​

Whether projects are on. Always answers 200.

json
{ "enabled": true, "entityCount": 2 }

GET /projects/entities ​

The fixed list of entities a project can belong to, from projects.entities in the config.

json
{ "entities": [ { "slug": "private", "label": "Private" },
                { "slug": "acme", "label": "acme" } ] }

GET /projects ​

The projects.

QueryMeaning
entityOnly this entity.
tagOnly projects with this tag.
includeArchived=trueAlso archived projects.
json
{ "total": 1,
  "projects": [
    { "slug": "home-cinema", "name": "Home cinema", "entity": "private",
      "description": "Receiver, projector, …", "color": "#4f46e5",
      "tags": ["hardware", "wip"],
      "created": "2026-04-15T10:23:00Z", "updated": "2026-05-13T09:42:00Z",
      "archived": false,
      "paths": [ { "ref": "~/code/home-cinema", "label": "Source code" },
                 { "ref": "https://example.com/plans" } ],
      "workdir": "~/code/home-cinema" } ] }

GET /projects/:slug ​

One project as {project}. 400 for a malformed slug, 404 when it does not exist.

POST /projects ​

Creates a project.

Body fieldRequiredMeaning
slugyesMust match [a-z0-9_-]+ and be new.
nameyesDisplay name.
entityyesOne of the slugs from GET /projects/entities.
description, color, tags, expiresnoFree fields. expires is a date string or null.
pathsno[{ref, label?}]. A ref is https://…, ~/path, /path, or <resource>:/path with a resource from the config.
workdirnoThe project's working folder. A session that pins the project works there.
StatusBody
201{project}
400A required field is missing, the slug is malformed, the entity is unknown or a ref is not valid. The error lists what is available.
409A project with that slug exists.

PATCH /projects/:slug ​

Changes a project through a list of operations. All are checked first: if one fails, nothing is written.

json
{ "ops": [
    { "op": "add_path", "ref": "~/research/atmos.md", "label": "Atmos notes" },
    { "op": "set_field", "field": "description", "value": "Updated" },
    { "op": "set_tags", "tags": ["hardware", "wip"] } ] }
opFieldsEffect
set_fieldfield (name, description, color, expires, workdir), value (string or null)Sets the field. null clears it. name cannot be cleared.
add_pathref, label?Adds a path. Checked as in POST /projects. 400 when it is already there.
remove_pathrefRemoves the path with exactly that ref. 400 when it is not there.
set_tagstagsReplaces all tags.
archivereason?Hides the project.
unarchivenoneBrings it back.

Returns {project}. 400 for a bad operation, 404 for an unknown project. Slug and entity cannot be changed.

GET /agents/:agent/sessions/:session/project ​

The project pinned to a session.

CaseBody
Pinned{agent, session, slug, project}
Nothing pinned{agent, session, slug: null, project: null}
Pinned, but the project file is gone{agent, session, slug, project: null, missing: true}

POST /agents/:agent/sessions/:session/project ​

Pins a project to a session. Body {"slug": "<slug>"}; null clears the pin. Returns {agent, session, previousSlug, currentSlug} and sends a project event. 400 without slug or for an unknown project.

DELETE /agents/:agent/sessions/:session/project ​

Clears the pin. Returns {agent, session, cleared: true, previousSlug} and sends a project event.

Attachments ​

Files for a chat turn travel in two steps: upload first, then name the upload in attachments on POST /chat/send or POST /chat/send-sync.

POST /attachments ​

Uploads one file as the raw request body. The file name goes into the X-Somora-Filename header, URL-encoded. An upload larger than the largest accepted file (50 MB, the size an image may have before it is scaled) is stopped while it streams, with 400.

bash
curl -H "Authorization: Bearer $KEY" -X POST $BASE/attachments \
     --data-binary @./screenshot.png \
     -H "Content-Type: image/png" \
     -H "X-Somora-Filename: screenshot.png"
json
{ "hash": "9f2c…", "name": "screenshot.png", "mime": "image/png",
  "kind": "image", "size": 184320 }

The type is read from the bytes, not from the name. The same content is stored only once. Pass the whole object on in attachments.

StatusWhen
400No body, or the file breaks a limit from attachments in the config.
415A multipart/form-data upload. Send the raw bytes.

GET /attachments/:hash ​

The bytes of an uploaded file, for showing what the agent saw. :hash is the 64-character hash. 400 for a malformed hash, 404 when it is unknown.

Files ​

GET /files/view ​

Describes a file on the server by absolute path, and returns its text when it is a text file. The shipped clients use it to open paths that agents mention in chat.

QueryRequiredMeaning
pathyesAbsolute path. A leading ~ is expanded.

The route follows the same rules as the file_read tool: what an agent may read, you may view. Links are resolved before the check.

FilekindThe response carries
.md, .markdownmarkdowncontent
.txt, .log, other texttextcontent
.json, .jsonl, .yaml, .yml, .toml, .svgcodecontent
PNG, JPEG, GIF, WebPimageurl, mime
MP4, MOV, WebMvideourl, mime
WAV, MP3, OGG, FLAC, M4Aaudiourl, mime
PDFpdfurl, mime
anything elsebinaryurl, mime

Media and unknown files are recognised from their bytes, not from the extension. An .svg is shown as its source, because it can carry script.

json
{ "path": "/home/me/somoraworkspace/report.md", "kind": "markdown",
  "ext": ".md", "bytes": 4321, "content": "# Report\n…",
  "truncated": false, "downloadUrl": "/files/raw?download=1&path=…" }
json
{ "path": "/home/me/somoraworkspace/shots/run-12.png", "kind": "image",
  "ext": ".png", "bytes": 184320, "mime": "image/png",
  "url": "/files/raw?path=…", "downloadUrl": "/files/raw?download=1&path=…" }

Text is cut at 200 000 characters; truncated is then true and truncated_reason says why. Every response has downloadUrl.

StatusWhen
400path is missing, relative, a folder or not a regular file.
403The read rules forbid the path.
404The file does not exist.

GET /files/raw ​

The bytes of a file: media to show in place, and a download for everything else. Same path rules as GET /files/view.

QueryRequiredMeaning
pathyesAbsolute path.
downloadno1 forces a download.
  • Range requests work (206, 416, and bytes=-N for the end), so a video player can seek. There is no size limit.
  • Content-Type comes from the bytes, with X-Content-Type-Options: nosniff.
  • Only images, video, audio and PDF are served inline. Everything else is an attachment.

Errors as for GET /files/view.

Images ​

Image generation. The routes that list, generate or ask a provider answer 503 unless imageGen.enabled is set and at least one model is configured.

GET /images/status ​

Whether image generation is on. Returns {enabled: false}, or {enabled: true, outputDir, maxImagesPerTurn, models: [{name, label, model, provider, defaults}]}.

GET /images ​

Every generated media record, images and videos, newest first; GET /media?kind=image lists images only.

QueryDefaultMeaning
querynonePart of the prompt, case-insensitive.
model, agentnoneOnly this model or agent.
since, untilnoneYYYY-MM-DD.
limit60At most 200.
offset0For paging.

Returns {total, offset, items, totalBytes}. total counts all matches, not only this page. The items are media records, see GET /media.

GET /images/:id ​

One record: prompt, model, specs, path, type, size, cost, agent and session.

GET /images/:id/file ​

The image bytes. ?download=1 forces a download. 410 when the record exists but the file was moved or deleted. Files are addressed by record id, never by path.

GET /images/models/:name/capabilities ​

What a configured image model accepts.

FieldMeaning
model, defaultsThe configured name and its default specs.
sourceWhere the answer comes from: catalog, config or unknown.
knownWhether anything is known about the model.
valuesAllowed values per spec field. A field that is missing here has no known limit: offer free input for it.
recommended, supportedThe provider's recommended values and supported fields, or null.
maxN, maxReferencesMost images per request and most reference images, or null.
sizeAlsoAcceptsNamed ratios the endpoint takes in size, or null.

404 for an unknown model name.

GET /images/catalog ​

The image models a provider offers right now. ?provider=<name> picks the provider; the default is the one behind the first configured model. Returns {provider, models: [{id, name?}]}. The config still decides which models somora calls. 400 for an unknown provider.

POST /images/generate ​

Generates images.

Body fieldRequiredMeaning
promptyesWhat to draw.
modelnoA configured model name.
resolution, aspect_ratio, size, quality, output_format, background, output_compression, seed, n, steps, cfg, guidancenoSpecs. Which ones a model takes is in its capabilities.
reference_imagesnoImages as base64 strings. The image_generate tool takes file paths instead.
extranoProvider fields somora has no name for, passed through as given, as the tool's extra.
sessionnoRecorded with the image.

Returns {images: [record], costUsd, warnings?, fellBackFrom?}. warnings lists what the endpoint did differently than asked, for example a size it replaced, and every body field the route did not use (ignored: <field>). fellBackFrom names the models that were unavailable when a backup model was used. A save_to field is not used: every image lands in the configured images folder.

StatusMeaning
400Something the caller can fix. The message names the field and the values that work.
502The provider failed.
503The model is configured but not loaded right now.

Error bodies carry kind beside error.

DELETE /images/:id ​

Forgets the record. The file on disk is kept. Returns {ok, path, fileKept: true}.

Media ​

One gallery over everything somora generated: images and videos.

GET /media ​

QueryDefaultMeaning
kindbothimage or video.
agentnoneOnly this agent.
querynonePart of the prompt.
limit60At most 200.
offset0For paging.

Returns {total, offset, items, totalBytes}. A media record:

FieldMeaning
id, kind, createdAtkind is image or video. A record without kind is an image.
prompt, modelName, modelId, provider, specsHow it was made.
path, filename, mime, bytesThe file.
width?, height?, durationSec?Size, and length for a video.
thumbPath?, thumbMime?A video's still image.
costUsd?, agent?, session?, references?Cost, who made it, reference images.
batchId, batchIndex, linkedToGrouping of images made in one request.

GET /media/:id ​

One media record. 404 when unknown.

GET /media/:id/file ​

The bytes, served inline. ?download=1 forces a download. Range requests work (206, 416), so a video player can seek. 410 when the file left the disk.

GET /media/:id/thumb ​

A video's still image, image/webp unless the record says otherwise. Same behaviour as /file. A video without a still gets one cut on the first request. 404 only when that fails.

DELETE /media/:id ​

Removes the record. Returns {ok: true} or 404.

Video ​

Video generation runs as jobs. A request starts one and returns at once. It is on when videoGen.enabled is set and a model is configured. When the file is ready it becomes a media record, and an agent that started the job is woken with a turn whose origin is {kind: "wake", about: "job"}.

GET /video/status ​

Whether video generation is on, and the jobs.

QueryMeaning
agentOnly this agent's jobs.

Returns {enabled: false, reason} when it is off. Otherwise:

FieldMeaning
active, limitJobs running now and the most allowed at once (videoGen.maxConcurrent).
models[{name, label, model, provider, wire, media, params}]. media lists the input files the model takes, by type: {kind, max?, min?, max_seconds?}. params lists its parameters as the provider catalog or allow.parameters describes them: {type?, values?, min?, max?, default?, note?} per name.
jobsEach {id, providerJobId, modelName, provider, prompt, specs, status, progress?, queuePosition?, error?, createdAt, updatedAt, mediaId?, path?, agent?, session?, references?}.

A job's status is queued, in_progress, completed or failed. mediaId appears once the file is stored. It is the id for GET /media/:id.

POST /video/generate ​

Starts a job.

Body fieldRequiredMeaning
promptyesWhat to show.
modelnoA configured model name.
seconds, size, aspect_ratio, audio, quality, seednoSpecs.
extranoThe model's own parameters, for example {"subject": "right"}. Checked against what the model takes, like the specs.
reference_imagesnoImages as base64 strings or {data, filename}: one is the opening frame, two are opening and closing frame.
medianoInput files by meaning: [{type, data, filename?, seconds?, strength?}], data in base64 or as a data: URI. Types as in the video guide, "Input files". Not together with reference_images.
agent, sessionnoWho is woken when the job ends.

Returns {job}. Follow it with GET /video/status. A body field the route did not use is listed in job.warnings as ignored: <field>.

StatusMeaning
400A bad request, or the provider refused it with a 4xx other than 401, 403 and 429. The provider's message is passed on.
429All job slots are busy.
502The provider failed, or refused for authentication or rate limits.
503Video is off, or the model is not available right now.

Voice ​

Dictation and spoken replies. Each route answers 503 when its part, stt or tts, is not enabled in the config, except GET /stt/config and GET /tts/config, which answer {enabled: false}.

GET /stt/config ​

Whether dictation is available. Returns {enabled, language} or {enabled: false}. language is the default language hint or null.

POST /stt/transcribe ​

Turns a recording into text. The body is multipart/form-data.

Form fieldRequiredMeaning
fileyesThe recording.
languagenoOverrides the configured language.

Returns {text}. 400 for a wrong body, 502 when the transcription service failed or was unreachable.

GET /tts/config ​

Whether spoken replies are available, and the defaults per client.

json
{ "enabled": true,
  "formats": ["audio/wav", "audio/opus", "audio/mp4"],
  "language": "de", "voice": null,
  "clients": {
    "web":    { "autoPlayVoiceReplies": false, "allowUserOverride": true },
    "mobile": { "autoPlayVoiceReplies": false, "allowUserOverride": true } } }

formats is only audio/wav when re-encoding is off. Returns {enabled: false} when spoken replies are off.

POST /tts/synthesize ​

Speaks a text. The response body is the audio. The format is chosen from the Accept header.

Body fieldRequiredMeaning
textyesAt most 4000 characters.
voice, languagenoOverride the configured ones.
agentnoUse this agent's voice settings.
Response headerMeaning
Content-Typeaudio/wav, audio/opus or audio/mp4.
X-Tts-Cachehit or miss.
X-Tts-Cache-KeyThe key under which the audio is cached.
X-Tts-Duration-MsThe length, when it is known.

400 for a missing or too long text, 502 when the speech service failed.

GET /tts/cache/:filename ​

A cached audio file. File names have the form <64 hex characters>.<wav|opus|m4a>. This is the URL in assistant_audio.url, so a client can hand it straight to an audio player. A Range: bytes=N- request works, for seeking.

400 for another file name, 404 when the file is not cached.

POST /voice/turn ​

Audio in, audio out, in one request: transcribes the recording, runs a normal turn with it, and speaks the reply. The turn shows up in the session and on its stream like any other. The body is multipart/form-data.

Form fieldRequiredMeaning
audioyesThe recording.
agentnoAgent name. When left out, the alphabetically first agent is used.
sessionnoDefault main. A slug that does not exist is created. An exact id that does not exist answers 404.
voice, languagenoFor the spoken reply. Default: tts.voice, tts.language.

The audio format is chosen from the Accept header.

json
{ "ok": true, "agent": "<your-agent>", "session": "main",
  "transcript": "What time is it?",
  "text": "It is 10:29.",
  "audio": { "url": "/tts/cache/abc123….opus", "mime": "audio/opus",
             "durationMs": 1800, "cacheKey": "abc123…" } }

The reply is always spoken, whatever a client's auto-play setting says. A reply that is mostly code or tables is replaced by a short spoken note that points to the chat.

502 when transcription returned nothing, the agent gave no reply or speech failed. 404 for an unknown agent or an exact session id that does not exist.

assistant_audio SSE event ​

After a turn whose reply was spoken, the session's stream sends:

event: assistant_audio
data: {"turnId":"…","url":"/tts/cache/….opus","mime":"audio/opus","durationMs":1800,"cacheKey":"…"}

Match it by turnId and offer a play button on that reply. The event is also stored, so GET /chat/history returns it.

Realtime voice ​

A standing call with an agent that you can interrupt. Off unless realtimeVoice.enabled is set. This is separate from dictation and spoken replies.

GET /voice/status ​

Whether calls are possible, and with whom.

json
{ "enabled": true, "provider": "openai", "model": "gpt-realtime-2.1-mini",
  "maxCallMinutes": 20, "agents": ["<your-agent>"], "calls": [] }

agents lists who can be called: agents whose agent.yaml has voice.enabled: true. calls lists the calls in progress. With the feature off the answer is {"enabled": false, "agents": []} with status 200.

GET /voice/instructions?agent=<name>&session=<slug> ​

What the speaking model would be told, without starting a call.

json
{ "agent": "<your-agent>", "session": "main",
  "text": "You are <your-agent>, speaking out loud …", "chars": 1528,
  "source": "derived", "voice": "ash", "language": "de", "consultPolicy": "always" }

source is derived when the text is built from the agent's persona and its voice: settings, or VOICE.md when the agent has that file. 503 when realtime voice is off, 404 when the agent has no voice.

WS /voice/attach?agent=<name>&session=<slug> ​

The call itself, as a WebSocket with JSON text frames in both directions. session defaults to main.

Client to server:

FrameMeaning
{"type": "audio", "base64": "…"}Microphone audio: PCM16, 24 kHz, mono.
{"type": "interrupt"}Stop the model's speech.
{"type": "hangup"}End the call.

Server to client:

FrameMeaning
{"type": "ready", "call", "rateHz": 24000}The call is up.
{"type": "audio", "base64", "rateHz"}Speech to play.
{"type": "state", "call"}The call's state changed.
{"type": "event", "event", "call"}Something happened. event.kind is ready (the provider session is up), user_speech, user_transcript, model_speech, model_transcript, tool_call, interrupted, usage, notice (message: a warning from the voice service, each once), closed or error (message, fatal). model_transcript carries responseId when the service names its answers.

call is {id, target, state, startedAt, consults, spokenTurns, handoverTo?, lastError?}. state is connecting, listening, consulting, speaking or closed. consulting means the agent is running a real turn in the session. target changes when the call is handed to another agent.

Note

Keep sending audio while nobody speaks. The model ends a turn on silence, not on missing packets.

Closing the socket ends the call. Work the agent already accepted keeps running. The socket closes with code 1008 when realtime voice is off or the call cannot start, and 1000 when the call ended.

Tmux integration ​

Terminals in the browser: tmux sessions on the server, and a plain shell.

GET /tmux/sessions ​

The tmux sessions on the server.

bash
curl -H "Authorization: Bearer $KEY" $BASE/tmux/sessions

Returns {sessions: [{name, windows, activeCommand, activeTitle, createdEpoch, lastActivityEpoch, sessionId, origin?}]}. The two …Epoch fields are in seconds. origin says which agent and session created the tmux session, when somora did.

WS /tmux/attach?session=<name> ​

A WebSocket to tmux attach-session -d -t <name>. A session somora created is attached with -f ignore-size, so the viewer never changes its size.

DirectionFrameMeaning
server to clientbinaryTerminal output.
client to serverbinaryKeyboard input.
client to servertext {"type":"resize","cols":N,"rows":N}The terminal's size. Send it on open and when it changes; one sent before the server's terminal is up is applied when it starts.
server to clienttext {"type":"attached","sessionId":"$N","createdEpoch":N,"fixedCols":N,"fixedRows":N}Attached; names the session (tmux's id and start second), so a client can tell a session started anew under the same name. fixedCols and fixedRows come for a session somora created: show exactly that size, the window plus its status line.
server to clienttext {"type":"ping"}Sent every 25 seconds.

Any message from the client counts as a sign of life. After 80 seconds without one the server closes the socket with code 4000, so answer each ping, for example with {"type":"pong"}. Code 1008 means the session name is invalid or unknown, 1011 that tmux could not start, 1000 that tmux exited.

WS /terminal/attach ​

A WebSocket to a fresh shell in the default workspace folder, without tmux. Same frames, pings and close codes as /tmux/attach. The shell ends when the socket closes.

Browser ​

The shared browser that agents drive and people can watch and take over. With browser.enabled off, the routes that change something answer 503, and the status and its stream report {enabled: false, browsers: [], warnings: []}.

GET /browser/status ​

The open browser windows.

json
{ "enabled": true, "headed": "headless",
  "browsers": [
    { "view_id": "profile:team@<your-agent>", "agent": "<your-agent>",
      "browser_id": "profile:team", "profile": "team", "ephemeral": false,
      "state": "running", "control": "agent_control",
      "tabs": [ { "tab_id": "t1", "url": "https://example.com", "title": "Example",
                  "agent": "<your-agent>", "generation": 3 } ],
      "last_used": 1789299999000 } ],
  "warnings": [] }
FieldMeaning
browsersOne entry per window, not per browser process. view_id is <browser_id>@<agent>. Agents that share a profile share a process and have one window each.
controlagent_control, handoff_requested, human_control or paused. human_by and handoff are added when they apply.
tabs{tab_id, url, title, agent, session?, generation, emulation?}. emulation shows a tab's device and locale.
headedHow windows are shown on the server, following browser.headed: headless, display, xvfb or unavailable.
warningsWhat needs fixing, for example that no Chromium was found.

Stopped browsers are not listed, except one that still holds an open hand-over.

GET /browser/stream ​

The browser status as Server-Sent Events.

EventWhenData
browsersOn connect, and whenever a window, tab or control state changes{enabled, browsers, warnings} as in GET /browser/status
heartbeatEvery sse.heartbeatMsThe current time in ms

Each browsers event is a complete snapshot that replaces the one before.

POST /browser/op ​

Runs one operation of the browser tool for an agent, in that agent's window.

Body fieldRequiredMeaning
agentyesThe agent.
sessionnoIts session.
inputyesThe tool's arguments, for example {"op": "open", "url": "…"} or {"op": "snapshot", "tab": "…"}.

Returns the tool's result object (ok, error, hint, tab, snapshot and so on). A refusal by the tool is still a 200, and so is an unknown op: ok: false with the valid ones in hint. 400 without an input.op, 404 for an unknown agent.

POST /browser/:id/restart ​

Reopens a stopped browser with a blank page and the same profile. :id is a window id or a browser id. Every window that existed comes back with its control state. Nothing is replayed. Returns {ok: true}, or 409 {error} when the browser is unknown or its shared profile was removed from the config.

POST /browser/:id/control ​

Takes a window over, or hands it back to its agent. :id is a window id such as profile:team@<your-agent>. A bare browser id works while only one agent has a window on it.

Body fieldRequiredMeaning
modeyeshuman takes control: the agent's operations in that window are refused until it is handed back. agent hands it back.
bynoWho acts. With it, somebody else's control cannot be handed back.
handoffIdnoThe id of the hand-over being answered, from the status. Prevents a late button press from waking the agent twice.

Returns {ok: true, control}.

Handing back with an open hand-over wakes the agent that asked for it, once, in its session. Without one, a hand-back after real activity wakes the window's own agent in the session of the last tab it used.

StatusMeaning
400mode is neither human nor agent.
404The browser is not running.
409A state conflict, such as a handoffId that does not match.

GET /browser/attach (WebSocket) ​

The live picture of one browser window, with input.

QueryMeaning
viewThe window id <browser_id>@<agent>. browser is accepted as the parameter name too.
tabThe tab to show first. Optional.
viewerAn id for this viewer. Optional.

Binary frames from the server carry one JPEG each: [u32 BE header length][JSON header][JPEG]. The header is {tabId, generation, seq, url, cssWidth, cssHeight, scrollX, scrollY, ts}. The frame rate follows browser.stream.maxFps (default 15, at most 20). Frames are skipped for a viewer with more than 2 MB waiting to be sent.

Text frames from the server:

typeDataMeaning
ready{browser, tabId, viewerId}Attached, or switched to another tab.
tabs{browser}Tabs or control changed.
control{control}Answer to a control request.
notice, error{text}A hint, or a failed request.
pingnoneAnswer with {"type":"pong"}. 80 seconds of silence close the socket.

Text frames from the viewer:

typeDataMeaning
control{mode: "human"|"agent", handoffId?}Take over or hand back.
tab{tabId}Show another tab.
navigate{url}Open a URL. Same rules as for the tool.
newtab, closetabnone, {tabId}Open or close a tab.
resize{width, height}Resize the page.
mousemove, click, mousedown, mouseup{x, y, button?, clickCount?}Pointer input, in CSS pixels of the shown page.
wheel{x, y, deltaX, deltaY}Scrolling.
text{text}Typed or pasted text.
key{key, ctrl?, alt?, shift?, meta?, action?}A key by its Playwright name, such as Enter or Control+a.
back, forward, reloadnoneHistory and reload.

Everything except control and tab is applied only while this viewer holds control; otherwise it gets a notice. Input other than navigate, newtab, closetab, tab and control must carry frameTab and generation from the frame on screen, and input for an older picture is refused.

Close codeMeaning
1008Bad request: unknown browser, browser switched off, or more than 64 inputs waiting.
1009A message larger than 64 KiB.
1012The server is shutting down.
4000No sign of life for 80 seconds.
4001The tab or the browser was closed.

Sentinel ​

Sentinel wakes agents on a schedule, or when a check script sees that something happened. These routes list and manage the triggers. The same operations are available to agents as the sentinel tool.

GET /sentinel/triggers ​

All triggers, newest first.

QueryMeaning
ownerOnly triggers of this agent.
statusactive, paused, error or completed.
json
{ "count": 1,
  "triggers": [
    { "id": "morning-mail-summary-a7c3", "name": "morning-mail-summary",
      "ownerAgent": "<your-agent>",
      "source": { "type": "time", "spec": { "type": "daily", "time": "08:00" } },
      "evaluator": { "type": "none" },
      "dispatch": { "agent": "<your-agent>", "session": "morning-routine",
                    "prompt": "Check the inbox …" },
      "createdAt": "2026-05-17T11:00:00.000Z", "status": "active",
      "fireCount": 5, "lastSuccessAt": "2026-05-17T08:00:01.234Z",
      "errorStreak": 0, "nextFireAt": "2026-05-18T08:00:00.000Z" } ] }

A check trigger (docs/sentinel.md, Check triggers) has a check source and an evaluator of ready, or decision for a judged check ({type: "decision", questions, wake, perItem?}; perItem: true judges each item of the data on its own):

json
{ "source": { "type": "check", "description": "the model server answers on glm",
              "interval": "15s", "mode": "once", "deadline": "2026-05-17T13:00:00.000Z",
              "script": { "file": "check.py", "lang": "python", "sha256": "…" } },
  "evaluator": { "type": "ready" } }

A check trigger has no nextFireAt. Instead the list and the single trigger carry check, read from its check state:

json
"check": { "checks": 412, "wakes": 3, "errorsInARow": 0,
           "nextCheckAt": "2026-05-17T12:14:30.000Z",
           "last": { "at": "2026-05-17T12:14:15.000Z", "ms": 104, "ok": true,
                     "ready": false, "summary": "profile is qwen, switching" },
           "lastDecision": { "at": "…", "question": "urgent", "value": 0.07,
                             "detail": "probability of yes, wakes from 0.8" } }
FieldMeaning
checks, wakesCounted apart: most checks wake nobody.
errorsInARowCheck errors since the last good check.
nextCheckAtOnly while the trigger is active.
lastThe last check: ok, then ready, summary, dataPreview, final, decision, warning, or error and errorClass. With perItem, decision.value is the highest answer and decision.detail lists each item's. warning: a judged check without perItem got a list of several items.
lastDecisionA judged check's last answer, kept when later checks bring no new data.
effectiveIntervalSet when config.yaml raised the interval limit above the trigger's own interval.

GET /sentinel/triggers/:id ​

One trigger as {trigger}.

GET /sentinel/triggers/:id/history ​

The fires of a trigger, newest first. ?limit=N, default 50, at most 200.

json
{ "count": 2,
  "entries": [
    { "firedAt": "2026-05-17T08:00:01.234Z", "scheduledFor": "2026-05-17T08:00:00.000Z",
      "outcome": "success", "taskId": "task-…" },
    { "firedAt": "2026-05-16T08:00:00.500Z", "scheduledFor": "2026-05-16T08:00:00.000Z",
      "outcome": "skipped", "skipReason": "cooldown (1320s remaining)" } ] }
outcomeComes with
successtaskId
errorerror. stopped by the user when a person stopped the turn.
skippedskipReason. removed from the queue by the user when a person removed the waiting fire.
updatednote: what changed and by whom. A check trigger's new script or settings, not a fire.
judgednote: what the decision model answered in a judged check, and whether it woke the agent. Only checks that asked the model, not a fire.

A check trigger that stops records an error entry starting with check paused:.

catchUp: true marks a fire made up for after a restart, testMode: true one started through the test route. 404 once the trigger is deleted.

GET /sentinel/triggers/:id/script ​

A check trigger's script copy, read only.

json
{ "file": "check.py", "lang": "python", "sha256": "…", "text": "#!/usr/bin/env python3\n…", "matches": true }

matches: false means the copy was changed outside somora; the trigger stops at its next check. A missing copy answers without text and with error. 400 for a time trigger, 404 for an unknown id.

POST /sentinel/triggers/:id/pause ​

Pauses a trigger until it is resumed. Returns {ok: true}.

POST /sentinel/triggers/:id/resume ​

Sets a trigger back to active, clears its error count and works out its next fire. Returns {ok: true}. 400 when the schedule cannot be computed.

POST /sentinel/triggers/:id/test ​

Fires a trigger now, ignoring cooldown and daily cap. The agent gets the same prompt as on a real fire. Returns {ok: true, hint}.

For a check trigger it runs the script copy once instead (a dry run): nothing is saved, nobody is woken, the script's state folder is not touched. Returns {ok, dryRun: {ok, art, ms, answer?, error?, errorClass?, stderr?, decision?, items?, more?, warning?, verdict}}. items (with perItem): [{key, value, wake}] or [{key, error}] per item; more: items over sentinel.checks.maxItemsPerCheck.

DELETE /sentinel/triggers/:id ​

Removes a trigger and its history. Returns {ok: true}, or 404 when it is already gone.

GET /sentinel/status ​

Whether the scheduler runs and when the next trigger is due.

json
{ "started": true, "nextFireAt": 1779013800000 }

Creating triggers ​

There is no route to create a trigger. Create it through the tool, so that the same limits apply as for an agent:

bash
curl -H "Authorization: Bearer $KEY" -X POST $BASE/agents/<your-agent>/tools/sentinel \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "create",
    "name": "morning-mail-summary",
    "intent": "Daily inbox digest at 8",
    "source": { "type": "time", "spec": { "type": "daily", "time": "08:00" } },
    "dispatch": {
      "agent": "<your-agent>",
      "session": "morning-routine",
      "prompt": "Check the inbox, group by topic, tell me what is important."
    }
  }'

The tool's actions are create, dry_run, update, list, get, pause, resume, delete, test, history and purge_completed.

A2A endpoint ​

somora's agents as A2A agents (A2A). These paths are the only data routes the login key does not guard: the cards are public, and the JSON-RPC endpoint checks the peer tokens of a2a.peers (Authorization: Bearer <token>). Without peers the cards and the endpoint answer 404; /a2a/files/<token> links keep working until they expire.

GET /a2a/agents/:agent/.well-known/agent-card.json · GET /a2a/agents/:agent/.well-known/agent.json ​

The agent's Agent Card, for agents with a2a: true; both paths answer the same. GET /.well-known/agent-card.json and GET /.well-known/agent.json give the card of a2a.defaultAgent.

json
{ "name": "nova", "description": "…", "version": "2026.1016.8",
  "supportedInterfaces": [{ "url": "https://<host>:18737/a2a/agents/nova", "protocolBinding": "JSONRPC", "protocolVersion": "1.0" }],
  "capabilities": { "streaming": true, "pushNotifications": false },
  "defaultInputModes": ["text/plain", "image/png", "image/jpeg", "image/gif", "image/webp", "application/pdf"],
  "defaultOutputModes": ["text/plain", "image/png", "image/jpeg", "image/webp"],
  "security": [{ "bearer": [] }] }

POST /a2a/agents/:agent ​

JSON-RPC 2.0. Methods in A2A 1.0 naming and their 0.3 names; the answer uses the naming of the request.

Method0.3 nameDoes
SendMessagemessage/sendA new task, or the answer to an open question in the same contextId. Waits up to a2a.replyTimeoutSeconds unless configuration.returnImmediately (0.3: blocking: false).
SendStreamingMessagemessage/streamThe same as an SSE stream: the task, statusUpdate, artifactUpdate with append, until the task ends or asks back.
GetTasktasks/getThe task by id.
ListTaskstasks/listThe peer's tasks for this agent, optionally by contextId.
CancelTasktasks/cancelStops the turn; -32002 when the task already ended.
SubscribeToTasktasks/resubscribeThe stream of a running task.
ErrorMeaning
HTTP 400, -32700The body is not JSON.
HTTP 401, -32050No token or an unknown one.
HTTP 404, -32601A2A is not enabled here (no a2a.peers).
HTTP 404, -32001No such agent for this peer.
HTTP 413, -32600The request is larger than the cap: five files at the attachments limits as base64, plus the longest text (about 214 MB by default).
HTTP 429, -32051Rate or daily limit of the peer, too many open streams (10 per peer, SendStreamingMessage and SubscribeToTask together), or too many open tasks (500).
HTTP 429, -32050Too many wrong tokens from this address.
-32001No such task (HTTP 200).
-32002CancelTask on a task that already ended.
-32004A reply naming a taskId whose task no longer waits for an answer.
-32600Not a JSON-RPC 2.0 request.
-32601Unknown method.
-32602No message text, longer than a2a.maxMessageChars, more than five files, a file beyond the limit, or a contextId that does not match the named task.

Errors without an HTTP status come with HTTP 200.

A turn for such a task carries origin: { kind: "peer", peer, contextId, taskId } in its user_message events, and from_system: "peer".

POST /agents/:agent/rename ​

Renames an agent, somora's own or external (Renaming an agent). Body { "to": "<new>", "dryRun": true }; without dryRun it renames.

json
{ "ok": true, "from": "claw", "to": "kai", "kind": "external", "dryRun": false,
  "changes": ["folder agents/claw → agents/kai", "team.yaml: agents.claw → kai",
              "config.yaml: external.systems.openclaw.agents.claw → kai"],
  "warnings": [] }

A refused or failed rename answers with the same report, ok: false and error saying why:

StatusWhen
400An invalid name, or the old one.
404Unknown agent.
409The agent is busy, the name is taken, another rename of it runs, or an entry is reached through a YAML anchor, alias or merge key.
500A file would not load after the rename, or a step failed and everything was put back.

GET /a2a/files/:token ​

One file behind a download link (A2A): an attachment somora sends to an external agent, or an image in an answer to a peer. Open without the login key; the signed token names the file and expires after an hour. 404 for a token that is not one, 410 for an expired one.

File parts in a task are taken as { raw, mediaType, filename } (bytes, base64) or { url, mediaType, filename } (fetched with the web_fetch guard), in 0.3 as { kind: "file", file: { bytes | uri, mimeType, name } }. An answer with an image carries { url, mediaType, filename }.

GET /agents/:agent/a2a · PUT /agents/:agent/a2a ​

The agent's A2A switch: { agent, on, available, peers, url?, problem? }. PUT takes { on: boolean }, writes a2a: into agent.yaml and answers { ok: true, agent, on, available, peers, url?, problem? }.

StatusWhen
400The body is not { on: boolean }.
404Unknown agent.
409on: true for a builder, or the agent is being renamed.
500agent.yaml could not be written, for example because it is not valid YAML.

External agents ​

Agents of other agent systems, reached over ACP (see External agents). They appear in GET /agents with kind: "external", and chat, history, streams, sessions, reset and archive work for them as for any agent. The routes that change a model, thinking level or sampling, and compaction, answer 409 for them. Their GET …/model, …/thinking and …/sampling return source: "external".

Their entry in GET /agents carries external.a2a: true when the agent takes work from agents over A2A. Such work arrives through the usual routes (/chat/send-sync for agent_ask, /spawn-async for a sub-agent). In its session, the turn's agent start and end events carry external.via: "a2a", and engine_meta rows with engine a2a and itemType: "a2a_task" report the task's progress (payload.text, and payload.state such as working). Taking a running agent_ask back (DELETE /chat/queue/:id with withdraw_running) stops the task and answers stopped: true.

A message the agent sends on its own between turns (Messages it sends on its own) arrives on the session's stream like a turn nobody started: an agent start with external.unprompted: true, an engine_meta with engine acp and itemType: "external_unprompted" (payload.text says who wrote), its tool calls and chat events, and an agent end. History stores it between turn_start and turn_end like any answer.

GET /external ​

The configured systems, their agents and open connections.

json
{ "idleMinutes": 10, "questionTimeoutMinutes": 10,
  "systems": [ { "name": "openclaw", "protocol": "acp",
    "transport": { "resource": "agents-vm" },
    "agents": [ { "name": "claw",
      "badge": { "label": "OpenClaw", "badge": "🦞", "badgeImage": null, "version": "2026.10.3" },
      "agentInfo": { "name": "openclaw-acp", "title": "OpenClaw ACP Gateway", "version": "2026.10.3" },
      "profile": "openclaw", "capabilities": { "loadSession": true },
      "connections": [ { "sessionId": "…", "where": "agents-vm", "idleMs": 48000 } ] } ] } ],
  "ignored": [] }
FieldMeaning
agentInfo, capabilitiesWhat the agent said about itself when somora last connected. null before the first connection.
profileThe quirks profile in use: openclaw, hermes or generic.
connectionsOpen ACP connections, one per somora session, with the remote session id and how long each has been idle.
ignoredExternal agent names a somora agent already has. Those entries are not used.

GET /external/:system/badge ​

The badge image configured for a system (badge: with a png, svg or webp path, at most 256 KB). 404 when the system has no badge image or the file is missing, 422 when it is larger than 256 KB or not a file.

GET /agents/:agent/sessions/:session/question ​

The session's open question, or { "question": null }: an external agent's permission request, a builder's ask_user question, or a question that does not wait. That last kind carries async: true and expiresAt: 0, and with several questions asked at once parts ([{question, header?, options, multiple}], the first repeated at the top). It stays open between turns, after a reload and a restart. details, when the agent gave it, is what the person decides on, in full (markdown).

json
{ "question": { "id": "…", "question": "claw asks for permission: exec: rm -rf /tmp/x",
  "header": "Permission", "multiple": false, "expiresAt": 1792157891000,
  "options": [ { "label": "Allow once", "description": "allow_once" },
               { "label": "Reject", "description": "reject_once" } ] } }

POST /agents/:agent/sessions/:session/questions/:id/answer ​

Answers the open question with { "answers": ["Allow once"] }, the labels of the chosen options, and optionally text, a free-text answer. Returns { ok: true }; every client of the session gets question_answered. 404 for an unknown session, or when no question with that id is open (answered already, or timed out).

A question that does not wait takes the same body, or parts with one {answers?, text?} per question. The answer is sent as the person's next message, the way POST /chat/send sends a typed one: the chosen labels for one question, each question with its answer for several. 400 when nothing was chosen or typed.

While a turn of the session is running, usually the one that asked, the answer goes into that turn the way a steered message does (POST /chat/send with steer: true): every client gets steer_queued, and the response is { ok: true, sent: true, steered: true, steerId, turnId, text } with the running turn's id. Otherwise it starts a turn of its own: { ok: true, sent: true, steered: false, turnId, text }. Any message the person sends to the session with POST /chat/send answers such a question too and removes it.

External MCP servers ​

State and control of the external MCP servers from mcp.servers in the config. All three routes answer 503 when none is configured.

GET /mcp/status ​

The state of each server.

json
{ "enabled": true,
  "servers": { "<name>": { "state": "connected", "toolCount": 12, "transport": "streamable-http",
                           "lastConnectedAt": 1789299000000, "consecutiveFailures": 0 } } }

state is pending, connected, failed, needs-auth or disabled. lastError is added after a failure. With needs-auth, loginHint says how to log in again when the server's config knows it (the Claude Design preset does).

POST /mcp/servers/:name/reconnect ​

Drops the connection to one server and connects again at once. Returns {ok: true, status} with the server's new state. 400 when the name is unknown or the server is disabled in the config.

POST /mcp/call ​

Calls one tool of an external server directly.

Body fieldRequiredMeaning
serveryesThe server's name.
toolyesThe tool's name on that server.
argsnoThe tool's arguments as an object.
timeoutMsnoHow long to wait.

Returns {isError, text, images: [{data, mimeType}]}. 400 without server or tool, 502 when the call failed.

Note

This route does not apply an agent's tool rules. It is meant for the server's own use and for an operator.

Web bundle ​

GET /web/ ​

The web client, as static files from the same address as the API. GET /web redirects here.

GET /mobile/ ​

The mobile app, served the same way. GET /mobile redirects here. A custom client needs neither: everything they do goes through the routes on this page.

See also ​