{ "openapi": "3.1.0", "info": { "title": "ADF Daemon API", "version": "0.2.0", "summary": "HTTP API of the headless ADF runtime (adf daemon).", "description": "The daemon is a headless ADF runtime: it loads agents from .adf files, runs them, streams their events and resolves human-in-the-loop requests. This document is the contract; docs/daemon/api-reference.md and api-reference.html are generated from it (`npm run docs:api`).\n\n**Authentication.** Every route except `GET /health` (and `HEAD /health`) requires `Authorization: Bearer `: the per-install token in `/daemon-token` (print it with `adf daemon token`) or `ADF_DAEMON_TOKEN`. Local adf clients send it automatically. Missing or wrong: 401 `unauthorized`.\n\n**Request guard.** A Host header that does not name this daemon (403 `host_not_allowed`, DNS-rebinding protection) and browser cross-site requests — a foreign `Origin` or `Sec-Fetch-Site: cross-site|same-site` (403 `cross_origin`) — are refused on every route. No CORS headers are ever sent.\n\n**Errors** are JSON `{ \"error\": \"\", \"code\": \"\" }`. Every error body carries a stable machine-readable `code`: a specific one where the route defines it (listed per response), otherwise the status default: 400 `bad_request`, 401 `unauthorized`, 403 `forbidden`, 404 `not_found`, 405 `not_supported`, 409 `conflict`, 500 `internal_error`, 502 `upstream_error`, 503 `unavailable`. Branch on `code`, not on the message. A body Fastify cannot parse — malformed JSON, or an empty body sent with `Content-Type: application/json` — is refused before the route with 400 in Fastify's shape `{ \"statusCode\": 400, \"code\": \"FST_ERR_CTP_EMPTY_JSON_BODY\", \"error\": \"Bad Request\", \"message\": \"…\" }`: send no Content-Type (or `{}`) on bodiless POSTs.\n\n**Local-only routes.** Owner identity secrets (`POST /identity/create|restore|unlock|lock|confirm-backup`) and `POST /daemon/shutdown` answer callers on the daemon's own machine only (403 `loopback_only`). A request carrying a proxy header (`Forwarded`, `X-Forwarded-For|Host|Proto`, `X-Real-IP`, `Via`) is never local, whatever its peer address: forwarded headers can only take \"local\" away, never grant it. Behind a same-host reverse proxy set `ADF_DAEMON_BEHIND_PROXY=1`: these routes then also need `X-ADF-Local-Proof`, a secret the daemon writes at every start to `/daemon-local-proof` (0600), which the adf CLI and terminal app on that host send automatically to their own daemon. Run these commands on the daemon host, against its loopback port, not through the proxy.\n\n**Secrets.** Credential and identity reads return metadata only; stored values and key material never leave the daemon. The owner seed phrase appears in exactly one response (`POST /identity/create`).\n\n**Agents** are addressed by id, handle or name (`{id}`). Loop-aware routes take `loop` (absent = `main`).", "license": { "name": "MIT", "identifier": "MIT" }, "contact": { "name": "ADF", "url": "https://github.com/christianbalevski/adf" } }, "servers": [ { "url": "http://127.0.0.1:7385", "description": "Default local daemon" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Health", "description": "Liveness. The only route that needs no bearer token." }, { "name": "Daemon", "description": "The daemon process itself: this OpenAPI document and graceful shutdown." }, { "name": "Events", "description": "Live umbilical event stream (Server-Sent Events) and per-agent replay windows." }, { "name": "Agents", "description": "Load, start, stop and inspect agents: status, config, tools, metadata, local tables, logs and usage." }, { "name": "Loops", "description": "Cognition loops: `main` plus an agent's inner loops, their persisted history, context usage and compaction." }, { "name": "Chat", "description": "Chat turns, event triggers and the agent's message inbox / outbox." }, { "name": "Files", "description": "The agent's virtual file system, including its primary document and mind." }, { "name": "Identity (agent)", "description": "An agent's own identity store: DID, keys, password and stored values (metadata only, never values)." }, { "name": "Owner identity", "description": "The owner identity on this machine (seed phrase, keychain or passphrase file). State-changing routes are loopback only." }, { "name": "Credentials", "description": "Per-agent provider, MCP and channel credentials. Writes take a value; reads return metadata only." }, { "name": "Channels", "description": "Channel adapters (Telegram, email, …) attached to an agent and their live state." }, { "name": "MCP", "description": "MCP servers attached to an agent, their live state, and the daemon-wide registrations." }, { "name": "Providers & sign-in", "description": "App-level LLM providers, model lists, agent provider configs and subscription sign-in (ChatGPT, Grok)." }, { "name": "Tasks & approvals", "description": "Human-in-the-loop: tool approvals, ask requests and suspend prompts." }, { "name": "Timers", "description": "An agent's scheduled wake-ups." }, { "name": "Templates", "description": "Agent templates new agents are created from. Every route needs a ready owner identity (409 `identity_not_ready`)." }, { "name": "Tracked folders", "description": "Folders whose agents the daemon autostarts (settings.trackedDirectories)." }, { "name": "Runtime", "description": "Runtime diagnostics, token usage and token counting, daemon-wide and per agent." }, { "name": "Network", "description": "Mesh registration, the mesh HTTP server and WebSocket diagnostics." }, { "name": "Compute", "description": "The Podman compute environment and its containers." }, { "name": "Admin", "description": "Package installs for MCP servers, channel adapters and the code sandbox." }, { "name": "Settings", "description": "The daemon settings file. Secret and identity keys are never read or written here." } ], "paths": { "/health": { "get": { "tags": [ "Health" ], "summary": "Liveness check", "description": "The only route that needs no bearer token (`HEAD /health` works the same, without a body); the Host and Origin checks still apply.", "operationId": "getHealth", "security": [], "responses": { "200": { "description": "The daemon is up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/openapi.json": { "get": { "tags": [ "Daemon" ], "summary": "This OpenAPI document", "operationId": "getOpenApiSpec", "responses": { "200": { "description": "OpenAPI 3.1 document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiDocument" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/daemon/shutdown": { "post": { "tags": [ "Daemon" ], "summary": "Stop the daemon gracefully (loopback only)", "description": "Answers 202 first, then runs the same bounded shutdown as Ctrl+C / SIGTERM: the HTTP server closes (3 s deadline), every agent is unloaded in immediate mode (running turns are cut, no 5 s grace) under a per-agent deadline (10 s, `ADF_SHUTDOWN_TIMEOUT_MS`), compute containers stop, and the process exits; the whole shutdown is capped at 20 s. `adf daemon stop` uses it; on Windows it is the only graceful way to stop a detached daemon. Local callers only (see Local-only routes: never through a proxy). No body.", "operationId": "shutdownDaemon", "responses": { "202": { "description": "Accepted; the daemon exits shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShutdownAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/LoopbackOnly" }, "405": { "description": "Shutdown is not available on this daemon", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Shutdown is not available on this daemon." } } } } }, "parameters": [ { "$ref": "#/components/parameters/LocalProofHeader" } ] } }, "/events": { "get": { "tags": [ "Events" ], "summary": "Stream live events (Server-Sent Events)", "description": "Starts with a `: connected` comment and a `stream.hello` frame, replays buffered frames after the resume cursor, then streams new ones; a `: heartbeat` comment every 30 s. Each event frame: `id: `, `event: `, `data: `. **Resume**: pass the last cursor as `?since=` or in the standard `Last-Event-ID` header (what EventSource sends on reconnect); `?since` wins when both are present. Add `?epoch=` (from `stream.hello`) so the daemon can tell you when the cursor is from an earlier run. **Control frames** (named SSE events, no `id:` line, data is not an EventFrame): `stream.hello` `{epoch, oldestCursor, latestCursor}` on every connect; `stream.gap` `{reason, epoch, requestedCursor, oldestCursor, latestCursor}` when the resume cannot be exact — `evicted` (the cursor is older than the buffer: frames were dropped) or `epoch_changed` (the daemon restarted: cursors restarted at 1, and the whole buffer is replayed). On a gap, or when `stream.hello` shows an epoch other than the one you had, reload state from the REST API. The buffer is bounded (1000 frames) and process-local: order and deduplicate by `event.agent_id` + `event.seq` (durable), and read durable history from GET /agents/{id}/loop. Events of a turn carry `event.turn_id`: the `turnId` POST …/chat and …/trigger answered with. The token goes in the Authorization header (use fetch, or an EventSource polyfill that sends headers). Event catalog: docs/guides/umbilical-events.md.", "operationId": "streamEvents", "parameters": [ { "$ref": "#/components/parameters/AgentIdQuery" }, { "$ref": "#/components/parameters/SinceQuery" }, { "$ref": "#/components/parameters/EpochQuery" }, { "$ref": "#/components/parameters/LastEventIdHeader" } ], "responses": { "200": { "description": "SSE stream (text/event-stream)", "content": { "text/event-stream": { "schema": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/EventFrame" }, { "$ref": "#/components/schemas/StreamHello" }, { "$ref": "#/components/schemas/StreamGap" } ] }, "description": "The stream's logical content: one object per SSE frame: an EventFrame per event, plus the `stream.hello` / `stream.gap` control frames. On the wire:\n\n```text\n: connected\n\nevent: stream.hello\ndata: {\"epoch\":\"6f1c…\",\"oldestCursor\":1,\"latestCursor\":41}\n\nid: 42\nevent: agent.state.changed\ndata: {\"cursor\":42,\"event\":{\"seq\":7,\"event_type\":\"agent.state.changed\",\"turn_id\":\"turn_V1StGXR8_Z5j\",…}}\n```" }, "example": [ { "cursor": 42, "event": { "seq": 7, "event_type": "agent.state.changed", "timestamp": 1790000000000, "source": "system:runtime", "agent_id": "Xk3v9QpLm2", "payload": { "state": "thinking" } } } ] } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/agents/{id}/umbilical/events": { "get": { "tags": [ "Events" ], "summary": "Catch up on the agent's in-memory replay window", "description": "Opt-in (`umbilical.log.enabled`), in-memory and bounded; nothing is persisted. Answers `log_enabled: false` with no events when the window is off. `since_seq < oldest_seq - 1` means the cursor predates the window: re-snapshot.", "operationId": "getAgentUmbilicalEvents", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "name": "since_seq", "in": "query", "required": false, "description": "Events with seq strictly greater than this", "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "description": "Max events (default 500, max 2000)", "schema": { "type": "integer", "minimum": 1, "maximum": 2000 } } ], "responses": { "200": { "description": "A page of the replay window", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UmbilicalEventsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents": { "get": { "tags": [ "Agents" ], "summary": "List loaded agents", "operationId": "listAgents", "responses": { "200": { "description": "Loaded agents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/agents/load": { "post": { "tags": [ "Agents" ], "summary": "Load an agent from an .adf file", "description": "Loading an already-loaded file returns its existing reference. Direct loads bypass the review gate unless `requireReview` is true.", "operationId": "loadAgent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoadAgentBody" } } } }, "responses": { "200": { "description": "The loaded agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRef" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ReviewRequired" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/create": { "post": { "tags": [ "Agents" ], "summary": "Create an agent from a template, then load it", "description": "Studio's \"new agent\", headless: template instance → sealed identity with owner/runtime stamps and attestations → marked reviewed → directory tracked → loaded (and started with `start: true`). Needs a ready owner identity; 409 `identity_not_ready` carries `identity` so a client can offer create / restore / unlock. `load_failed` (422) means the file was created, reviewed and tracked but could not load (e.g. no provider configured): fix it, then POST /agents/load.", "operationId": "createAgent", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentBody" } } } }, "responses": { "201": { "description": "Created (and loaded; started when `start`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentResponse" } } } }, "400": { "description": "Invalid field (`bad_request`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreateErrorResponse" }, "example": { "error": "directory must be an absolute path.", "code": "bad_request" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Owner identity not ready (`identity_not_ready`) or the name is taken in that directory (`name_taken`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreateErrorResponse" }, "examples": { "identity_not_ready": { "value": { "error": "Set up the owner identity first. …", "code": "identity_not_ready" } }, "name_taken": { "value": { "error": "An agent named \"agent-1\" already exists in /home/me/agents.", "code": "name_taken" } } } } } }, "422": { "description": "The template was refused (`template_missing`, `template_unreviewed`, `template_invalid`) or the new file could not load (`load_failed`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreateErrorResponse" }, "example": { "error": "standard.adf is not in the templates folder.", "code": "template_missing" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/agents/autostart": { "post": { "tags": [ "Agents" ], "summary": "Scan folders and autostart their reviewed agents", "description": "Same rules as daemon boot: autostart agents that are reviewed and not password-protected; others are reported in `skipped`.", "operationId": "autostartAgents", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutostartBody" } } } }, "responses": { "200": { "description": "What was started, skipped and failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutostartReport" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/review": { "get": { "tags": [ "Agents" ], "summary": "Review information for an .adf file", "operationId": "getAgentReview", "parameters": [ { "$ref": "#/components/parameters/AdfFilePathQuery" } ], "responses": { "200": { "description": "Review summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewInfo" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/review/accept": { "post": { "tags": [ "Agents" ], "summary": "Mark an .adf file's agent as reviewed", "operationId": "acceptAgentReview", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewAcceptBody" } } } }, "responses": { "200": { "description": "Reviewed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewInfo" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}": { "get": { "tags": [ "Agents" ], "summary": "A loaded agent's reference (id, file, config)", "operationId": "getAgent", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Agent reference", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRef" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/agents/{id}/status": { "get": { "tags": [ "Agents" ], "summary": "Agent runtime status", "operationId": "getAgentStatus", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentStatus" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/agents/{id}/start": { "post": { "tags": [ "Agents" ], "summary": "Start an agent, loading it from a tracked folder when needed", "description": "`id` may also name an agent that is not loaded: an .adf path, or an id / handle / name found in the tracked folders. The daemon loads it (review gate applies: 403) and starts it; `loaded` says whether it did. `startupTriggered` is true when the agent's start state fired its startup event. An identifier that matches several files answers 409 `ambiguous_agent` with the `candidates`: start one by its file path. No body.", "operationId": "startAgent", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartAgentResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ReviewRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The identifier matches several agent files (`ambiguous_agent`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AmbiguousAgentResponse" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/stop": { "post": { "tags": [ "Agents" ], "summary": "Stop and unload an agent", "description": "Graceful: a running turn gets a 5 s grace period, then the agent is unloaded (its file stays on disk). No body.", "operationId": "stopAgent", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Stopped and unloaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/unload": { "post": { "tags": [ "Agents" ], "summary": "Unload an agent (alias of stop)", "description": "No body.", "operationId": "unloadAgent", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Unloaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/abort": { "post": { "tags": [ "Agents" ], "summary": "Abort the current turn without unloading", "description": "A hard stop: the executor of main (or the named inner loop) is left `stopped` and runs no further turns, triggers or timers until the agent is reloaded. To end a turn and keep working, use /interrupt. Chats still queued behind the turn are discarded, never silently: a `chat.discarded` event names their `turnId`s and a System notice lands in the loop. Unknown loop 404; a loop with no running executor 409.", "operationId": "abortAgent", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/LoopQuery" } ], "requestBody": { "required": false, "description": "Optional; `?loop=` wins.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoopBody" } } } }, "responses": { "200": { "description": "Aborted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AbortResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/interrupt": { "post": { "tags": [ "Agents" ], "summary": "Interrupt the running turn and leave the loop idle", "description": "Ends main's (or the named loop's) running turn and sets that executor idle; it keeps accepting chats, triggers and timers. Unlike /abort it never stops the executor, and chats queued behind the turn are kept and run next. `interrupted` is false when nothing was running; 409 when the loop is stopped or errored.", "operationId": "interruptAgent", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/LoopQuery" } ], "requestBody": { "required": false, "description": "Optional; `?loop=` wins.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoopBody" } } } }, "responses": { "200": { "description": "Interrupted (or nothing to interrupt)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InterruptResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/state": { "post": { "tags": [ "Agents" ], "summary": "Move the running agent's display state", "description": "Fleet-map semantics, not persisted to the .adf: a `config.state` change via PUT …/config does not move the running agent; this does.", "operationId": "setAgentDisplayState", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisplayStateBody" } } } }, "responses": { "200": { "description": "State set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisplayStateResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/config": { "get": { "tags": [ "Agents" ], "summary": "Read the agent config", "operationId": "getAgentConfig", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Config", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentConfigResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Agents" ], "summary": "Replace the agent config", "description": "Validated against the ADF config schema, persisted and applied to the running executor, trigger evaluator and loops. A changed `state` does not move the running agent (it is the persisted start state); use POST …/state. Owner locks (`locked`, `locked_fields`) bind the agent's own sys_update_config, not this route.", "operationId": "setAgentConfig", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentConfig" } } } }, "responses": { "200": { "description": "Saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentConfigUpdateResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/tools": { "get": { "tags": [ "Agents" ], "summary": "The agent's tool catalog", "description": "Every built-in tool the main registry holds, every MCP tool its servers advertise and every declared tool, sorted by name, with declared state and description (what sys_get_config gives the agent). Read-only: change tools with PUT …/config.", "operationId": "getAgentTools", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Tools", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentToolsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/meta": { "get": { "tags": [ "Agents" ], "summary": "List metadata entries (adf_meta)", "operationId": "getAgentMeta", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/agents/{id}/meta/{key}": { "put": { "tags": [ "Agents" ], "summary": "Set a metadata value", "operationId": "setAgentMeta", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/MetaKeyPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaSetBody" } } } }, "responses": { "200": { "description": "Saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSuccess" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "tags": [ "Agents" ], "summary": "Delete a metadata value", "operationId": "deleteAgentMeta", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/MetaKeyPath" } ], "responses": { "200": { "description": "`success` is false when nothing was deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSuccess" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/meta/{key}/protection": { "patch": { "tags": [ "Agents" ], "summary": "Set a metadata key's protection", "operationId": "setAgentMetaProtection", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/MetaKeyPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaProtectionBody" } } } }, "responses": { "200": { "description": "Saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSuccess" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/tables": { "get": { "tags": [ "Agents" ], "summary": "List the agent's local tables", "operationId": "listAgentLocalTables", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Tables", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TablesResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/agents/{id}/tables/{table}": { "get": { "tags": [ "Agents" ], "summary": "Read rows of a local table", "description": "Only `local_*` tables and `adf_audit` are readable (anything else: 400 \"Invalid table name\"); read the inbox and outbox through their own routes. `limit` default 100 (1–1000), `offset` default 0.", "operationId": "queryAgentLocalTable", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/TablePath" }, { "$ref": "#/components/parameters/LimitQuery" }, { "$ref": "#/components/parameters/OffsetQuery" } ], "responses": { "200": { "description": "Rows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableQueryResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "tags": [ "Agents" ], "summary": "Drop a local table", "description": "Only `local_*` tables can be dropped.", "operationId": "dropAgentLocalTable", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/TablePath" } ], "responses": { "200": { "description": "Dropped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSuccess" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/logs": { "get": { "tags": [ "Agents" ], "summary": "Recent agent logs (adf_logs)", "description": "`limit` default 50 (clamped 1–500).", "operationId": "getAgentLogs", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/LimitQuery" }, { "name": "origin", "in": "query", "required": false, "description": "Only this origin (e.g. `lambda`, `websocket`)", "schema": { "type": "string" } }, { "name": "event", "in": "query", "required": false, "description": "Only this event name", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Log rows, newest last", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLogsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Agents" ], "summary": "Clear the agent's logs", "operationId": "clearAgentLogs", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Cleared", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSuccess" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/logs/after": { "get": { "tags": [ "Agents" ], "summary": "Log rows after an id (tail)", "operationId": "getAgentLogsAfter", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "name": "afterId", "in": "query", "required": true, "description": "Return rows with id greater than this", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Newer rows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLogsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/agents/{id}/usage": { "get": { "tags": [ "Agents" ], "summary": "Token usage from the agent's persisted loop rows", "description": "A rollup of `adf_loop.tokens` (compaction summary rows included). It excludes model_invoke and any provider call that created no loop row; the per-call usage/cost channel is the `llm.completed` umbilical event. `input` already includes cacheRead and cacheWrite; total = input + output.", "operationId": "getAgentUsage", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentUsageResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/agents/{id}/loops": { "get": { "tags": [ "Loops" ], "summary": "List cognition loops (main plus inner loops)", "operationId": "listAgentLoops", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Loops with live status and declarations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoopListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "Loops" ], "summary": "Create an inner loop", "description": "Goes through the agent's loop pool, the same path as the loop_manage tool: same validation, tool attenuation and owner locks (`locked_fields: [\"loops\"]`). Defaults: enabled and autostart true; tools loop_send + loop_list + sys_set_state (filtered to what the host can grant). An enabled autostart loop is kicked off at once through loop_send (`kickoff`). `excludedTools`: requested tools the host has disabled, carried by name and granted once enabled. 400 invalid declaration (bad name, unknown or never-grantable tool); 409 for `main`, a duplicate name, the loop cap, or `loops` locked by the owner.", "operationId": "createAgentLoop", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoopCreateBody" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoopCreateResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/loops/{name}": { "get": { "tags": [ "Loops" ], "summary": "Read one loop", "operationId": "getAgentLoopInfo", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/LoopNamePath" } ], "responses": { "200": { "description": "The loop", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoopResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "tags": [ "Loops" ], "summary": "Patch an inner loop", "description": "Present keys replace wholesale; `\"model\": null` / `\"compact_threshold\": null` remove the override so the loop inherits main's again. The loop is re-derived at once; `enabled: false` stops a running loop now (its turn is aborted and flushed). Loops cannot be renamed and an empty patch is refused (400). `main` is not managed here (409; change the agent config).", "operationId": "updateAgentLoop", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/LoopNamePath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoopPatchBody" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoopUpdateResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "tags": [ "Loops" ], "summary": "Stop, archive and remove an inner loop", "description": "Stops the loop (mid-turn included), archives its stream to adf_audit under `loop:`, drops its timers (locked timers are kept), then removes it. 409 for `main`.", "operationId": "deleteAgentLoop", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/LoopNamePath" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoopDeleteResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/loop": { "get": { "tags": [ "Loops" ], "summary": "Read persisted loop entries (paginated)", "description": "The durable conversation history. `limit` default 50 (clamped 1–500); `offset` default = the last page.", "operationId": "getAgentLoop", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/LimitQuery" }, { "$ref": "#/components/parameters/OffsetQuery" }, { "$ref": "#/components/parameters/LoopQuery" } ], "responses": { "200": { "description": "A page of adf_loop rows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoopPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/context": { "get": { "tags": [ "Loops" ], "summary": "One loop's context usage", "description": "What the next request of main (or `?loop=`) would carry: the executor's breakdown split into non-overlapping categories (system, files, tools, mcp:, dynamic, messages; biggest first, summing to totalTokens) with their biggest items, plus the compact threshold that loop auto-compacts at. Figures are the executor's own: system prompt and tool schemas measured with the provider tokenizer when it rebuilds them; conversation (compaction summary included) and dynamic instructions estimated per read. `compactThreshold` resolves like the executor: the loop's `compact_threshold`, else the agent's `context.compact_threshold`, else the (loop's or agent's) model's, else 100000 (`compactThresholdSource`: loop · agent · model · default); `agentCompactThreshold` is main's, for comparison. `available: false` (empty categories, null totals) when the loop has no live executor: disabled, never woken or put to sleep.", "operationId": "getAgentContext", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/LoopQuery" }, { "name": "items", "in": "query", "required": false, "description": "Items per category (default 12, max 200)", "schema": { "type": "integer", "minimum": 0, "maximum": 200 } } ], "responses": { "200": { "description": "Context usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentContextResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/compact": { "post": { "tags": [ "Loops" ], "summary": "Compact one loop's history now", "description": "Summarize-and-replace on demand for main, or the named inner loop. Emits loop.compacted; triggers queue and chats replay after it. 409 mid-turn, already compacting, nothing to compact, or a disabled loop; 502 when summarization fails (history preserved).", "operationId": "compactAgentLoop", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/LoopQuery" } ], "requestBody": { "required": false, "description": "Optional; `?loop=` wins.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoopBody" } } } }, "responses": { "200": { "description": "Compacted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompactResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" } } } }, "/agents/{id}/chat": { "post": { "tags": [ "Chat" ], "summary": "Queue a user chat turn", "description": "The owner's voice into main or any inner loop. Answers 202 at once (scheduling, not completion); follow the turn on GET /events, …/status or …/loop. An unknown loop answers 404 and a disabled one 409, before anything is queued. Match the returned `turnId` against `event.turn_id` on GET /events to follow this request's turn. Chats sent while the loop is busy queue in arrival order and none is ever dropped: the first interrupts the running turn, then the oldest queued chat runs as the next turn (its own `turnId`) and the others join it as consecutive user rows before its first model call, listed right away on a `chat.delivered` event (`payload.turn_ids`). Every `turnId` ends on a `turn.completed` (as its `turn_id` or in `absorbed_turn_ids`) or an `agent.error`; only /abort, unload or an `off` transition discard queued chats, announced by `chat.discarded`.", "operationId": "chatAgent", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatBody" } } } }, "responses": { "202": { "description": "Queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedTurn" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "tags": [ "Chat" ], "summary": "Display chat history of a loop", "description": "Display entries derived from the most recent loop rows. `limit` default 200 (clamped 1–500).", "operationId": "getAgentChat", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/LimitQuery" }, { "$ref": "#/components/parameters/LoopQuery" } ], "responses": { "200": { "description": "Chat history (null when none)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatHistoryResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "tags": [ "Chat" ], "summary": "Clear a loop's persisted chat / loop history", "description": "Clears one loop's stream (default main, never all of them) and resets its in-memory session.", "operationId": "clearAgentChat", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/LoopQuery" } ], "responses": { "200": { "description": "Cleared", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatClearResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/trigger": { "post": { "tags": [ "Chat" ], "summary": "Queue an ADF event dispatch", "description": "Accepts a dispatch, a wrapped `{ dispatch }`, a bare event (target fields at the top level or under `target`) or a batch (`events`). The daemon fills missing `id`, `time` and `source`. Event types: inbox, outbox, file_change, chat, timer, tool_call, task_create, task_complete, log_entry, startup, llm_call; `data` is required except for startup. Answers 202 at once.\n\n**Bypasses the TriggerEvaluator:** the dispatch goes straight to the executor, with no enabled check, target/scope gate, filter, timing modifier, state gating or self-suppression. An `inbox` dispatch creates no adf_inbox row; for a real inbound message use the mesh server's `POST /agents/{handle}/inbox`.\n\n**No owner voice:** `data.message.source: \"user\"` is refused (400; use POST …/chat, or source `api` / `mesh`), as are the internal flags `skip_loop_append` and `pre_appended_loop`. Match the returned `turnId` against `event.turn_id` on GET /events to follow this request's turn.", "operationId": "triggerAgent", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerBody" } } } }, "responses": { "202": { "description": "Queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedTurn" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/agents/{id}/inbox": { "get": { "tags": [ "Chat" ], "summary": "List inbox messages", "operationId": "getAgentInbox", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "name": "status", "in": "query", "required": false, "description": "Only this status", "schema": { "type": "string", "enum": [ "unread", "read", "archived" ] } } ], "responses": { "200": { "description": "Messages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Chat" ], "summary": "Delete all inbox messages", "description": "Audit snapshots are kept when the agent's audit config requires them.", "operationId": "clearAgentInbox", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Cleared", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxClearResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/outbox": { "get": { "tags": [ "Chat" ], "summary": "List outbox messages", "operationId": "getAgentOutbox", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "name": "status", "in": "query", "required": false, "description": "Only this status", "schema": { "type": "string", "enum": [ "pending", "sent", "delivered", "failed" ] } } ], "responses": { "200": { "description": "Messages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutboxResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/agents/{id}/files": { "get": { "tags": [ "Files" ], "summary": "List the agent's files", "operationId": "listAgentFiles", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Files (metadata)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentFilesResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/agents/{id}/files/content": { "get": { "tags": [ "Files" ], "summary": "Read one file", "description": "Text-like files come back as `encoding: \"utf-8\"` with `content`; binary files as `encoding: \"base64\"` with `content_base64`.", "operationId": "getAgentFileContent", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/FilePathQuery" } ], "responses": { "200": { "description": "File with content (utf-8) or content_base64", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileContentResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Files" ], "summary": "Write one file", "description": "Text with `content`, binary with `content_base64` (plus `mime_type`). Fires the agent's file-change triggers.", "operationId": "writeAgentFileContent", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/FilePathQuery" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileWriteBody" } } } }, "responses": { "200": { "description": "Written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSuccess" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "tags": [ "Files" ], "summary": "Delete one file", "operationId": "deleteAgentFileContent", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/FilePathQuery" } ], "responses": { "200": { "description": "`success` is false when nothing was deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSuccess" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/files/rename": { "post": { "tags": [ "Files" ], "summary": "Rename a file", "operationId": "renameAgentFile", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileRenameBody" } } } }, "responses": { "200": { "description": "Renamed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSuccess" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/files/rename-folder": { "post": { "tags": [ "Files" ], "summary": "Rename a folder (path prefix)", "operationId": "renameAgentFolder", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderRenameBody" } } } }, "responses": { "200": { "description": "Renamed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderRenameResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/files/protection": { "patch": { "tags": [ "Files" ], "summary": "Set a file's protection", "operationId": "setAgentFileProtection", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileProtectionBody" } } } }, "responses": { "200": { "description": "Saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSuccess" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/files/authorized": { "patch": { "tags": [ "Files" ], "summary": "Mark a file as authorized code (or not)", "operationId": "setAgentFileAuthorized", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileAuthorizedBody" } } } }, "responses": { "200": { "description": "Saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSuccess" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/document": { "get": { "tags": [ "Files" ], "summary": "Read the primary document", "operationId": "getAgentDocument", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextContentResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Files" ], "summary": "Write the primary document", "description": "Fires the agent's file/document-change triggers.", "operationId": "setAgentDocument", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextContentBody" } } } }, "responses": { "200": { "description": "Saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSuccess" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/mind": { "get": { "tags": [ "Files" ], "summary": "Read mind.md", "operationId": "getAgentMind", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextContentResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Files" ], "summary": "Write mind.md", "operationId": "setAgentMind", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextContentBody" } } } }, "responses": { "200": { "description": "Saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSuccess" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/identities": { "get": { "tags": [ "Identity (agent)" ], "summary": "List stored identity entries (no values)", "operationId": "getAgentIdentities", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/agents/{id}/identity": { "get": { "tags": [ "Identity (agent)" ], "summary": "List identity purposes", "operationId": "listAgentIdentityPurposes", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "name": "prefix", "in": "query", "required": false, "description": "Only purposes starting with this", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Purposes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityPurposesResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/agents/{id}/identity/entries": { "get": { "tags": [ "Identity (agent)" ], "summary": "List stored identity entries (alias of …/identities)", "operationId": "listAgentIdentityEntries", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/agents/{id}/identity/password": { "get": { "tags": [ "Identity (agent)" ], "summary": "Whether the identity store has a password and is unlocked", "operationId": "getAgentIdentityPasswordStatus", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityPasswordStatus" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Identity (agent)" ], "summary": "Set an identity password (legacy whole-file encryption)", "operationId": "setAgentIdentityPassword", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityPasswordBody" } } } }, "responses": { "200": { "description": "Set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSuccess" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": "Always 400 `not_supported`: whole-file passwords are no longer supported." }, "delete": { "tags": [ "Identity (agent)" ], "summary": "Remove the identity password", "operationId": "removeAgentIdentityPassword", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSuccess" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/CredentialsLocked" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/identity/password/unlock": { "post": { "tags": [ "Identity (agent)" ], "summary": "Unlock a password-protected identity store", "operationId": "unlockAgentIdentityPassword", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityPasswordBody" } } } }, "responses": { "200": { "description": "Unlocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSuccess" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/identity/password/change": { "post": { "tags": [ "Identity (agent)" ], "summary": "Change the identity password", "operationId": "changeAgentIdentityPassword", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityChangePasswordBody" } } } }, "responses": { "200": { "description": "Changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSuccess" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": "Always 400 `not_supported`: whole-file passwords are no longer supported." } }, "/agents/{id}/identity/did": { "get": { "tags": [ "Identity (agent)" ], "summary": "The agent's DID", "operationId": "getAgentDid", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "DID (null when no keys)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentDidResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/agents/{id}/identity/generate-keys": { "post": { "tags": [ "Identity (agent)" ], "summary": "Generate the agent's signing keys", "description": "No body.", "operationId": "generateAgentIdentityKeys", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateKeysResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/identity/wipe": { "post": { "tags": [ "Identity (agent)" ], "summary": "Wipe every identity row", "description": "Irreversible: keys, DID and every stored credential go. No body.", "operationId": "wipeAgentIdentity", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Wiped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSuccess" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/identity-prefix": { "delete": { "tags": [ "Identity (agent)" ], "summary": "Delete identity values by purpose prefix", "operationId": "deleteAgentIdentityPrefix", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "name": "prefix", "in": "query", "required": true, "description": "Purpose prefix, e.g. `mcp:@acme/server:`", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted count", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityPrefixDeleteResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/identity/{purpose}": { "get": { "tags": [ "Identity (agent)" ], "summary": "Metadata of one stored value (never the value)", "description": "Values and key material (`crypto:signing:*`, `crypto:envelope:*`, owner/runtime keys) never leave the daemon by any route. `storage`: sealed (envelope-encrypted), plain, password (legacy whole-file password) or null (absent); `locked`: stored but unreadable in this process; `length` is null for `crypto:*` and locked values.", "operationId": "getAgentIdentityValue", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/PurposePath" } ], "responses": { "200": { "description": "Metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentIdentityMetaResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "tags": [ "Identity (agent)" ], "summary": "Store one identity value", "description": "Values go in, never out. While the agent's credentials envelope is locked (or foreign) on this daemon the write is refused with 409 `credentials_locked`: a plain write would destroy a sealed value it cannot read, or store a new one unsealed. Unlock the owner identity first, or send `replace: true` (the owner's override: a locked sealed value is discarded unread, the new value stored plain and sealed once the envelope unlocks, logged as `credential_replaced`; the response then has `replaced: true`). `replace` is refused for key material (`crypto:*`, 400). A write to an agent locked by a legacy whole-file identity password answers 500 (unlock it with POST …/identity/password/unlock).", "operationId": "setAgentIdentityValue", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/PurposePath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityValueBody" } } } }, "responses": { "200": { "description": "Stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityWriteResponse" } } } }, "400": { "description": "Missing value, or `replace` on key material", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "value is required" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/CredentialsLocked" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "tags": [ "Identity (agent)" ], "summary": "Delete one identity value", "operationId": "deleteAgentIdentityValue", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/PurposePath" } ], "responses": { "200": { "description": "`success` is false when nothing was deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityDeleteResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/identity/{purpose}/code-access": { "patch": { "tags": [ "Identity (agent)" ], "summary": "Allow or deny code (sys_code / lambdas) reading a value", "operationId": "setAgentIdentityCodeAccess", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/PurposePath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityCodeAccessBody" } } } }, "responses": { "200": { "description": "Saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityDeleteResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/identity": { "get": { "tags": [ "Owner identity" ], "summary": "Owner identity status (no secrets)", "description": "The owner identity (a DID derived from a 12-word BIP-39 phrase) is what new agents are sealed and attested under, the same identity ADF Studio uses. Stored in the OS keychain (shared with Studio), or where there is none in a passphrase-encrypted `owner-secrets.json` next to the daemon settings. `status`: `none` (create or restore), `locked` (unlock), `restore-needed` (this machine has an owner DID, e.g. from Studio, but the daemon lacks its phrase: restore), `ready`. `passphraseRequired: true` means file storage. Whenever the identity becomes ready the daemon re-unlocks every loaded agent that is `degraded` (credentials locked), without a reload.", "operationId": "getOwnerIdentity", "responses": { "200": { "description": "Status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityStatus" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/identity/create": { "post": { "tags": [ "Owner identity" ], "summary": "Create the owner identity; returns the seed phrase ONCE (loopback only)", "description": "Only when `status` is `none`. `passphrase` (8+ characters) is required with file storage. Show the words to the user once, then call POST /identity/confirm-backup. Local callers only (see Local-only routes).", "operationId": "createOwnerIdentity", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityPassphraseBody" } } } }, "responses": { "201": { "description": "Created. Show the phrase once; it is never returned again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityCreateResponse" } } } }, "400": { "description": "No keychain and no/weak passphrase (`passphrase_required`, `weak_passphrase`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityErrorResponse" }, "example": { "error": "Choose a passphrase of at least 8 characters.", "code": "weak_passphrase" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/LoopbackOnly" }, "409": { "description": "An identity already exists (`identity_exists`, `owner_mismatch`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityErrorResponse" }, "example": { "error": "An owner identity already exists here (status: ready). …", "code": "identity_exists" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [ { "$ref": "#/components/parameters/LocalProofHeader" } ] } }, "/identity/restore": { "post": { "tags": [ "Owner identity" ], "summary": "Restore the owner identity from its seed phrase (loopback only)", "description": "A phrase of a different owner than the one this machine already has answers 409 `owner_mismatch` (switch owners in Studio instead); a wrong passphrase for an existing file 403 `wrong_passphrase`. Local callers only (see Local-only routes).", "operationId": "restoreOwnerIdentity", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityRestoreBody" } } } }, "responses": { "200": { "description": "Restored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityStatusEnvelope" } } } }, "400": { "description": "Invalid phrase or passphrase (`invalid_mnemonic`, `passphrase_required`, `weak_passphrase`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityErrorResponse" }, "example": { "error": "That is not a valid 12-word seed phrase. Check the words and their order.", "code": "invalid_mnemonic" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/LoopbackOnly" }, "409": { "description": "A different owner is already set up here (`owner_mismatch`, `identity_exists`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityErrorResponse" }, "example": { "error": "Refusing to replace this machine's owner did:key:… from the daemon.", "code": "owner_mismatch" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [ { "$ref": "#/components/parameters/LocalProofHeader" } ] } }, "/identity/unlock": { "post": { "tags": [ "Owner identity" ], "summary": "Unlock a passphrase-file identity (loopback only)", "description": "Only for file storage (no OS keychain). A wrong passphrase answers 403 `wrong_passphrase`. The daemon can also unlock at boot from ADF_OWNER_PASSPHRASE or ADF_OWNER_PASSPHRASE_FILE. Local callers only (see Local-only routes).", "operationId": "unlockOwnerIdentity", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityPassphraseBody" } } } }, "responses": { "200": { "description": "Unlocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityStatusEnvelope" } } } }, "400": { "description": "Keychain storage (`not_file_storage`) or no passphrase (`passphrase_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityErrorResponse" }, "example": { "error": "Provide the passphrase.", "code": "passphrase_required" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/LoopbackOnly" }, "409": { "description": "No identity file yet (`nothing_to_unlock`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityErrorResponse" }, "example": { "error": "There is no owner identity file yet. …", "code": "nothing_to_unlock" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [ { "$ref": "#/components/parameters/LocalProofHeader" } ] } }, "/identity/lock": { "post": { "tags": [ "Owner identity" ], "summary": "Lock a passphrase-file identity (loopback only)", "description": "No body. Local callers only (see Local-only routes).", "operationId": "lockOwnerIdentity", "responses": { "200": { "description": "Locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityStatusEnvelope" } } } }, "400": { "description": "Keychain storage cannot be locked by the daemon (`not_file_storage`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityErrorResponse" }, "example": { "error": "The owner identity is in the OS keychain and cannot be locked by the daemon.", "code": "not_file_storage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/LoopbackOnly" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [ { "$ref": "#/components/parameters/LocalProofHeader" } ] } }, "/identity/confirm-backup": { "post": { "tags": [ "Owner identity" ], "summary": "Record that the seed phrase was written down (loopback only)", "description": "No body. Local callers only (see Local-only routes).", "operationId": "confirmOwnerBackup", "responses": { "200": { "description": "Confirmed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityStatusEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/LoopbackOnly" }, "409": { "description": "No usable identity (`not_ready`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityErrorResponse" }, "example": { "error": "No usable owner identity to confirm.", "code": "not_ready" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [ { "$ref": "#/components/parameters/LocalProofHeader" } ] } }, "/agents/{id}/providers/{providerId}/credentials": { "get": { "tags": [ "Credentials" ], "summary": "Provider credential metadata and config overrides", "description": "Metadata only; stored values never leave the daemon.", "operationId": "getAgentProviderCredentials", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/ProviderIdPath" } ], "responses": { "200": { "description": "Metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderCredentialsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/providers/{providerId}/credential": { "put": { "tags": [ "Credentials" ], "summary": "Store a provider API key in the agent", "description": "Stored as `provider:{providerId}:apiKey`. Values go in, never out. While the agent's credentials envelope is locked (or foreign) on this daemon the write is refused with 409 `credentials_locked`: a plain write would destroy a sealed value it cannot read, or store a new one unsealed. Unlock the owner identity first, or send `replace: true` (the owner's override: a locked sealed value is discarded unread, the new value stored plain and sealed once the envelope unlocks, logged as `credential_replaced`; the response then has `replaced: true`). `replace` is refused for key material (`crypto:*`, 400). A write to an agent locked by a legacy whole-file identity password answers 500 (unlock it with POST …/identity/password/unlock).", "operationId": "setAgentProviderCredential", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/ProviderIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityValueBody" } } } }, "responses": { "200": { "description": "Stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderCredentialWriteResponse" } } } }, "400": { "description": "Missing value, or `replace` on key material", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "value is required" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/CredentialsLocked" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/mcp/credentials": { "get": { "tags": [ "Credentials" ], "summary": "MCP credential metadata by package", "description": "Metadata only.", "operationId": "getAgentMcpCredentials", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "name": "npmPackage", "in": "query", "required": true, "description": "Package or server name", "schema": { "type": "string" }, "example": "@acme/mcp-server" } ], "responses": { "200": { "description": "Metadata by env key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpCredentialsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "tags": [ "Credentials" ], "summary": "Store an MCP credential", "description": "Stored as `mcp:{npmPackage}:{envKey}`. Values go in, never out. While the agent's credentials envelope is locked (or foreign) on this daemon the write is refused with 409 `credentials_locked`: a plain write would destroy a sealed value it cannot read, or store a new one unsealed. Unlock the owner identity first, or send `replace: true` (the owner's override: a locked sealed value is discarded unread, the new value stored plain and sealed once the envelope unlocks, logged as `credential_replaced`; the response then has `replaced: true`). `replace` is refused for key material (`crypto:*`, 400). A write to an agent locked by a legacy whole-file identity password answers 500 (unlock it with POST …/identity/password/unlock).", "operationId": "setAgentMcpCredential", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpCredentialBody" } } } }, "responses": { "200": { "description": "Stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpCredentialWriteResponse" } } } }, "400": { "description": "Missing field, or `replace` on key material", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "envKey is required" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/CredentialsLocked" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/adapters/credentials": { "get": { "tags": [ "Credentials" ], "summary": "Channel adapter credential metadata by type", "description": "Metadata only.", "operationId": "getAgentAdapterCredentials", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "name": "adapterType", "in": "query", "required": true, "description": "Adapter type", "schema": { "type": "string" }, "example": "telegram" } ], "responses": { "200": { "description": "Metadata by env key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdapterCredentialsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "tags": [ "Credentials" ], "summary": "Store a channel adapter credential", "description": "Stored as `adapter:{adapterType}:{envKey}`. Values go in, never out. While the agent's credentials envelope is locked (or foreign) on this daemon the write is refused with 409 `credentials_locked`: a plain write would destroy a sealed value it cannot read, or store a new one unsealed. Unlock the owner identity first, or send `replace: true` (the owner's override: a locked sealed value is discarded unread, the new value stored plain and sealed once the envelope unlocks, logged as `credential_replaced`; the response then has `replaced: true`). `replace` is refused for key material (`crypto:*`, 400). A write to an agent locked by a legacy whole-file identity password answers 500 (unlock it with POST …/identity/password/unlock).", "operationId": "setAgentAdapterCredential", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdapterCredentialBody" } } } }, "responses": { "200": { "description": "Stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdapterCredentialWriteResponse" } } } }, "400": { "description": "Missing field, or `replace` on key material", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "adapterType is required" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/CredentialsLocked" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/adapters": { "get": { "tags": [ "Channels" ], "summary": "The agent's adapters: configured and live state", "operationId": "getAgentAdapters", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Adapters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAdaptersDiagnostics" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "Channels" ], "summary": "Attach or update a channel adapter", "description": "Validated like Studio's adapter attach. Tokens are credentials (PUT …/adapters/credentials), not config.", "operationId": "attachAgentAdapter", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdapterAttachBody" } } } }, "responses": { "200": { "description": "Attached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdapterAttachResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/adapters/{adapterType}": { "delete": { "tags": [ "Channels" ], "summary": "Detach an adapter and delete its credentials", "description": "Removes the adapter config and every `adapter:{adapterType}:*` identity row.", "operationId": "detachAgentAdapter", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/AdapterTypePath" } ], "responses": { "200": { "description": "Detached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdapterDetachResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/runtime/adapters": { "get": { "tags": [ "Channels" ], "summary": "The agent's adapters (same as GET …/adapters)", "operationId": "getAgentRuntimeAdapters", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Adapters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAdaptersDiagnostics" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/runtime/adapters": { "get": { "tags": [ "Channels" ], "summary": "Daemon-wide adapter registrations", "operationId": "getRuntimeAdapters", "responses": { "200": { "description": "Registrations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdapterRegistrationsDiagnostics" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/agents/{id}/mcp": { "get": { "tags": [ "MCP" ], "summary": "The agent's MCP servers: configured and live state", "operationId": "getAgentMcp", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Servers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentMcpDiagnostics" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/agents/{id}/runtime/mcp": { "get": { "tags": [ "MCP" ], "summary": "The agent's MCP servers (same as GET …/mcp)", "operationId": "getAgentRuntimeMcp", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Servers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentMcpDiagnostics" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/agents/{id}/mcp/servers": { "post": { "tags": [ "MCP" ], "summary": "Attach or update an MCP server config", "description": "Saved to the agent config; the server connects at the next start, or now with POST …/mcp/servers/{serverName}/restart.", "operationId": "attachAgentMcpServer", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpAttachBody" }, "example": { "server": { "name": "filesystem", "transport": "stdio", "npm_package": "@modelcontextprotocol/server-filesystem" } } } } }, "responses": { "200": { "description": "Attached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpAttachResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/mcp/servers/{serverName}": { "delete": { "tags": [ "MCP" ], "summary": "Detach an MCP server and delete its credentials", "description": "Removes the server config and the matching `mcp:*` identity rows.", "operationId": "detachAgentMcpServer", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/ServerNamePath" }, { "name": "credentialNamespace", "in": "query", "required": false, "description": "Credential namespace to delete (default: the server's package or name)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Detached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpDetachResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/mcp/servers/{serverName}/restart": { "post": { "tags": [ "MCP" ], "summary": "Connect one configured MCP server now", "description": "The same connect the agent's own mcp_restart tool does (host or container routing, the agent's sealed credentials, tool discovery). Use it after POST …/mcp/servers (attached servers connect at the next start otherwise) or to retry a failed server. 404 for an unknown server; 409 when the agent is not running here. No body.", "operationId": "restartAgentMcpServer", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/ServerNamePath" } ], "responses": { "200": { "description": "Connect outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpRestartResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/runtime/mcp": { "get": { "tags": [ "MCP" ], "summary": "Daemon-wide MCP registrations (values redacted)", "operationId": "getRuntimeMcp", "responses": { "200": { "description": "Registrations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpRegistrationsDiagnostics" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/runtime/providers": { "get": { "tags": [ "Providers & sign-in" ], "summary": "App providers and which agents use them", "operationId": "getRuntimeProviders", "responses": { "200": { "description": "Providers (hasApiKey only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderDiagnostics" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "Providers & sign-in" ], "summary": "Add an API-key provider", "description": "For every agent on this daemon. The key goes to the daemon secret store (OS keychain, or the owner's passphrase file), never the settings file, and is never returned: the settings entry carries `apiKeyStorage: \"secret-store\"` and an empty `apiKey`, and the daemon fills the key in when it resolves the provider. `openai-compatible` needs `baseUrl` (apiKey optional, for local servers); subscriptions (ChatGPT, Grok) sign in instead (400 `subscription_type`). The name is made unique (`OpenRouter 2`); the first provider becomes the default.", "operationId": "addRuntimeProvider", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddProviderBody" } } } }, "responses": { "201": { "description": "Added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddProviderResponse" } } } }, "400": { "description": "Invalid body (`bad_type`, `subscription_type`, `api_key_required`, `base_url_required`, `bad_base_url`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "apiKey is required for this provider type.", "code": "api_key_required" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "description": "Settings store is read-only (`read_only`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Settings store is read-only.", "code": "read_only" } } } }, "409": { "description": "The secret store is locked or not set up (`secret_store_locked`): set up or unlock the owner identity first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "The daemon secret store is locked or not set up yet: …", "code": "secret_store_locked" } } } }, "500": { "description": "Saving failed (`save_failed`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Could not save the provider: …", "code": "save_failed" } } } } } } }, "/runtime/providers/{id}": { "delete": { "tags": [ "Providers & sign-in" ], "summary": "Remove an app provider and its stored key", "description": "The default moves to the next provider.", "operationId": "removeRuntimeProvider", "parameters": [ { "$ref": "#/components/parameters/AppProviderIdPath" } ], "responses": { "200": { "description": "Removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveProviderResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Unknown provider (`not_found`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Unknown provider \"custom:ab12cd\"", "code": "not_found" } } } }, "405": { "description": "Settings store is read-only (`read_only`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Settings store is read-only.", "code": "read_only" } } } } } } }, "/runtime/models": { "get": { "tags": [ "Providers & sign-in" ], "summary": "List a provider's models", "description": "App providers, or an agent's own provider (and its agent-scoped key) with `agentId`. Remote failures come back as 200 `{ models: [], error }`.", "operationId": "listRuntimeProviderModels", "parameters": [ { "name": "provider", "in": "query", "required": true, "description": "Provider id", "schema": { "type": "string" }, "example": "anthropic" }, { "name": "agentId", "in": "query", "required": false, "description": "Resolve the provider in this agent's config", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Models", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/runtime/auth": { "get": { "tags": [ "Providers & sign-in" ], "summary": "Sign-in and API-key status of every provider", "operationId": "getRuntimeAuth", "responses": { "200": { "description": "Auth status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthDiagnostics" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/auth/chatgpt/status": { "get": { "tags": [ "Providers & sign-in" ], "summary": "ChatGPT subscription sign-in status", "operationId": "getChatGptAuthStatus", "responses": { "200": { "description": "Status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionAuthStatus" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/auth/chatgpt/start": { "post": { "tags": [ "Providers & sign-in" ], "summary": "Start a ChatGPT subscription sign-in", "description": "The daemon keeps its own subscription session, separate from Studio's. ChatGPT uses a loopback OAuth redirect, so the callback server must run where the browser is. `loopback` (default) serves it in the daemon: open authUrl, then poll GET /auth/chatgpt/status. `relay` (for a remote daemon) keeps the PKCE verifier in the daemon while the caller serves the callback on its own loopback `redirectUri` (required, loopback only) and posts code + state to /auth/chatgpt/complete within 10 minutes.", "operationId": "startChatGptAuth", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatGptAuthStartRequest" } } } }, "responses": { "200": { "description": "Flow started; open authUrl", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatGptAuthStartResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/auth/chatgpt/complete": { "post": { "tags": [ "Providers & sign-in" ], "summary": "Complete a relayed ChatGPT sign-in", "description": "Exchanges the code captured by the caller's callback server. Each flowId is single-use and expires 10 minutes after start; an unknown or expired flowId, a mismatched state or a failed token exchange answers 400. After any sign-in (loopback, relay or Grok) every loaded loop in `error` from an auth failure of that provider type returns to idle and emits agent.recovered; the failed turn is not re-run.", "operationId": "completeChatGptAuth", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatGptAuthCompleteRequest" } } } }, "responses": { "200": { "description": "Signed in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatGptAuthCompleteResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/auth/chatgpt/logout": { "post": { "tags": [ "Providers & sign-in" ], "summary": "Sign out of ChatGPT", "description": "No body.", "operationId": "logoutChatGpt", "responses": { "200": { "description": "Signed out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/auth/grok/status": { "get": { "tags": [ "Providers & sign-in" ], "summary": "Grok (xAI) subscription sign-in status", "description": "`flowPending` while a device-code flow runs; a failed flow surfaces `flowError`.", "operationId": "getGrokAuthStatus", "responses": { "200": { "description": "Status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionAuthStatus" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/auth/grok/start": { "post": { "tags": [ "Providers & sign-in" ], "summary": "Start a Grok device-code sign-in", "description": "OAuth device-code flow (RFC 8628): no localhost callback, so it works against a remote daemon. Open verificationUriComplete (or verificationUri and enter userCode) in any browser, then poll GET /auth/grok/status; the daemon polls xAI in the background. No body.", "operationId": "startGrokAuth", "responses": { "200": { "description": "Flow started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrokAuthStartResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/auth/grok/logout": { "post": { "tags": [ "Providers & sign-in" ], "summary": "Sign out of Grok", "description": "No body.", "operationId": "logoutGrok", "responses": { "200": { "description": "Signed out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/agents/{id}/providers": { "post": { "tags": [ "Providers & sign-in" ], "summary": "Attach or update a provider in the agent config", "operationId": "attachAgentProvider", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderAttachBody" } } } }, "responses": { "200": { "description": "Attached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderAttachResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/providers/{providerId}": { "delete": { "tags": [ "Providers & sign-in" ], "summary": "Detach a provider and delete its credentials", "description": "Removes the provider config and every `provider:{providerId}:*` identity row.", "operationId": "detachAgentProvider", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/ProviderIdPath" } ], "responses": { "200": { "description": "Detached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderDetachResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/tasks": { "get": { "tags": [ "Tasks & approvals" ], "summary": "List tasks and approvals", "description": "`limit` default 200 (clamped 1–1000). `pending_approval` rows carry the live Always-approve affordance (`canAlwaysApprove`, `alwaysApproveBlockedReason`), derived from the executor holding the request and never persisted.", "operationId": "getAgentTasks", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "name": "status", "in": "query", "required": false, "description": "Only this status", "schema": { "$ref": "#/components/schemas/TaskStatus" } }, { "$ref": "#/components/parameters/LimitQuery" } ], "responses": { "200": { "description": "Tasks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TasksResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/agents/{id}/tasks/{taskId}": { "get": { "tags": [ "Tasks & approvals" ], "summary": "Read one task", "operationId": "getAgentTask", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/TaskIdPath" } ], "responses": { "200": { "description": "Task", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/agents/{id}/tasks/{taskId}/resolve": { "post": { "tags": [ "Tasks & approvals" ], "summary": "Approve or deny a pending task", "description": "`approve` lets it run (optionally with `modifiedArgs`); `deny` refuses it: `reason` is stored as the task's `error` and handed back to the agent as the owner's feedback (a blocking call's tool result reads `Tool call \"\" was rejected by authorizer. Feedback: `); `pending_approval` marks a pending task as awaiting approval. Only `pending` / `pending_approval` tasks resolve; others answer 409. At load the runtime sweeps orphans from a crash: `running` tasks become `failed` and the executor's own `pending_approval` tasks `cancelled`, so resolving one of those is a 409. Requests parked by an inner loop are answered on that loop's executor.", "operationId": "resolveAgentTask", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/TaskIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResolveBody" } } } }, "responses": { "200": { "description": "Resolved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResolutionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/tasks/{taskId}/always-approve": { "post": { "tags": [ "Tasks & approvals" ], "summary": "Always approve: un-restrict the tool and approve the request", "description": "Studio's Approve ▸ Always approve. The host tool declaration (taken from the pending request, never the client) becomes enabled and unrestricted, persisted like PUT …/config; then the request is approved. 409 for protection overrides, one-shot approvals, locked declarations or a request no executor holds. No body.", "operationId": "alwaysApproveAgentTask", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/TaskIdPath" } ], "responses": { "200": { "description": "Approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskAlwaysApproveResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/tasks/approve-all": { "post": { "tags": [ "Tasks & approvals" ], "summary": "Approve every pending gated approval", "description": "Studio's Approve all: main and every running inner loop (or only `loop`, from the body or query). Protection overrides are never approved; they are counted in `skippedProtection`.", "operationId": "approveAllAgentTasks", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/LoopQuery" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveAllBody" } } } }, "responses": { "200": { "description": "Counts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveAllResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/asks": { "get": { "tags": [ "Tasks & approvals" ], "summary": "List pending ask requests", "description": "Every loop's (main and each running inner loop); `loop` names the loop whose turn is waiting.", "operationId": "getAgentAsks", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Asks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsksResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/agents/{id}/asks/{requestId}/respond": { "post": { "tags": [ "Tasks & approvals" ], "summary": "Answer an ask request", "description": "Request ids are numbered per loop: pass the `loop` from GET …/asks when two loops ask at once; without it the first loop holding the id is answered. An id no loop holds (already answered, or never asked) answers 404 `ask_not_found`.", "operationId": "answerAgentAsk", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/RequestIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskRespondBody" } } } }, "responses": { "200": { "description": "`answered` is false when no loop held the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskRespondResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Unknown agent (`not_found`), or no loop holds this ask (`ask_not_found`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "ask_not_found": { "value": { "error": "Ask request \"ask_3\" not found (already answered, or never asked).", "code": "ask_not_found" } }, "not_found": { "value": { "error": "Unknown agent \"agent-9\"", "code": "not_found" } } } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/suspend/respond": { "post": { "tags": [ "Tasks & approvals" ], "summary": "Resume or stop after a suspend prompt", "operationId": "respondAgentSuspend", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuspendRespondBody" } } } }, "responses": { "200": { "description": "Resolved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuspendRespondResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/timers": { "get": { "tags": [ "Timers" ], "summary": "List timers", "operationId": "getAgentTimers", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Timers (expired ones kept as history)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimersResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "Timers" ], "summary": "Add a timer", "description": "Same body as Studio's timer creation. `loop` names the cognition loop an agent-scope wake dispatches to (absent = main; unknown = 404): this is how an inner loop runs on a schedule. A system-scope-only timer carries no loop.", "operationId": "addAgentTimer", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimerMutationBody" } } } }, "responses": { "200": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimerCreateResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agents/{id}/timers/{timerId}": { "put": { "tags": [ "Timers" ], "summary": "Replace a timer's schedule and target", "description": "Same body as creation. With `loop` the timer moves to that loop in place (same id; `\"main\"` moves it back; unknown loop 404); without `loop` it keeps its loop.", "operationId": "updateAgentTimer", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/TimerIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimerMutationBody" } } } }, "responses": { "200": { "description": "`success` is false when no such timer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSuccess" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "tags": [ "Timers" ], "summary": "Delete a timer", "operationId": "deleteAgentTimer", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" }, { "$ref": "#/components/parameters/TimerIdPath" } ], "responses": { "200": { "description": "`success` is false when no such timer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSuccess" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/templates": { "get": { "tags": [ "Templates" ], "summary": "List agent templates", "operationId": "listTemplates", "responses": { "200": { "description": "Templates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/IdentityNotReady" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "post": { "tags": [ "Templates" ], "summary": "Create a template (blank, or a duplicate of fromId)", "description": "A template is an ordinary .adf in `/templates` (Studio's Settings > Agent templates); its id is the file stem. New agents get everything in a template except its identity and history. A duplicate carries the notes, never the identity or history. Names: letters, digits, spaces, `-`, `_`, at most 64 characters.", "operationId": "createTemplate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateCreateBody" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateRef" } } } }, "400": { "description": "Invalid body or the template was refused (`bad_request`, `template_invalid`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreateErrorResponse" }, "example": { "error": "name is required", "code": "bad_request" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Unknown template (`template_missing`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreateErrorResponse" }, "example": { "error": "Unknown template.", "code": "template_missing" } } } }, "409": { "$ref": "#/components/responses/IdentityNotReady" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/templates/{id}": { "get": { "tags": [ "Templates" ], "summary": "One template: summary, contents and whether it is the default", "operationId": "getTemplate", "parameters": [ { "$ref": "#/components/parameters/TemplateIdPath" } ], "responses": { "200": { "description": "Template", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateDetail" } } } }, "400": { "description": "Invalid body or the template was refused (`bad_request`, `template_invalid`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreateErrorResponse" }, "example": { "error": "name is required", "code": "bad_request" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Unknown template (`template_missing`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreateErrorResponse" }, "example": { "error": "Unknown template.", "code": "template_missing" } } } }, "409": { "$ref": "#/components/responses/IdentityNotReady" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "patch": { "tags": [ "Templates" ], "summary": "Rename a template and/or set its notes", "description": "Notes are shown wherever the template is offered and never copied into agents (`\"\"` clears one; at most 500 characters). A rename moves the file (`defaultId` follows): the response carries the new id.", "operationId": "updateTemplate", "parameters": [ { "$ref": "#/components/parameters/TemplateIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplatePatchBody" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateRef" } } } }, "400": { "description": "Invalid body or the template was refused (`bad_request`, `template_invalid`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreateErrorResponse" }, "example": { "error": "name is required", "code": "bad_request" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Unknown template (`template_missing`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreateErrorResponse" }, "example": { "error": "Unknown template.", "code": "template_missing" } } } }, "409": { "$ref": "#/components/responses/IdentityNotReady" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "tags": [ "Templates" ], "summary": "Delete a template (moved to templates-trash)", "description": "Never a hard delete; the default falls back to `standard`.", "operationId": "deleteTemplate", "parameters": [ { "$ref": "#/components/parameters/TemplateIdPath" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateDeleteResponse" } } } }, "400": { "description": "Invalid body or the template was refused (`bad_request`, `template_invalid`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreateErrorResponse" }, "example": { "error": "name is required", "code": "bad_request" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Unknown template (`template_missing`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreateErrorResponse" }, "example": { "error": "Unknown template.", "code": "template_missing" } } } }, "409": { "$ref": "#/components/responses/IdentityNotReady" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/templates/{id}/default": { "post": { "tags": [ "Templates" ], "summary": "Make this the default template", "description": "No body.", "operationId": "setDefaultTemplate", "parameters": [ { "$ref": "#/components/parameters/TemplateIdPath" } ], "responses": { "200": { "description": "Default set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateDefaultResponse" } } } }, "400": { "description": "Invalid body or the template was refused (`bad_request`, `template_invalid`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreateErrorResponse" }, "example": { "error": "name is required", "code": "bad_request" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Unknown template (`template_missing`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreateErrorResponse" }, "example": { "error": "Unknown template.", "code": "template_missing" } } } }, "409": { "$ref": "#/components/responses/IdentityNotReady" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/templates/{id}/reset": { "post": { "tags": [ "Templates" ], "summary": "Reset a shipped template to the shipped version", "description": "For a shipped template (`standard`, `sandboxed`, `full-access`, even renamed); 400 for a user template. No body.", "operationId": "resetShippedTemplate", "parameters": [ { "$ref": "#/components/parameters/TemplateIdPath" } ], "responses": { "200": { "description": "Reset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateRef" } } } }, "400": { "description": "Invalid body or the template was refused (`bad_request`, `template_invalid`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreateErrorResponse" }, "example": { "error": "name is required", "code": "bad_request" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Unknown template (`template_missing`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreateErrorResponse" }, "example": { "error": "Unknown template.", "code": "template_missing" } } } }, "409": { "$ref": "#/components/responses/IdentityNotReady" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/templates/{id}/review": { "get": { "tags": [ "Templates" ], "summary": "The review summary of a template", "description": "The agent review summary (identity scenario, tools, MCP, triggers, network, …). Provider status is `unchecked` or `missing`: credentials are not probed. Someone else's template (foreign or identity-less) shows `reviewed: false`, and POST /agents/create refuses it (422 `template_unreviewed`) until accepted.", "operationId": "getTemplateReview", "parameters": [ { "$ref": "#/components/parameters/TemplateIdPath" } ], "responses": { "200": { "description": "Review", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateReview" } } } }, "400": { "description": "Invalid body or the template was refused (`bad_request`, `template_invalid`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreateErrorResponse" }, "example": { "error": "name is required", "code": "bad_request" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Unknown template (`template_missing`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreateErrorResponse" }, "example": { "error": "Unknown template.", "code": "template_missing" } } } }, "409": { "$ref": "#/components/responses/IdentityNotReady" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/templates/{id}/review/accept": { "post": { "tags": [ "Templates" ], "summary": "Accept a template: claim it under this owner and mark it reviewed", "description": "Claims the file with a fresh identity under this owner, auto-locks `compute` (and ws / adapters / table protections when set), marks it reviewed. `password` for a password-protected file (400 `password_required`, 403 `wrong_password`); 409 `identity_not_ready` when the owner keys are unavailable.", "operationId": "acceptTemplateReview", "parameters": [ { "$ref": "#/components/parameters/TemplateIdPath" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateReviewAcceptBody" } } } }, "responses": { "200": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateReviewAcceptResponse" } } } }, "400": { "description": "Invalid body or the template was refused (`bad_request`, `template_invalid`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreateErrorResponse" }, "example": { "error": "name is required", "code": "bad_request" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Wrong password (`wrong_password`), or the request guard refused it: Host header not allowed (`host_not_allowed`, DNS-rebinding protection) or a browser cross-site request (`cross_origin`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreateErrorResponse" }, "example": { "error": "Wrong password", "code": "wrong_password" } } } }, "404": { "description": "Unknown template (`template_missing`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreateErrorResponse" }, "example": { "error": "Unknown template.", "code": "template_missing" } } } }, "409": { "$ref": "#/components/responses/IdentityNotReady" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/templates/{id}/config": { "put": { "tags": [ "Templates" ], "summary": "Replace a template's agent config", "description": "Validated with the config schema; the first issue is the 400 error.", "operationId": "setTemplateConfig", "parameters": [ { "$ref": "#/components/parameters/TemplateIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateConfigBody" } } } }, "responses": { "200": { "description": "Saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateConfigResponse" } } } }, "400": { "description": "Invalid body or the template was refused (`bad_request`, `template_invalid`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreateErrorResponse" }, "example": { "error": "name is required", "code": "bad_request" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Unknown template (`template_missing`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreateErrorResponse" }, "example": { "error": "Unknown template.", "code": "template_missing" } } } }, "409": { "$ref": "#/components/responses/IdentityNotReady" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/templates/{id}/files": { "put": { "tags": [ "Templates" ], "summary": "Write a template file (seed or extra)", "operationId": "setTemplateFile", "parameters": [ { "$ref": "#/components/parameters/TemplateIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateFileBody" } } } }, "responses": { "200": { "description": "Written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateFileResponse" } } } }, "400": { "description": "Invalid body or the template was refused (`bad_request`, `template_invalid`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreateErrorResponse" }, "example": { "error": "name is required", "code": "bad_request" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Unknown template (`template_missing`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreateErrorResponse" }, "example": { "error": "Unknown template.", "code": "template_missing" } } } }, "409": { "$ref": "#/components/responses/IdentityNotReady" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "tags": [ "Templates" ], "summary": "Remove an extra file", "description": "Seed files cannot be removed; clear their text instead.", "operationId": "removeTemplateFile", "parameters": [ { "$ref": "#/components/parameters/TemplateIdPath" }, { "name": "path", "in": "query", "required": true, "description": "Extra file path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateFileResponse" } } } }, "400": { "description": "Invalid body or the template was refused (`bad_request`, `template_invalid`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreateErrorResponse" }, "example": { "error": "name is required", "code": "bad_request" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Unknown template (`template_missing`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreateErrorResponse" }, "example": { "error": "Unknown template.", "code": "template_missing" } } } }, "409": { "$ref": "#/components/responses/IdentityNotReady" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/tracked-dirs": { "get": { "tags": [ "Tracked folders" ], "summary": "List tracked folders", "operationId": "listTrackedDirs", "responses": { "200": { "description": "Tracked folders", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackedDirsList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "post": { "tags": [ "Tracked folders" ], "summary": "Track a folder and autostart its agents", "description": "1. `path` must be an absolute, existing directory; it is stored canonicalized (resolved, symlinks and 8.3 names expanded, no trailing separator). 2. It is persisted to settings.trackedDirectories; a new parent replaces tracked subfolders it covers (`absorbed`). 3. The live daemon (mesh tracked roots) is updated at once. 4. The folder gets the same autostart pass as daemon boot, with the review gate: unreviewed agents are not loaded and are listed in `needsReview` (accept with POST /agents/review/accept). `agents` is every agent in the folder after the pass. Tracking never creates, moves or deletes files; scans use maxDirectoryScanDepth (default 5).", "operationId": "trackDir", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackDirBody" } } } }, "responses": { "201": { "description": "Tracked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackDirResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "description": "Settings store is read-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackedDirErrorResponse" }, "example": { "error": "Settings store is read-only." } } } }, "409": { "description": "Already tracked, itself or through a parent (`coveredBy`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackedDirErrorResponse" }, "example": { "error": "Already tracked through its parent folder /home/me", "coveredBy": "/home/me" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "tags": [ "Tracked folders" ], "summary": "Untrack a folder (files are never deleted)", "description": "`path` matches the stored string exactly or names the same folder under another spelling; a folder gone from disk can still be untracked by its stored string. `unload=true` also unloads every loaded agent whose file is under it (files stay on disk); the default leaves them running.", "operationId": "untrackDir", "parameters": [ { "name": "path", "in": "query", "required": true, "description": "The tracked folder", "schema": { "type": "string" } }, { "name": "unload", "in": "query", "required": false, "description": "Also unload the agents loaded from under it", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "Untracked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UntrackDirResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not a tracked folder", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackedDirErrorResponse" }, "example": { "error": "Not a tracked folder: /home/me/other" } } } }, "405": { "description": "Settings store is read-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackedDirErrorResponse" }, "example": { "error": "Settings store is read-only." } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/tracked-dirs/agents": { "get": { "tags": [ "Tracked folders" ], "summary": "The agents of one tracked folder and what each needs", "description": "`status`: loaded; needs_review (never reviewed here: POST /agents/review/accept); not_autostart (reviewed, loads on request); stopped (should have loaded but did not: `error` has the load error when known); password_protected; unreadable (`error` says why).", "operationId": "listTrackedDirAgents", "parameters": [ { "name": "path", "in": "query", "required": true, "description": "The tracked folder", "schema": { "type": "string" }, "example": "/home/me/agents" } ], "responses": { "200": { "description": "Folder agents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderAgentsList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not a tracked folder", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackedDirErrorResponse" }, "example": { "error": "Not a tracked folder: /home/me/other" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/tracked-dirs/agents/all": { "get": { "tags": [ "Tracked folders" ], "summary": "Every tracked folder with its agents", "description": "One read for a fleet view that lists stopped agents next to loaded ones. Each .adf is peeked read-only (sidecars a peek creates are removed), cached per file by the modification time and size of the file and its `-wal`, so polling opens only files that changed. The last load error an autostart pass hit (boot, POST /agents/autostart, POST /tracked-dirs) stays as `error` until the agent loads.", "operationId": "listAllTrackedAgents", "responses": { "200": { "description": "Folders with agents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackedAgentsList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/runtime": { "get": { "tags": [ "Runtime" ], "summary": "Daemon runtime overview", "description": "Process, settings, providers, auth, MCP, adapters, network, compute and every loaded agent in one read, secrets sanitized. `daemon.version` is ADF_VERSION, else the npm package version, else null.", "operationId": "getRuntime", "responses": { "200": { "description": "Overview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeOverview" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/diagnostics": { "get": { "tags": [ "Runtime" ], "summary": "Legacy per-agent health summary", "operationId": "getDiagnostics", "responses": { "200": { "description": "Diagnostics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiagnosticsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/runtime/settings": { "get": { "tags": [ "Runtime" ], "summary": "Sanitized settings summary", "operationId": "getRuntimeSettings", "responses": { "200": { "description": "Settings summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeSettingsDiagnostics" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/runtime/usage": { "get": { "tags": [ "Runtime" ], "summary": "Token usage totals by provider and model", "operationId": "getRuntimeUsage", "responses": { "200": { "description": "Usage (not attributed per agent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeUsageResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/runtime/token-count": { "post": { "tags": [ "Runtime" ], "summary": "Count tokens in one string", "description": "With neither `provider` nor `model`, `agentId` picks the loaded agent's model; default provider anthropic.", "operationId": "countRuntimeTokens", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenCountBody" } } } }, "responses": { "200": { "description": "Count", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenCountResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/runtime/token-count/batch": { "post": { "tags": [ "Runtime" ], "summary": "Count tokens in several strings", "operationId": "countRuntimeTokensBatch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenCountBatchBody" }, "example": { "texts": [ "one", "two words" ] } } } }, "responses": { "200": { "description": "Counts, in input order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenCountBatchResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/agents/{id}/runtime": { "get": { "tags": [ "Runtime" ], "summary": "One agent's runtime diagnostics", "description": "Status, adapters, MCP, triggers and WebSocket connections in one read.", "operationId": "getAgentRuntime", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Diagnostics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRuntimeDiagnostics" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/agents/{id}/runtime/triggers": { "get": { "tags": [ "Runtime" ], "summary": "One agent's trigger configuration", "operationId": "getAgentRuntimeTriggers", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Triggers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTriggersDiagnostics" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/agents/{id}/triggers": { "get": { "tags": [ "Runtime" ], "summary": "One agent's trigger configuration (same as …/runtime/triggers)", "operationId": "getAgentTriggers", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Triggers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTriggersDiagnostics" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/agents/{id}/runtime/ws": { "get": { "tags": [ "Runtime" ], "summary": "One agent's WebSocket connections", "operationId": "getAgentRuntimeWs", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Connections", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentWsDiagnostics" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/agents/{id}/ws": { "get": { "tags": [ "Runtime" ], "summary": "One agent's WebSocket connections (same as …/runtime/ws)", "operationId": "getAgentWs", "parameters": [ { "$ref": "#/components/parameters/AgentIdPath" } ], "responses": { "200": { "description": "Connections", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentWsDiagnostics" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/network": { "get": { "tags": [ "Network" ], "summary": "Network diagnostics (host, mesh, WebSockets, agents)", "operationId": "getNetworkDiagnostics", "responses": { "200": { "description": "Diagnostics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkDiagnostics" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/runtime/network": { "get": { "tags": [ "Network" ], "summary": "Network diagnostics (same as GET /network)", "operationId": "getRuntimeNetwork", "responses": { "200": { "description": "Diagnostics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkDiagnostics" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/network/mesh": { "get": { "tags": [ "Network" ], "summary": "Live mesh status", "operationId": "getMeshStatus", "responses": { "200": { "description": "Mesh status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeshStatus" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/network/mesh/enable": { "post": { "tags": [ "Network" ], "summary": "Enable mesh registration (persisted)", "description": "Persists meshEnabled: true and re-registers the loaded agents. No body.", "operationId": "enableMesh", "responses": { "200": { "description": "Enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeshToggleResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/network/mesh/disable": { "post": { "tags": [ "Network" ], "summary": "Disable mesh registration (persisted)", "description": "Persists meshEnabled: false and unregisters mesh agents without unloading them. No body.", "operationId": "disableMesh", "responses": { "200": { "description": "Disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeshToggleResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/network/mesh/recent-tools": { "get": { "tags": [ "Network" ], "summary": "Recent tool calls per mesh agent", "operationId": "getRecentMeshTools", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Calls per agent (default 5)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Recent calls", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecentMeshToolsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/network/mesh/lan-addresses": { "get": { "tags": [ "Network" ], "summary": "This host's name and LAN addresses", "operationId": "getLanAddresses", "responses": { "200": { "description": "Addresses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LanAddressesResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/network/mesh/discovered-runtimes": { "get": { "tags": [ "Network" ], "summary": "Remote mesh runtimes discovered on the LAN", "operationId": "getDiscoveredRuntimes", "responses": { "200": { "description": "Runtimes (the daemon does not discover yet: empty)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoveredRuntimesResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/network/server": { "get": { "tags": [ "Network" ], "summary": "Mesh HTTP server status", "operationId": "getMeshServerStatus", "responses": { "200": { "description": "Status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeshServerStatus" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/network/server/start": { "post": { "tags": [ "Network" ], "summary": "Start the mesh HTTP server (persisted)", "description": "The mesh server (port 7295 by default, separate from this API) serves agent cards, health, ALF inbox delivery and agent web/API routes under /agents/{handle}/*. It is on by default; this persists meshServerEnabled: true. No body.", "operationId": "startMeshServer", "responses": { "200": { "description": "Started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeshServerActionResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/network/server/stop": { "post": { "tags": [ "Network" ], "summary": "Stop the mesh HTTP server (persisted)", "description": "Persists meshServerEnabled: false, so it stays off across restarts until started again. No body.", "operationId": "stopMeshServer", "responses": { "200": { "description": "Stopped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeshServerActionResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/network/server/restart": { "post": { "tags": [ "Network" ], "summary": "Restart the mesh HTTP server", "description": "No body.", "operationId": "restartMeshServer", "responses": { "200": { "description": "Restarted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeshServerActionResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/compute/status": { "get": { "tags": [ "Compute" ], "summary": "Compute environment status", "operationId": "getComputeStatus", "responses": { "200": { "description": "Status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputeStatus" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/compute/containers": { "get": { "tags": [ "Compute" ], "summary": "List ADF compute containers", "operationId": "listComputeContainers", "responses": { "200": { "description": "Containers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputeContainersResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/compute/start": { "post": { "tags": [ "Compute" ], "summary": "Start the shared compute environment", "description": "No body.", "operationId": "startCompute", "responses": { "200": { "description": "Status after start", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputeStatus" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/compute/stop": { "post": { "tags": [ "Compute" ], "summary": "Stop the daemon's compute containers", "description": "No body.", "operationId": "stopCompute", "responses": { "200": { "description": "Status after stop", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputeStatus" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/compute/destroy": { "post": { "tags": [ "Compute" ], "summary": "Destroy the daemon's compute containers and images", "description": "No body.", "operationId": "destroyCompute", "responses": { "200": { "description": "Destroyed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputeDestroyResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/compute/setup": { "post": { "tags": [ "Compute" ], "summary": "Run a compute setup step", "description": "Studio's compute setup steps. `check` reports availability (Podman, machine, installMethods); any other step name is refused before Podman is probed. `install` runs `installCommand` only when it exactly matches the `command` of an `autoRunnable` entry in `availability.installMethods` from `check` (e.g. `/opt/homebrew/bin/brew install podman`); anything else is refused with \"Install command is not one this runtime can run automatically\" and nothing runs. Methods with a `url` are for the user to open; on Linux every method needs sudo, so `install` is always refused there. `machine_init` sizes the Podman machine from compute settings machineMemoryMb / machineCpus (missing, invalid or larger than the host: 2048 MB, 2 CPUs). Step failures answer 200 with `success: false`.", "operationId": "setupCompute", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputeSetupBody" } } } }, "responses": { "200": { "description": "Step outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputeSetupResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/compute/exec-log": { "get": { "tags": [ "Compute" ], "summary": "Recent container exec log", "operationId": "getComputeExecLog", "parameters": [ { "$ref": "#/components/parameters/ContainerNameQuery" } ], "responses": { "200": { "description": "Entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputeExecLogResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/compute/containers/{name}": { "get": { "tags": [ "Compute" ], "summary": "One container's live detail", "operationId": "getComputeContainer", "parameters": [ { "$ref": "#/components/parameters/ContainerNamePath" } ], "responses": { "200": { "description": "Detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputeContainerDetail" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/compute/containers/{name}/start": { "post": { "tags": [ "Compute" ], "summary": "Start one container", "description": "No body.", "operationId": "startComputeContainer", "parameters": [ { "$ref": "#/components/parameters/ContainerNamePath" } ], "responses": { "200": { "description": "Outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/compute/containers/{name}/stop": { "post": { "tags": [ "Compute" ], "summary": "Stop one container", "description": "No body.", "operationId": "stopComputeContainer", "parameters": [ { "$ref": "#/components/parameters/ContainerNamePath" } ], "responses": { "200": { "description": "Outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/compute/containers/{name}/destroy": { "post": { "tags": [ "Compute" ], "summary": "Destroy one container", "description": "No body.", "operationId": "destroyComputeContainer", "parameters": [ { "$ref": "#/components/parameters/ContainerNamePath" } ], "responses": { "200": { "description": "Outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/admin/mcp/packages": { "get": { "tags": [ "Admin" ], "summary": "Installed MCP packages (npm and Python)", "operationId": "listMcpPackages", "responses": { "200": { "description": "Packages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackagesResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/admin/mcp/packages/npm": { "post": { "tags": [ "Admin" ], "summary": "Install an MCP npm package", "operationId": "installMcpNpmPackage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageInstallBody" } } } }, "responses": { "200": { "description": "Installed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageInstallResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "tags": [ "Admin" ], "summary": "Uninstall an MCP npm package", "operationId": "uninstallMcpNpmPackage", "parameters": [ { "$ref": "#/components/parameters/PackageNameQuery" } ], "responses": { "200": { "description": "Uninstalled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/admin/mcp/packages/python": { "post": { "tags": [ "Admin" ], "summary": "Install an MCP Python package (uvx)", "operationId": "installMcpPythonPackage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageInstallBody" }, "example": { "package": "mcp-server-fetch" } } } }, "responses": { "200": { "description": "Installed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageInstallResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "tags": [ "Admin" ], "summary": "Uninstall an MCP Python package", "operationId": "uninstallMcpPythonPackage", "parameters": [ { "$ref": "#/components/parameters/PackageNameQuery" } ], "responses": { "200": { "description": "Uninstalled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/admin/adapters/packages": { "get": { "tags": [ "Admin" ], "summary": "Installed channel adapter packages", "operationId": "listAdapterPackages", "responses": { "200": { "description": "Packages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackagesResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "post": { "tags": [ "Admin" ], "summary": "Install a channel adapter npm package", "operationId": "installAdapterPackage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageInstallBody" } } } }, "responses": { "200": { "description": "Installed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageInstallResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "tags": [ "Admin" ], "summary": "Uninstall a channel adapter package", "operationId": "uninstallAdapterPackage", "parameters": [ { "$ref": "#/components/parameters/PackageNameQuery" } ], "responses": { "200": { "description": "Uninstalled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/admin/sandbox/packages": { "get": { "tags": [ "Admin" ], "summary": "Packages available to the code sandbox", "operationId": "listSandboxPackages", "responses": { "200": { "description": "Packages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxPackagesResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "post": { "tags": [ "Admin" ], "summary": "Install a sandbox package", "operationId": "installSandboxPackage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageInstallBody" }, "example": { "package": "lodash", "version": "4.17.21" } } } }, "responses": { "200": { "description": "Installed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxInstallResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "tags": [ "Admin" ], "summary": "Uninstall a sandbox package", "operationId": "uninstallSandboxPackage", "parameters": [ { "name": "name", "in": "query", "required": false, "description": "Package name (alias: package)", "schema": { "type": "string" }, "example": "lodash" }, { "name": "package", "in": "query", "required": false, "description": "Alias of name", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`success` is false when it was not installed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/admin/sandbox/packages/check": { "post": { "tags": [ "Admin" ], "summary": "Which of these packages are missing", "operationId": "checkSandboxPackages", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxCheckBody" } } } }, "responses": { "200": { "description": "Missing packages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxCheckResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/settings": { "get": { "tags": [ "Settings" ], "summary": "Read the settings (secrets removed)", "operationId": "getSettings", "responses": { "200": { "description": "Settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "patch": { "tags": [ "Settings" ], "summary": "Merge settings values", "description": "Never writable here (403, no `code`): ownerMnemonic, runtimePrivateKey, runtimeEncPrivateKey, mcpOauthCredentials, trustedDaemonEncKeys, ownerDid, ownerEncPublicKey, runtimeDid, runtimeEncPublicKey, runtimeDelegation, legacyOwnerDids, legacyRuntimeDids, daemonRuntimeDid, daemonRuntimeDelegation, ownerDidSeedDerived. The owner identity changes only through /identity. A providers[].apiKey of `__redacted__` keeps the stored key.", "operationId": "patchSettings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsPatchBody" }, "example": { "meshEnabled": false } } } }, "responses": { "200": { "description": "Settings after the merge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/SettingsKeyDenied" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/settings/{key}": { "get": { "tags": [ "Settings" ], "summary": "Read one setting", "description": "Secret keys read as null; providers[].apiKey as `__redacted__`.", "operationId": "getSetting", "parameters": [ { "$ref": "#/components/parameters/SettingsKeyPath" } ], "responses": { "200": { "description": "Value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingValueResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "put": { "tags": [ "Settings" ], "summary": "Write one setting", "description": "Never writable here (403, no `code`): ownerMnemonic, runtimePrivateKey, runtimeEncPrivateKey, mcpOauthCredentials, trustedDaemonEncKeys, ownerDid, ownerEncPublicKey, runtimeDid, runtimeEncPublicKey, runtimeDelegation, legacyOwnerDids, legacyRuntimeDids, daemonRuntimeDid, daemonRuntimeDelegation, ownerDidSeedDerived. The owner identity changes only through /identity. A providers[].apiKey of `__redacted__` keeps the stored key.", "operationId": "putSetting", "parameters": [ { "$ref": "#/components/parameters/SettingsKeyPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingPutBody" } } } }, "responses": { "200": { "description": "Stored value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingValueResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/SettingsKeyDenied" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "503": { "$ref": "#/components/responses/Unavailable" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Per-install token from `/daemon-token` (printed by `adf daemon token`), or ADF_DAEMON_TOKEN. Local adf clients send it automatically." } }, "parameters": { "AgentIdPath": { "name": "id", "in": "path", "required": true, "description": "Loaded agent: its id, handle or name.", "schema": { "type": "string" }, "example": "agent-1" }, "TaskIdPath": { "name": "taskId", "in": "path", "required": true, "description": "Task id (GET …/tasks)", "schema": { "type": "string" } }, "RequestIdPath": { "name": "requestId", "in": "path", "required": true, "description": "Ask request id (GET …/asks)", "schema": { "type": "string" } }, "LoopNamePath": { "name": "name", "in": "path", "required": true, "description": "Loop name (`main` or an inner loop)", "schema": { "type": "string" }, "example": "reflector" }, "TimerIdPath": { "name": "timerId", "in": "path", "required": true, "description": "Timer id", "schema": { "type": "integer" }, "example": 3 }, "PurposePath": { "name": "purpose", "in": "path", "required": true, "description": "Identity purpose, e.g. `provider:anthropic:apiKey`", "schema": { "type": "string" } }, "ProviderIdPath": { "name": "providerId", "in": "path", "required": true, "description": "Provider id in the agent config", "schema": { "type": "string" }, "example": "anthropic" }, "ServerNamePath": { "name": "serverName", "in": "path", "required": true, "description": "MCP server name in the agent config", "schema": { "type": "string" }, "example": "filesystem" }, "AdapterTypePath": { "name": "adapterType", "in": "path", "required": true, "description": "Adapter type, e.g. `telegram`", "schema": { "type": "string" }, "example": "telegram" }, "MetaKeyPath": { "name": "key", "in": "path", "required": true, "description": "Metadata key", "schema": { "type": "string" } }, "TablePath": { "name": "table", "in": "path", "required": true, "description": "Local table name (`local_*`)", "schema": { "type": "string" } }, "SettingsKeyPath": { "name": "key", "in": "path", "required": true, "description": "Settings key", "schema": { "type": "string" }, "example": "meshEnabled" }, "ContainerNamePath": { "name": "name", "in": "path", "required": true, "description": "Container name", "schema": { "type": "string" } }, "TemplateIdPath": { "name": "id", "in": "path", "required": true, "description": "Template id (the file stem in the templates folder)", "schema": { "type": "string" }, "example": "standard" }, "AppProviderIdPath": { "name": "id", "in": "path", "required": true, "description": "App provider id (settings.providers[].id)", "schema": { "type": "string" }, "example": "custom:ab12cd" }, "LoopQuery": { "name": "loop", "in": "query", "required": false, "description": "Cognition loop to address. Absent = main. Unknown loops answer 404.", "schema": { "type": "string" } }, "LimitQuery": { "name": "limit", "in": "query", "required": false, "description": "Maximum rows to return", "schema": { "type": "integer" } }, "OffsetQuery": { "name": "offset", "in": "query", "required": false, "description": "Rows to skip", "schema": { "type": "integer", "minimum": 0 } }, "AgentIdQuery": { "name": "agentId", "in": "query", "required": false, "description": "Only this agent's events", "schema": { "type": "string" } }, "SinceQuery": { "name": "since", "in": "query", "required": false, "description": "Replay buffered frames whose cursor is greater than this. Process-local; resets on daemon restart. Wins over `Last-Event-ID`.", "schema": { "type": "integer", "minimum": 0 } }, "ContainerNameQuery": { "name": "name", "in": "query", "required": false, "description": "Only this container's entries", "schema": { "type": "string" } }, "PackageNameQuery": { "name": "package", "in": "query", "required": true, "description": "Package name", "schema": { "type": "string" } }, "FilePathQuery": { "name": "path", "in": "query", "required": true, "description": "File path inside the agent", "schema": { "type": "string" }, "example": "notes/today.md" }, "AdfFilePathQuery": { "name": "filePath", "in": "query", "required": true, "description": "Absolute path of the .adf file", "schema": { "type": "string" }, "example": "/home/me/agents/agent-2.adf" }, "LocalProofHeader": { "name": "X-ADF-Local-Proof", "in": "header", "required": false, "description": "Required only when the daemon runs with `ADF_DAEMON_BEHIND_PROXY`: the contents of `/daemon-local-proof` (`daemon-local-proof-` off the default port) on the daemon host (the adf CLI and terminal app send it automatically to their own daemon).", "schema": { "type": "string" } }, "EpochQuery": { "name": "epoch", "in": "query", "required": false, "description": "The `stream.hello` epoch the resume cursor came from. A different epoch (the daemon restarted) yields `stream.gap` `epoch_changed` and a full replay.", "schema": { "type": "string" } }, "LastEventIdHeader": { "name": "Last-Event-ID", "in": "header", "required": false, "description": "Standard SSE resume header: the last `id:` (cursor) received. Same as `?since=`, which wins when both are sent. Not an integer: 400.", "schema": { "type": "string" } } }, "responses": { "Unauthorized": { "description": "Missing or wrong bearer token (`unauthorized`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "This ADF daemon requires its access token (Authorization: Bearer). The adf CLI and terminal app read it automatically on the daemon's machine; update adf if yours does not. Elsewhere pass --token or set ADF_DAEMON_TOKEN. Print the token on the daemon host with: adf daemon token", "code": "unauthorized" } } } }, "Forbidden": { "description": "The request guard refused it: Host header not allowed (`host_not_allowed`, DNS-rebinding protection) or a browser cross-site request (`cross_origin`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "host_not_allowed": { "value": { "error": "Host header not allowed for this daemon (DNS rebinding protection). Use 127.0.0.1 or localhost, or add the name to ADF_DAEMON_ALLOWED_HOSTS.", "code": "host_not_allowed" } }, "cross_origin": { "value": { "error": "Cross-origin requests are not accepted by the ADF daemon.", "code": "cross_origin" } } } } } }, "LoopbackOnly": { "description": "Not a local caller (`loopback_only`): the request came from another machine, through a proxy (forwarded headers), or — with `ADF_DAEMON_BEHIND_PROXY` — without this machine's `X-ADF-Local-Proof`. Owner secrets and shutdown are handled on the daemon host only. Or the request guard refused it: Host header not allowed (`host_not_allowed`, DNS-rebinding protection) or a browser cross-site request (`cross_origin`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "loopback_only": { "value": { "error": "Owner identity secrets can be handled only from this machine: the request came through a proxy (forwarded headers). Run the adf command on the daemon host, against the daemon's own loopback address (not through a proxy or tunnel).", "code": "loopback_only" } }, "host_not_allowed": { "value": { "error": "Host header not allowed for this daemon (DNS rebinding protection). Use 127.0.0.1 or localhost, or add the name to ADF_DAEMON_ALLOWED_HOSTS.", "code": "host_not_allowed" } }, "cross_origin": { "value": { "error": "Cross-origin requests are not accepted by the ADF daemon.", "code": "cross_origin" } } } } } }, "ReviewRequired": { "description": "The .adf must be reviewed on this machine before it loads (`AGENT_REVIEW_REQUIRED`), or the request guard refused it: Host header not allowed (`host_not_allowed`, DNS-rebinding protection) or a browser cross-site request (`cross_origin`)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ReviewRequiredResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "example": { "error": "Agent must be reviewed before loading into the runtime.", "code": "AGENT_REVIEW_REQUIRED", "agentId": "Xk3v9QpLm2", "filePath": "/home/me/agents/agent-2.adf" } } } }, "SettingsKeyDenied": { "description": "A secret or identity settings key cannot be written over HTTP (`setting_not_writable`), or the request guard refused it: Host header not allowed (`host_not_allowed`, DNS-rebinding protection) or a browser cross-site request (`cross_origin`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Settings key \"ownerDid\" cannot be written through the daemon API.", "code": "setting_not_writable" } } } }, "BadRequest": { "description": "Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (`statusCode`, `code`, `error`, `message`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "route": { "value": { "error": "limit must be an integer", "code": "bad_request" } }, "fastify": { "value": { "statusCode": 400, "code": "FST_ERR_CTP_EMPTY_JSON_BODY", "error": "Bad Request", "message": "Body cannot be empty when content-type is set to 'application/json'" } } } } } }, "NotFound": { "description": "Unknown agent (or the named resource: loop, task, file, …)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Unknown agent \"agent-9\"", "code": "not_found" } } } }, "MethodNotAllowed": { "description": "Not available on this daemon (the subsystem is read-only or lacks this operation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Settings store is read-only.", "code": "not_supported" } } } }, "Conflict": { "description": "The resource is in a state that does not allow this now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Loop \"reflector\" has no running executor (it is disabled or stopping).", "code": "conflict" } } } }, "CredentialsLocked": { "description": "Bad value (key material cannot be replaced over the API), or the agent's credentials envelope is locked on this daemon (`credentials_locked`): unlock the owner identity, or retry with `replace: true`. A legacy agent locked with a whole-file password answers 409 `credentials_locked` until POST /agents/{id}/identity/password/unlock", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "The credentials envelope of this agent is locked on this daemon — refusing to store \"provider:anthropic:apiKey\" unsealed. … Or store it anyway (replace: true): it is sealed once the envelope unlocks.", "code": "credentials_locked" } } } }, "IdentityNotReady": { "description": "No usable owner identity (`identity_not_ready`): set it up or unlock it first. `identity` carries its status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreateErrorResponse" }, "example": { "error": "Set up the owner identity first. …", "code": "identity_not_ready", "identity": { "status": "none", "ownerDid": null, "runtimeDid": null, "storage": "keychain", "backupConfirmed": false, "passphraseRequired": false, "message": "No owner identity yet." } } } } }, "ServerError": { "description": "Unexpected runtime failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "SQLITE_BUSY: database is locked", "code": "internal_error" } } } }, "BadGateway": { "description": "An upstream call failed (e.g. the summarization request of a compaction); nothing was changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Compaction failed: provider returned 529", "code": "upstream_error" } } } }, "Unavailable": { "description": "The subsystem is not configured on this daemon", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Settings store is not configured.", "code": "unavailable" } } } } }, "schemas": { "AbortResponse": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "const": true }, "loop": { "type": "string", "description": "Echoed when a loop was named" } } }, "AcceptedTurn": { "type": "object", "required": [ "accepted", "turnId" ], "properties": { "accepted": { "type": "boolean", "const": true }, "turnId": { "type": "string", "description": "Correlation id: the events of the turn that handles this request carry it as `event.turn_id` on GET /events" } }, "example": { "accepted": true, "turnId": "turn_V1StGXR8_Z5j" } }, "AdapterAttachBody": { "type": "object", "required": [ "adapterType", "config" ], "properties": { "adapterType": { "type": "string" }, "config": { "$ref": "#/components/schemas/AdapterInstanceConfig" } }, "example": { "adapterType": "telegram", "config": { "enabled": true } } }, "AdapterAttachResponse": { "type": "object", "required": [ "agentId", "adapterType", "success", "alreadyAttached", "config" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "adapterType": { "type": "string" }, "success": { "type": "boolean", "const": true }, "alreadyAttached": { "type": "boolean" }, "config": { "$ref": "#/components/schemas/AgentConfig" } } }, "AdapterCredentialBody": { "type": "object", "required": [ "adapterType", "envKey", "value" ], "properties": { "adapterType": { "type": "string" }, "envKey": { "type": "string" }, "value": { "type": "string" }, "replace": { "type": "boolean", "description": "Owner override while the agent's credentials envelope is locked on this daemon: a locked sealed value is discarded unread and the new value is stored plain, sealed again on unlock; logged to adf_logs (`credential_replaced`). Without it such a write answers 409 `credentials_locked`." } }, "example": { "adapterType": "telegram", "envKey": "TELEGRAM_BOT_TOKEN", "value": "…" } }, "AdapterCredentialsResponse": { "type": "object", "required": [ "agentId", "adapterType", "credentials" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "adapterType": { "type": "string" }, "credentials": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/CredentialMeta" }, "description": "By env key" } } }, "AdapterCredentialWriteResponse": { "type": "object", "required": [ "agentId", "adapterType", "envKey", "success" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "adapterType": { "type": "string" }, "envKey": { "type": "string" }, "success": { "type": "boolean", "const": true }, "replaced": { "type": "boolean" } } }, "AdapterDetachResponse": { "type": "object", "required": [ "agentId", "adapterType", "success", "deletedCredentials", "config" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "adapterType": { "type": "string" }, "success": { "type": "boolean", "const": true }, "deletedCredentials": { "type": "integer" }, "config": { "$ref": "#/components/schemas/AgentConfig" } } }, "AdapterInstanceConfig": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "config": { "type": "object", "additionalProperties": true, "description": "Adapter-specific settings (no secrets: tokens are credentials)" }, "policy": { "type": "object", "additionalProperties": true }, "limits": { "type": "object", "properties": { "max_attachment_size": { "type": "integer", "description": "Bytes" } } } }, "example": { "enabled": true, "config": {} } }, "AdapterRegistrationsDiagnostics": { "type": "object", "required": [ "adapters" ], "properties": { "adapters": { "type": "array", "items": { "type": "object", "required": [ "id", "type", "managed" ], "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "npmPackage": { "type": "string" }, "managed": { "type": "boolean" }, "version": { "type": "string" } } } } } }, "AdapterState": { "type": "object", "required": [ "type", "status", "restartCount", "logs" ], "properties": { "type": { "type": "string" }, "status": { "type": "string", "enum": [ "connected", "connecting", "disconnected", "error" ] }, "error": { "type": "string" }, "connectedAt": { "type": "integer" }, "restartCount": { "type": "integer" }, "logs": { "type": "array", "items": { "type": "object", "required": [ "timestamp", "level", "message" ], "properties": { "timestamp": { "type": "integer" }, "level": { "type": "string", "enum": [ "info", "warn", "error", "system" ] }, "message": { "type": "string" } } } } }, "additionalProperties": true }, "AddProviderBody": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "anthropic", "openai", "openrouter", "openai-compatible" ] }, "name": { "type": "string" }, "baseUrl": { "type": "string", "description": "Required for openai-compatible" }, "defaultModel": { "type": "string" }, "preset": { "type": "string", "description": "Provider catalog key (e.g. groq)" }, "apiKey": { "type": "string", "description": "Required except for openai-compatible. Stored in the daemon secret store, never returned." } }, "example": { "type": "anthropic", "apiKey": "sk-ant-…" } }, "AddProviderResponse": { "type": "object", "required": [ "provider", "defaultProviderId" ], "properties": { "provider": { "$ref": "#/components/schemas/PublicProvider" }, "defaultProviderId": { "type": [ "string", "null" ] } } }, "AdfBatchDispatch": { "type": "object", "required": [ "events" ], "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/AdfEvent" }, "minItems": 1 }, "count": { "type": "integer" }, "target": { "$ref": "#/components/schemas/DispatchTarget" }, "scope": { "type": "string", "enum": [ "agent", "system" ] }, "lambda": { "type": "string" }, "command": { "type": "string" }, "warm": { "type": "boolean" }, "loop": { "type": "string" } }, "additionalProperties": true }, "AdfEvent": { "type": "object", "required": [ "type" ], "properties": { "id": { "type": "string", "description": "Default: generated" }, "type": { "type": "string", "enum": [ "inbox", "outbox", "file_change", "chat", "timer", "tool_call", "task_create", "task_complete", "log_entry", "startup", "llm_call" ] }, "source": { "type": "string", "description": "Default: `daemon:http`" }, "time": { "type": "string", "description": "ISO 8601; default: now" }, "data": { "description": "Event payload; required (use null) for every type except startup. `data.message.source: \"user\"` and the internal flags `skip_loop_append` / `pre_appended_loop` are refused." }, "correlationId": { "type": "string" } }, "additionalProperties": true }, "AdfEventDispatch": { "type": "object", "description": "Target fields may sit at the top level or under `target` (default scope: agent).", "required": [ "event" ], "properties": { "event": { "$ref": "#/components/schemas/AdfEvent" }, "target": { "$ref": "#/components/schemas/DispatchTarget" }, "scope": { "type": "string", "enum": [ "agent", "system" ] }, "lambda": { "type": "string" }, "command": { "type": "string" }, "warm": { "type": "boolean" }, "loop": { "type": "string" } }, "additionalProperties": true }, "AgentAdaptersDiagnostics": { "type": "object", "required": [ "agentId", "configured", "states" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "configured": { "type": "array", "items": { "type": "object", "required": [ "type", "enabled", "config" ], "properties": { "type": { "type": "string" }, "enabled": { "type": "boolean" }, "config": { "type": "object", "additionalProperties": true } } } }, "states": { "type": "array", "items": { "$ref": "#/components/schemas/AdapterState" } } } }, "AgentConfig": { "type": "object", "description": "The agent's ADF v0.2 config (adf_config). Only the most used fields are listed; the full shape is the ADF spec's AgentConfig. Secret values never appear here.", "required": [ "adf_version", "id", "name", "description", "state", "autonomous", "model", "instructions", "context", "tools", "triggers", "security", "limits", "messaging", "metadata" ], "properties": { "adf_version": { "type": "string", "const": "0.2" }, "id": { "type": "string", "description": "Agent id (stable, the daemon addresses the agent by it)" }, "name": { "type": "string" }, "description": { "type": "string" }, "handle": { "type": "string" }, "icon": { "type": "string" }, "state": { "$ref": "#/components/schemas/DisplayState" }, "autonomous": { "type": "boolean" }, "autostart": { "type": "boolean" }, "model": { "$ref": "#/components/schemas/ModelConfig" }, "instructions": { "type": "string" }, "context": { "type": "object", "additionalProperties": true, "description": "compact_threshold, audit, dynamic_instructions" }, "tools": { "type": "array", "items": { "type": "object", "required": [ "name", "enabled" ], "properties": { "name": { "type": "string" }, "enabled": { "type": "boolean" }, "visible": { "type": "boolean" }, "restricted": { "type": "boolean" }, "locked": { "type": "boolean" } }, "additionalProperties": true }, "description": "Tool declarations" }, "triggers": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TriggerConfig" }, "description": "on_startup, on_inbox, on_outbox, on_file_change, on_chat, on_timer, on_tool_call, on_task_create, on_task_complete, on_logs, on_llm_call" }, "security": { "type": "object", "additionalProperties": true }, "limits": { "type": "object", "additionalProperties": true }, "messaging": { "type": "object", "additionalProperties": true, "description": "mode (proactive | respond_only | listen_only), receive, network, …" }, "mcp": { "type": "object", "required": [ "servers" ], "properties": { "servers": { "type": "array", "items": { "$ref": "#/components/schemas/McpServerConfig" } }, "new_tools_restricted": { "type": "boolean" } } }, "adapters": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/AdapterInstanceConfig" }, "description": "Channel adapters by type" }, "providers": { "type": "array", "items": { "$ref": "#/components/schemas/AgentProviderConfig" } }, "loops": { "type": "array", "items": { "$ref": "#/components/schemas/LoopConfig" }, "description": "Inner (side) loops; `main` is implicit" }, "ws_connections": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "serving": { "type": "object", "additionalProperties": true }, "locked_fields": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true, "description": "created_at, updated_at, author, tags, version" } }, "additionalProperties": true }, "AgentConfigResponse": { "type": "object", "required": [ "agentId", "config" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "config": { "$ref": "#/components/schemas/AgentConfig" } } }, "AgentConfigUpdateResponse": { "type": "object", "required": [ "agentId", "success", "config" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "success": { "type": "boolean", "const": true }, "config": { "$ref": "#/components/schemas/AgentConfig" } } }, "AgentContextResponse": { "type": "object", "required": [ "agentId", "loop", "available", "model", "compactThreshold", "compactThresholdSource", "agentCompactThreshold", "totalTokens", "percent", "categories", "breakdown" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "loop": { "type": "string" }, "available": { "type": "boolean", "description": "False when the loop has no live executor" }, "model": { "type": "object", "required": [ "provider", "modelId" ], "properties": { "provider": { "type": [ "string", "null" ] }, "modelId": { "type": [ "string", "null" ] } } }, "compactThreshold": { "type": "integer" }, "compactThresholdSource": { "type": "string", "enum": [ "loop", "agent", "model", "default" ] }, "agentCompactThreshold": { "type": "integer" }, "totalTokens": { "type": [ "integer", "null" ] }, "percent": { "type": [ "integer", "null" ], "description": "totalTokens / compactThreshold, rounded percent" }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/ContextCategory" } }, "breakdown": { "oneOf": [ { "$ref": "#/components/schemas/ContextBreakdown" }, { "type": "null" } ] } } }, "AgentCreateErrorResponse": { "type": "object", "description": "Template and agent-creation errors. `identity` is the owner identity status when `code` is `identity_not_ready`.", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "bad_request", "identity_not_ready", "name_taken", "template_missing", "template_unreviewed", "template_invalid", "password_required", "wrong_password", "load_failed" ] }, "identity": { "$ref": "#/components/schemas/IdentityStatus" } } }, "AgentDidResponse": { "type": "object", "required": [ "agentId", "did" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "did": { "type": [ "string", "null" ] } }, "example": { "agentId": "Xk3v9QpLm2", "did": "did:key:z6Mk…" } }, "AgentFilesResponse": { "type": "object", "required": [ "agentId", "files" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/FileListEntry" } } } }, "AgentIdentityMetaResponse": { "allOf": [ { "$ref": "#/components/schemas/CredentialMeta" }, { "type": "object", "required": [ "agentId" ], "properties": { "agentId": { "type": "string" } } } ] }, "AgentList": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSummary" } }, "AgentLogsResponse": { "type": "object", "required": [ "agentId", "logs" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "logs": { "type": "array", "items": { "$ref": "#/components/schemas/LogEntry" } } } }, "AgentMcpDiagnostics": { "type": "object", "required": [ "agentId", "configured", "states" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "configured": { "type": "array", "items": { "type": "object", "required": [ "name", "toolCount" ], "properties": { "name": { "type": "string" }, "transport": { "type": "string" }, "command": { "type": "string" }, "args": { "type": "array", "items": { "type": "string" } }, "toolCount": { "type": "integer" } } } }, "states": { "type": "array", "items": { "$ref": "#/components/schemas/McpServerState" } } } }, "AgentProviderConfig": { "type": "object", "description": "A provider carried in the agent's own config. Its API key is a credential (PUT …/providers/{providerId}/credential), never part of this object.", "required": [ "id", "type", "name", "baseUrl" ], "properties": { "id": { "type": "string", "description": "`anthropic`, `openai`, … or `custom:`" }, "type": { "type": "string", "enum": [ "anthropic", "openai", "openai-compatible", "openrouter" ] }, "name": { "type": "string" }, "baseUrl": { "type": "string" }, "preset": { "type": "string" }, "defaultModel": { "type": "string" }, "params": { "type": "array", "items": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string" }, "value": { "type": "string" } } } }, "requestDelayMs": { "type": "integer" } }, "example": { "id": "custom:ab12cd", "type": "openai-compatible", "name": "Local LLM", "baseUrl": "http://127.0.0.1:11434/v1" } }, "AgentRef": { "type": "object", "required": [ "id", "filePath", "config" ], "properties": { "id": { "type": "string" }, "filePath": { "type": [ "string", "null" ] }, "config": { "$ref": "#/components/schemas/AgentConfig" } } }, "AgentRuntimeDiagnostics": { "type": "object", "required": [ "agentId", "adapters", "mcp", "triggers", "ws" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "status": { "$ref": "#/components/schemas/AgentStatus" }, "adapters": { "$ref": "#/components/schemas/AgentAdaptersDiagnostics" }, "mcp": { "$ref": "#/components/schemas/AgentMcpDiagnostics" }, "triggers": { "$ref": "#/components/schemas/AgentTriggersDiagnostics" }, "ws": { "type": "object", "required": [ "configured", "active" ], "properties": { "configured": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "active": { "type": "array", "items": { "$ref": "#/components/schemas/WsConnectionInfo" } } } } } }, "AgentStatus": { "allOf": [ { "$ref": "#/components/schemas/AgentSummary" }, { "type": "object", "required": [ "runtimeState", "targetState", "loopCount" ], "properties": { "runtimeState": { "type": "string", "description": "Executor state: idle, thinking, tool_use, awaiting_approval, awaiting_ask, suspended, error, stopped — or a display state (active, hibernate, off)" }, "targetState": { "type": [ "string", "null" ] }, "loopCount": { "type": "integer", "description": "Persisted entries in main's loop stream" }, "degraded": { "type": "string", "description": "Set when the agent loaded but cannot fully function (CREDENTIALS_LOCKED: its credentials envelope is locked); cleared once the owner identity unlocks it" } } } ], "example": { "id": "Xk3v9QpLm2", "filePath": "/home/me/agents/agent-1.adf", "name": "agent-1", "handle": "agent-1", "autostart": true, "runtimeState": "idle", "targetState": null, "loopCount": 1 } }, "AgentSuccess": { "type": "object", "required": [ "agentId", "success" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "success": { "type": "boolean" } }, "example": { "agentId": "Xk3v9QpLm2", "success": true } }, "AgentSummary": { "type": "object", "required": [ "id", "filePath", "name", "autostart" ], "properties": { "id": { "type": "string" }, "filePath": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "handle": { "type": "string" }, "autostart": { "type": "boolean" } }, "example": { "id": "Xk3v9QpLm2", "filePath": "/home/me/agents/agent-1.adf", "name": "agent-1", "handle": "agent-1", "autostart": true } }, "AgentToolsResponse": { "type": "object", "required": [ "agentId", "tools" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolEntry" } } } }, "AgentTriggersDiagnostics": { "type": "object", "required": [ "agentId", "displayState", "configured" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "displayState": { "type": [ "string", "null" ] }, "configured": { "type": "array", "items": { "type": "object", "required": [ "type", "enabled", "targetCount", "targets" ], "properties": { "type": { "type": "string" }, "enabled": { "type": "boolean" }, "targetCount": { "type": "integer" }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/TriggerTarget" } } } } } } }, "AgentUsageResponse": { "type": "object", "required": [ "agentId", "source", "note", "loopRows", "usageRows", "totals", "byModel" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "source": { "type": "string", "const": "adf_loop" }, "note": { "type": "string" }, "loopRows": { "type": "integer" }, "usageRows": { "type": "integer" }, "totals": { "$ref": "#/components/schemas/UsageTotals" }, "byModel": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/UsageTotals" }, { "type": "object", "required": [ "model", "rows" ], "properties": { "model": { "type": "string" }, "rows": { "type": "integer" } } } ] } } } }, "AgentWsDiagnostics": { "type": "object", "required": [ "agentId", "configured", "active", "recentLogs" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "configured": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "config.ws_connections" }, "active": { "type": "array", "items": { "$ref": "#/components/schemas/WsConnectionInfo" } }, "recentLogs": { "type": "array", "items": { "$ref": "#/components/schemas/LogEntry" }, "description": "Last 50 websocket-origin log rows" } } }, "ApproveAllBody": { "type": "object", "properties": { "loop": { "type": "string", "description": "Only this loop's approvals" } }, "additionalProperties": false }, "ApproveAllResponse": { "type": "object", "required": [ "agentId", "approved", "skippedProtection" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "loop": { "type": "string" }, "approved": { "type": "integer" }, "skippedProtection": { "type": "integer" } }, "example": { "agentId": "Xk3v9QpLm2", "approved": 2, "skippedProtection": 1 } }, "AskRespondBody": { "type": "object", "required": [ "answer" ], "properties": { "answer": { "type": "string" }, "loop": { "type": "string", "description": "The loop that asked (GET …/asks lists it); absent = the first loop holding the id" } }, "example": { "answer": "Yes, go ahead." } }, "AskRespondResponse": { "type": "object", "required": [ "agentId", "requestId", "loop", "answered" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "requestId": { "type": "string" }, "loop": { "type": "string" }, "answered": { "type": "boolean" } } }, "AsksResponse": { "type": "object", "required": [ "agentId", "asks" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "asks": { "type": "array", "items": { "type": "object", "required": [ "requestId", "question", "loop" ], "properties": { "requestId": { "type": "string" }, "question": { "type": "string" }, "loop": { "type": "string", "description": "The loop waiting on the answer" } } } } } }, "AuthDiagnostics": { "type": "object", "required": [ "chatgpt", "grok", "providers" ], "properties": { "chatgpt": { "$ref": "#/components/schemas/SubscriptionAuthStatus" }, "grok": { "$ref": "#/components/schemas/SubscriptionAuthStatus" }, "providers": { "type": "array", "items": { "type": "object", "required": [ "id", "type", "name", "credentialStorage", "hasApiKey" ], "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "credentialStorage": { "type": "string" }, "hasApiKey": { "type": "boolean" } } } } } }, "AuthRecovery": { "type": "object", "required": [ "agentId", "filePath", "loop", "notice" ], "properties": { "agentId": { "type": "string" }, "filePath": { "type": [ "string", "null" ] }, "loop": { "type": "string" }, "notice": { "type": "string" } } }, "AutostartBody": { "type": "object", "required": [ "trackedDirs" ], "properties": { "trackedDirs": { "type": "array", "items": { "type": "string" } }, "maxDepth": { "type": "integer" } }, "example": { "trackedDirs": [ "/home/me/agents" ], "maxDepth": 5 } }, "AutostartReport": { "type": "object", "required": [ "scanned", "started", "skipped", "failed" ], "properties": { "scanned": { "type": "integer", "description": ".adf files found" }, "started": { "type": "array", "items": { "type": "object", "required": [ "agentId", "filePath", "name", "startupTriggered" ], "properties": { "agentId": { "type": "string" }, "filePath": { "type": "string" }, "name": { "type": "string" }, "startupTriggered": { "type": "boolean" } } } }, "skipped": { "type": "array", "items": { "type": "object", "required": [ "filePath", "name", "reason" ], "properties": { "filePath": { "type": "string" }, "name": { "type": "string" }, "reason": { "type": "string", "enum": [ "already_loaded", "not_autostart", "password_protected", "unreviewed" ] }, "agentId": { "type": "string" } } } }, "failed": { "type": "array", "items": { "type": "object", "required": [ "filePath", "name", "error" ], "properties": { "filePath": { "type": "string" }, "name": { "type": "string" }, "error": { "type": "string" } } } } }, "example": { "scanned": 2, "started": [ { "agentId": "Xk3v9QpLm2", "filePath": "/home/me/agents/agent-1.adf", "name": "agent-1", "startupTriggered": true } ], "skipped": [ { "filePath": "/home/me/agents/agent-2.adf", "name": "agent-2", "reason": "unreviewed" } ], "failed": [] } }, "ChatBody": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string" }, "loop": { "type": "string", "description": "Cognition loop to talk to; absent = main. Unknown loop: 404; disabled loop: 409." } }, "example": { "text": "Summarize today's inbox." } }, "ChatClearResponse": { "type": "object", "required": [ "agentId", "loop", "success" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "loop": { "type": "string" }, "success": { "type": "boolean", "const": true } } }, "ChatGptAuthCompleteRequest": { "type": "object", "required": [ "flowId", "code", "state" ], "properties": { "flowId": { "type": "string" }, "code": { "type": "string", "description": "Authorization code from the caller's OAuth callback" }, "state": { "type": "string" } } }, "ChatGptAuthCompleteResponse": { "type": "object", "required": [ "success", "status", "recovered" ], "properties": { "success": { "type": "boolean", "const": true }, "status": { "$ref": "#/components/schemas/SubscriptionAuthStatus" }, "recovered": { "type": "array", "items": { "$ref": "#/components/schemas/AuthRecovery" }, "description": "Loops that left `error` after this sign-in" } } }, "ChatGptAuthStartRequest": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "loopback", "relay" ], "description": "Where the OAuth callback is served (default loopback)" }, "redirectUri": { "type": "string", "description": "Relay mode only, and required there: the caller's own loopback callback URL" } }, "example": { "mode": "relay", "redirectUri": "http://127.0.0.1:1455/auth/callback" } }, "ChatGptAuthStartResponse": { "type": "object", "required": [ "started", "mode", "authUrl" ], "properties": { "started": { "type": "boolean", "const": true }, "mode": { "type": "string", "enum": [ "loopback", "relay" ] }, "authUrl": { "type": "string" }, "callbackPort": { "type": "integer", "description": "Loopback mode: the port the daemon listens on" }, "flowId": { "type": "string", "description": "Relay mode: pass to /auth/chatgpt/complete" }, "state": { "type": "string", "description": "Relay mode: echo back with the code" }, "expiresAt": { "type": "integer", "description": "Relay mode: epoch ms after which the flow is discarded" } } }, "ChatHistoryResponse": { "type": "object", "required": [ "agentId", "loop", "chatHistory" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "loop": { "type": "string" }, "chatHistory": { "type": [ "object", "null" ], "required": [ "version", "uiLog", "llmMessages", "total", "earlierCount" ], "properties": { "version": { "type": "integer" }, "uiLog": { "type": "array", "items": { "$ref": "#/components/schemas/DisplayEntry" } }, "llmMessages": { "type": "array", "items": {} }, "total": { "type": "integer" }, "earlierCount": { "type": "integer" } } } } }, "CompactResponse": { "type": "object", "required": [ "agentId", "loop", "success" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "loop": { "type": "string" }, "success": { "type": "boolean", "const": true } } }, "ComputeContainer": { "type": "object", "required": [ "name", "status", "running" ], "properties": { "name": { "type": "string" }, "status": { "type": "string" }, "running": { "type": "boolean" } } }, "ComputeContainerDetail": { "type": "object", "required": [ "success", "overview", "processes", "packages", "workspace", "logs", "inspect" ], "properties": { "success": { "type": "boolean", "const": true }, "overview": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Parsed `podman inspect` summary" }, "processes": { "type": "string" }, "packages": { "type": "string" }, "workspace": { "type": "string" }, "logs": { "type": "string" }, "inspect": { "type": "string", "description": "Raw `podman inspect` JSON" } } }, "ComputeContainersResponse": { "type": "object", "required": [ "containers" ], "properties": { "containers": { "type": "array", "items": { "$ref": "#/components/schemas/ComputeContainer" } } } }, "ComputeDestroyResponse": { "type": "object", "required": [ "success", "status" ], "properties": { "success": { "type": "boolean", "const": true }, "status": { "$ref": "#/components/schemas/ComputeStatus" } } }, "ComputeExecLogEntry": { "type": "object", "required": [ "timestamp", "containerName", "command", "exitCode", "stdout", "stderr", "durationMs" ], "properties": { "timestamp": { "type": "integer" }, "containerName": { "type": "string" }, "command": { "type": "string" }, "exitCode": { "type": "integer" }, "stdout": { "type": "string", "description": "Truncated" }, "stderr": { "type": "string", "description": "Truncated" }, "durationMs": { "type": "integer" } } }, "ComputeExecLogResponse": { "type": "object", "required": [ "entries" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/ComputeExecLogEntry" } } } }, "ComputeSetupBody": { "type": "object", "required": [ "step" ], "properties": { "step": { "type": "string", "enum": [ "install", "machine_init", "machine_start", "check" ] }, "installCommand": { "type": "string", "description": "step=install: must exactly match an autoRunnable command in availability.installMethods from step=check; anything else is refused" } }, "example": { "step": "check" } }, "ComputeSetupResponse": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" }, "error": { "type": "string" }, "availability": { "type": "object", "additionalProperties": true, "description": "Podman availability: binPath, version, machine state, installMethods, prerequisites" } }, "additionalProperties": true }, "ComputeStatus": { "type": "object", "required": [ "status", "containerName", "activeAgents" ], "properties": { "status": { "type": "string", "enum": [ "not_installed", "machine_stopped", "stopped", "starting", "running", "error" ] }, "containerName": { "type": "string" }, "activeAgents": { "type": "array", "items": { "type": "string" } }, "error": { "type": "string" } }, "example": { "status": "running", "containerName": "adf-mcp", "activeAgents": [ "agent-1" ] } }, "ContextBreakdown": { "type": "object", "required": [ "system_prompt_tokens", "system_prompt_parts", "injected_files", "tool_groups", "tools_total_tokens", "dynamic_instructions_tokens", "messages_tokens", "overhead_tokens", "computed_at" ], "properties": { "system_prompt_tokens": { "type": "integer" }, "system_prompt_parts": { "type": "object", "required": [ "base_and_sections", "runtime_blocks", "instructions" ], "properties": { "base_and_sections": { "type": "integer" }, "runtime_blocks": { "type": "integer" }, "instructions": { "type": "integer" } } }, "injected_files": { "type": "array", "items": { "type": "object", "required": [ "path", "tokens" ], "properties": { "path": { "type": "string" }, "tokens": { "type": "integer" } } } }, "tool_groups": { "type": "array", "items": { "type": "object", "required": [ "source", "tokens", "tools" ], "properties": { "source": { "type": "string", "description": "`built-in` or the MCP server name" }, "tokens": { "type": "integer" }, "tools": { "type": "array", "items": { "type": "object", "required": [ "name", "tokens" ], "properties": { "name": { "type": "string" }, "tokens": { "type": "integer" } } } } } } }, "tools_total_tokens": { "type": "integer" }, "dynamic_instructions_tokens": { "type": "integer" }, "messages_tokens": { "type": "integer" }, "overhead_tokens": { "type": "integer" }, "computed_at": { "type": "integer", "description": "Epoch ms" } } }, "ContextCategory": { "type": "object", "required": [ "id", "key", "label", "tokens", "items", "note" ], "properties": { "id": { "type": "string", "description": "The key, or `mcp:`" }, "key": { "type": "string", "enum": [ "system", "files", "tools", "mcp", "dynamic", "messages" ] }, "label": { "type": "string" }, "tokens": { "type": "integer" }, "count": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "required": [ "name", "tokens" ], "properties": { "name": { "type": "string" }, "tokens": { "type": "integer" }, "detail": { "type": "string" } } } }, "note": { "type": "string" } } }, "CreateAgentBody": { "type": "object", "properties": { "name": { "type": "string", "description": "File name (<= 64 chars). Omitted: a generated adjective-plant name." }, "directory": { "type": "string", "description": "Absolute, existing directory. Default: settings.agentsFolder, else ~/Documents/adf-agents." }, "template": { "type": "string", "description": "Template id (GET /templates). Default: settings.defaultTemplateId, else `standard`." }, "provider": { "type": "string", "description": "App provider id (must exist in settings.providers)" }, "model": { "type": "string" }, "start": { "type": "boolean", "default": false } }, "example": { "name": "agent-1", "template": "standard", "start": true } }, "CreateAgentResponse": { "type": "object", "required": [ "agentId", "name", "filePath", "did", "started" ], "properties": { "agentId": { "type": "string" }, "name": { "type": "string" }, "filePath": { "type": "string" }, "did": { "type": "string" }, "started": { "type": "boolean" } }, "example": { "agentId": "Xk3v9QpLm2", "name": "agent-1", "filePath": "/home/me/Documents/adf-agents/agent-1.adf", "did": "did:key:z6Mk…", "started": true } }, "CredentialMeta": { "type": "object", "description": "What the API reveals about one stored identity value: never the value.", "required": [ "purpose", "present", "storage", "sealed", "locked", "length", "code_access" ], "properties": { "purpose": { "type": "string" }, "present": { "type": "boolean" }, "storage": { "type": [ "string", "null" ], "enum": [ "sealed", "plain", "password", null ] }, "sealed": { "type": "boolean" }, "locked": { "type": "boolean", "description": "Stored but not readable in this process" }, "length": { "type": [ "integer", "null" ], "description": "null for crypto:* purposes and locked values" }, "code_access": { "type": "boolean" } }, "example": { "purpose": "provider:anthropic:apiKey", "present": true, "storage": "sealed", "sealed": true, "locked": false, "length": 108, "code_access": false } }, "DiagnosticsResponse": { "type": "object", "description": "Legacy per-agent health summary; prefer GET /runtime.", "required": [ "daemon", "agents" ], "properties": { "daemon": { "type": "object", "required": [ "uptime", "pid" ], "properties": { "uptime": { "type": "number" }, "pid": { "type": "integer" } } }, "agents": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/AgentSummary" }, { "type": "object", "required": [ "adapters", "mcp", "ws" ], "properties": { "status": { "$ref": "#/components/schemas/AgentStatus" }, "adapters": { "type": "array", "items": { "type": "object", "required": [ "type", "status" ], "properties": { "type": { "type": "string" }, "status": { "type": "string" }, "error": { "type": "string" } } } }, "mcp": { "type": "array", "items": { "type": "object", "required": [ "name", "status", "toolCount" ], "properties": { "name": { "type": "string" }, "status": { "type": "string" }, "error": { "type": "string" }, "toolCount": { "type": "integer" } } } }, "ws": { "type": "object", "required": [ "configured", "active" ], "properties": { "configured": { "type": "integer" }, "active": { "type": "integer" } } } } } ] } } } }, "DiscoveredRuntimesResponse": { "type": "object", "required": [ "runtimes" ], "properties": { "runtimes": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "DispatchTarget": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "agent", "system" ] }, "lambda": { "type": "string" }, "command": { "type": "string" }, "warm": { "type": "boolean" }, "loop": { "type": "string" } }, "additionalProperties": false }, "DisplayEntry": { "type": "object", "required": [ "id", "type", "content", "timestamp" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "text", "tool_call", "tool_result", "thinking", "error", "trigger", "compaction", "context" ] }, "content": { "type": "string" }, "timestamp": { "type": "integer" }, "metadata": { "type": "object", "additionalProperties": true } } }, "DisplayState": { "type": "string", "enum": [ "active", "idle", "hibernate", "suspended", "off" ], "description": "Display (fleet-map) state of an agent" }, "DisplayStateBody": { "type": "object", "required": [ "state" ], "properties": { "state": { "$ref": "#/components/schemas/DisplayState" } }, "example": { "state": "idle" } }, "DisplayStateResponse": { "type": "object", "required": [ "agentId", "success", "state" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "success": { "type": "boolean", "const": true }, "state": { "$ref": "#/components/schemas/DisplayState" } } }, "ErrorResponse": { "type": "object", "description": "Every error body. Some routes add fields (e.g. `identity`, `coveredBy`, `agentId`).", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable message" }, "code": { "type": "string", "description": "Stable machine-readable code. Every error body has one: route-specific where listed, else the status default (400 bad_request, 403 forbidden, 404 not_found, 405 not_supported, 409 conflict, 500 internal_error, 502 upstream_error, 503 unavailable)" } }, "additionalProperties": true, "example": { "error": "Unknown agent \"agent-1\"", "code": "not_found" } }, "EventFrame": { "type": "object", "description": "The `data` of one SSE frame. The SSE `id` is the cursor, the SSE `event` is event.event_type.", "required": [ "cursor", "event" ], "properties": { "cursor": { "type": "integer", "description": "Resume token for ?since= / Last-Event-ID (process-local; see the stream.hello epoch)" }, "event": { "$ref": "#/components/schemas/UmbilicalEvent" } } }, "FileAuthorizedBody": { "type": "object", "required": [ "path", "authorized" ], "properties": { "path": { "type": "string" }, "authorized": { "type": "boolean" } }, "additionalProperties": false }, "FileContentResponse": { "type": "object", "required": [ "agentId", "path", "mime_type", "size", "protection", "authorized", "created_at", "updated_at", "encoding" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "path": { "type": "string" }, "mime_type": { "type": [ "string", "null" ] }, "size": { "type": "integer" }, "protection": { "$ref": "#/components/schemas/FileProtection" }, "authorized": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "encoding": { "type": "string", "enum": [ "utf-8", "base64" ] }, "content": { "type": "string", "description": "utf-8 files" }, "content_base64": { "type": "string", "description": "Binary files" } }, "example": { "agentId": "Xk3v9QpLm2", "path": "mind.md", "mime_type": "text/markdown", "size": 12, "protection": "none", "authorized": false, "created_at": "2026-09-01T10:00:00.000Z", "updated_at": "2026-09-01T10:00:00.000Z", "encoding": "utf-8", "content": "# Mind\n" } }, "FileListEntry": { "type": "object", "required": [ "path", "size", "protection", "authorized", "created_at", "updated_at" ], "properties": { "path": { "type": "string" }, "size": { "type": "integer" }, "mime_type": { "type": "string" }, "protection": { "$ref": "#/components/schemas/FileProtection" }, "authorized": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "FileProtection": { "type": "string", "enum": [ "none", "read_only", "no_delete" ] }, "FileProtectionBody": { "type": "object", "required": [ "path", "protection" ], "properties": { "path": { "type": "string" }, "protection": { "$ref": "#/components/schemas/FileProtection" } }, "additionalProperties": false }, "FileRenameBody": { "type": "object", "required": [ "oldPath", "newPath" ], "properties": { "oldPath": { "type": "string" }, "newPath": { "type": "string" } }, "additionalProperties": false }, "FileWriteBody": { "type": "object", "description": "One of content / content_base64 is required.", "properties": { "content": { "type": "string", "description": "Text content" }, "content_base64": { "type": "string", "description": "Binary content (alias: contentBase64)" }, "contentBase64": { "type": "string" }, "mime_type": { "type": "string", "description": "Alias: mimeType" }, "mimeType": { "type": "string" }, "protection": { "$ref": "#/components/schemas/FileProtection" } }, "additionalProperties": false, "example": { "content": "hello\n", "mime_type": "text/plain" } }, "FolderAgent": { "type": "object", "required": [ "filePath", "name", "status", "autostart", "reviewed" ], "properties": { "filePath": { "type": "string" }, "name": { "type": "string" }, "agentId": { "type": "string" }, "status": { "type": "string", "enum": [ "loaded", "needs_review", "not_autostart", "stopped", "password_protected", "unreadable" ] }, "autostart": { "type": "boolean" }, "reviewed": { "type": "boolean" }, "error": { "type": "string", "description": "Load error or why the file is unreadable" } }, "example": { "filePath": "/home/me/agents/agent-2.adf", "name": "agent-2", "status": "needs_review", "autostart": true, "reviewed": false } }, "FolderAgentsList": { "type": "object", "required": [ "path", "agents" ], "properties": { "path": { "type": "string" }, "agents": { "type": "array", "items": { "$ref": "#/components/schemas/FolderAgent" } } } }, "FolderRenameBody": { "type": "object", "required": [ "oldPrefix", "newPrefix" ], "properties": { "oldPrefix": { "type": "string" }, "newPrefix": { "type": "string" } }, "additionalProperties": false }, "FolderRenameResponse": { "type": "object", "required": [ "agentId", "success", "count" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "success": { "type": "boolean", "const": true }, "count": { "type": "integer", "description": "Files moved" } } }, "GenerateKeysResponse": { "type": "object", "required": [ "agentId", "success", "did" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "success": { "type": "boolean", "const": true }, "did": { "type": "string" } } }, "GrokAuthStartResponse": { "type": "object", "required": [ "started", "userCode", "verificationUri", "verificationUriComplete", "expiresIn" ], "properties": { "started": { "type": "boolean", "const": true }, "userCode": { "type": "string" }, "verificationUri": { "type": "string" }, "verificationUriComplete": { "type": "string" }, "expiresIn": { "type": "integer", "description": "Seconds" } }, "example": { "started": true, "userCode": "ABCD-EFGH", "verificationUri": "https://accounts.x.ai/device", "verificationUriComplete": "https://accounts.x.ai/device?code=ABCD-EFGH", "expiresIn": 900 } }, "HealthResponse": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } }, "example": { "ok": true } }, "IdentityChangePasswordBody": { "type": "object", "required": [ "newPassword" ], "properties": { "newPassword": { "type": "string", "description": "Alias: new_password" } } }, "IdentityCodeAccessBody": { "type": "object", "required": [ "codeAccess" ], "properties": { "codeAccess": { "type": "boolean", "description": "Alias: code_access" } }, "example": { "codeAccess": true } }, "IdentityCreateResponse": { "type": "object", "description": "The ONLY response that carries the seed phrase (sent with Cache-Control: no-store). Show it once; the daemon never returns it again.", "required": [ "mnemonic", "words", "identity" ], "properties": { "mnemonic": { "type": "string" }, "words": { "type": "array", "items": { "type": "string" }, "minItems": 12, "maxItems": 12 }, "identity": { "$ref": "#/components/schemas/IdentityStatus" } } }, "IdentityDeleteResponse": { "type": "object", "required": [ "agentId", "purpose", "success" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "purpose": { "type": "string" }, "success": { "type": "boolean" } } }, "IdentityErrorResponse": { "type": "object", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "invalid_mnemonic", "owner_mismatch", "identity_exists", "passphrase_required", "weak_passphrase", "wrong_passphrase", "not_file_storage", "nothing_to_unlock", "not_ready", "loopback_only" ] } } }, "IdentityListResponse": { "type": "object", "required": [ "agentId", "identities" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "identities": { "type": "array", "items": { "type": "object", "required": [ "purpose", "encrypted", "code_access" ], "properties": { "purpose": { "type": "string" }, "encrypted": { "type": "boolean" }, "code_access": { "type": "boolean" } } } } } }, "IdentityPassphraseBody": { "type": "object", "properties": { "passphrase": { "type": "string", "description": "Required with file storage (no OS keychain)", "minLength": 8 } } }, "IdentityPasswordBody": { "type": "object", "required": [ "password" ], "properties": { "password": { "type": "string" } } }, "IdentityPasswordStatus": { "type": "object", "required": [ "agentId", "needsPassword", "unlocked" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "needsPassword": { "type": "boolean" }, "unlocked": { "type": "boolean" } } }, "IdentityPrefixDeleteResponse": { "type": "object", "required": [ "agentId", "prefix", "deleted" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "prefix": { "type": "string" }, "deleted": { "type": "integer" } } }, "IdentityPurposesResponse": { "type": "object", "required": [ "agentId", "purposes" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "purposes": { "type": "array", "items": { "type": "string" } } } }, "IdentityRestoreBody": { "type": "object", "required": [ "mnemonic" ], "properties": { "mnemonic": { "type": "string", "description": "12-word BIP-39 phrase (case/whitespace-insensitive)" }, "passphrase": { "type": "string" } } }, "IdentityStatus": { "type": "object", "required": [ "status", "ownerDid", "runtimeDid", "storage", "backupConfirmed", "passphraseRequired", "message" ], "properties": { "status": { "type": "string", "enum": [ "none", "locked", "restore-needed", "ready" ] }, "ownerDid": { "type": [ "string", "null" ] }, "runtimeDid": { "type": [ "string", "null" ], "description": "This daemon's own runtime DID (never Studio's)" }, "storage": { "type": "string", "enum": [ "keychain", "file" ] }, "backupConfirmed": { "type": "boolean" }, "passphraseRequired": { "type": "boolean", "description": "File storage not unlocked: create/restore/unlock take a passphrase" }, "message": { "type": "string", "description": "What to do next" } }, "example": { "status": "ready", "ownerDid": "did:key:z6MkOwner…", "runtimeDid": "did:key:z6MkRuntime…", "storage": "keychain", "backupConfirmed": true, "passphraseRequired": false, "message": "Owner identity is ready." } }, "IdentityStatusEnvelope": { "type": "object", "required": [ "identity" ], "properties": { "identity": { "$ref": "#/components/schemas/IdentityStatus" } } }, "IdentityValueBody": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "string" }, "replace": { "type": "boolean", "description": "Owner override while the agent's credentials envelope is locked on this daemon: a locked sealed value is discarded unread and the new value is stored plain, sealed again on unlock; logged to adf_logs (`credential_replaced`). Without it such a write answers 409 `credentials_locked`." } }, "example": { "value": "sk-…" } }, "IdentityWriteResponse": { "type": "object", "required": [ "agentId", "purpose", "success" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "purpose": { "type": "string" }, "success": { "type": "boolean", "const": true }, "replaced": { "type": "boolean", "description": "A locked sealed value was discarded (replace: true)" } } }, "InboxClearResponse": { "type": "object", "required": [ "agentId", "success", "deleted" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "success": { "type": "boolean", "const": true }, "deleted": { "type": "integer" } } }, "InboxMessage": { "type": "object", "required": [ "id", "from", "content", "received_at", "status" ], "properties": { "id": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "reply_to": { "type": "string" }, "network": { "type": "string" }, "thread_id": { "type": "string" }, "parent_id": { "type": "string" }, "subject": { "type": "string" }, "content": { "type": "string" }, "content_type": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "meta": { "type": "object", "additionalProperties": true }, "sender_alias": { "type": "string" }, "recipient_alias": { "type": "string" }, "message_id": { "type": "string" }, "owner": { "type": "string" }, "card": { "type": "string" }, "return_path": { "type": "string" }, "source": { "type": "string" }, "source_context": { "type": "object", "additionalProperties": true }, "sent_at": { "type": "integer" }, "received_at": { "type": "integer" }, "status": { "type": "string", "enum": [ "unread", "read", "archived" ] }, "original_message": { "type": "string" } } }, "InboxResponse": { "type": "object", "required": [ "agentId", "messages" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/InboxMessage" } } } }, "InstalledPackage": { "type": "object", "required": [ "package", "version", "command", "installPath", "installedAt" ], "properties": { "package": { "type": "string" }, "version": { "type": "string" }, "command": { "type": "string", "description": "Resolved entry point" }, "installPath": { "type": "string" }, "installedAt": { "type": "integer" }, "runtime": { "type": "string", "enum": [ "npm", "uvx", "pip" ] } } }, "InterruptResponse": { "type": "object", "required": [ "success", "interrupted", "loop" ], "properties": { "success": { "type": "boolean", "const": true }, "interrupted": { "type": "boolean", "description": "False when nothing was running" }, "loop": { "type": "string" } }, "example": { "success": true, "interrupted": true, "loop": "main" } }, "LanAddressesResponse": { "type": "object", "required": [ "addresses" ], "properties": { "addresses": { "$ref": "#/components/schemas/LanAddressInfo" } } }, "LanAddressInfo": { "type": "object", "required": [ "hostname", "addresses" ], "properties": { "hostname": { "type": "string" }, "addresses": { "type": "array", "items": { "type": "object", "required": [ "iface", "address", "family", "mac" ], "properties": { "iface": { "type": "string" }, "address": { "type": "string" }, "family": { "type": "string", "enum": [ "IPv4", "IPv6" ] }, "mac": { "type": "string" } } } } } }, "LoadAgentBody": { "type": "object", "required": [ "filePath" ], "properties": { "filePath": { "type": "string", "description": "Absolute path of the .adf file" }, "requireReview": { "type": "boolean", "description": "Enforce the review gate for this load (direct loads bypass it by default)" } }, "example": { "filePath": "/home/me/agents/agent-1.adf" } }, "LogEntry": { "type": "object", "required": [ "id", "level", "origin", "event", "target", "message", "data", "created_at" ], "properties": { "id": { "type": "integer" }, "level": { "type": "string", "enum": [ "debug", "info", "warn", "error" ] }, "origin": { "type": [ "string", "null" ] }, "event": { "type": [ "string", "null" ] }, "target": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "data": { "type": [ "string", "null" ], "description": "JSON text" }, "created_at": { "type": "integer", "description": "Epoch ms" } } }, "LoopBody": { "type": "object", "properties": { "loop": { "type": "string", "description": "Cognition loop; absent = main. The `loop` query parameter wins." } }, "additionalProperties": false }, "LoopConfig": { "type": "object", "required": [ "name", "goal", "enabled" ], "properties": { "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,31}$" }, "goal": { "type": "string", "description": "Becomes the loop's instructions" }, "enabled": { "type": "boolean" }, "autostart": { "type": "boolean" }, "autonomous": { "type": "boolean" }, "model": { "$ref": "#/components/schemas/ModelConfig" }, "compact_threshold": { "type": [ "integer", "null" ] }, "tools": { "type": "array", "items": { "type": "string" }, "description": "Absolute allow-list, intersected with the host's enabled tools" } } }, "LoopCreateBody": { "type": "object", "required": [ "name", "goal" ], "properties": { "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,31}$" }, "goal": { "type": "string" }, "enabled": { "type": "boolean", "default": true }, "autostart": { "type": "boolean", "default": true }, "autonomous": { "type": "boolean" }, "model": { "$ref": "#/components/schemas/ModelConfig" }, "compact_threshold": { "type": [ "integer", "null" ] }, "tools": { "type": "array", "items": { "type": "string" }, "description": "Default: loop_send, loop_list, sys_set_state (filtered to what the host can grant)" } }, "example": { "name": "reflector", "goal": "Review the day's work and write lessons to mind.md." } }, "LoopCreateResponse": { "type": "object", "required": [ "agentId", "loop", "effectiveTools", "excludedTools", "kickoff" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "loop": { "$ref": "#/components/schemas/LoopInfo" }, "effectiveTools": { "type": "array", "items": { "type": "string" } }, "excludedTools": { "type": "array", "items": { "type": "string", "description": "Requested tools the host has disabled: carried by name, not granted" } }, "kickoff": { "oneOf": [ { "$ref": "#/components/schemas/LoopSendResult" }, { "type": "null" } ] } } }, "LoopDeleteResponse": { "type": "object", "required": [ "agentId", "name", "archivedEntries", "interruptedTurn" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "name": { "type": "string" }, "archivedEntries": { "type": "integer", "description": "adf_loop rows written to adf_audit" }, "interruptedTurn": { "type": "boolean" } } }, "LoopEntry": { "type": "object", "required": [ "seq", "role", "content_json", "created_at" ], "properties": { "seq": { "type": "integer" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content_json": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Provider-neutral content blocks (text, tool_use, tool_result, …)" }, "model": { "type": "string" }, "tokens": { "$ref": "#/components/schemas/LoopTokenUsage" }, "created_at": { "type": "integer", "description": "Epoch ms" } } }, "LoopInfo": { "type": "object", "required": [ "name", "goal", "status", "enabled", "isMain", "config", "entryCount", "effectiveTools" ], "properties": { "name": { "type": "string" }, "goal": { "type": "string" }, "status": { "type": "string", "enum": [ "idle", "running" ] }, "enabled": { "type": "boolean" }, "isMain": { "type": "boolean", "description": "The implicit host loop" }, "config": { "oneOf": [ { "$ref": "#/components/schemas/LoopConfig" }, { "type": "null" } ] }, "entryCount": { "type": "integer", "description": "Rows in this loop's adf_loop stream" }, "effectiveTools": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "example": { "name": "main", "goal": "You are agent-1…", "status": "idle", "enabled": true, "isMain": true, "config": null, "entryCount": 42, "effectiveTools": null } }, "LoopListResponse": { "type": "object", "required": [ "agentId", "loops" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "loops": { "type": "array", "items": { "$ref": "#/components/schemas/LoopInfo" } } } }, "LoopPage": { "type": "object", "required": [ "agentId", "loop", "total", "limit", "offset", "entries" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "loop": { "type": "string" }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/LoopEntry" } } } }, "LoopPatchBody": { "type": "object", "description": "At least one field. `null` clears model / compact_threshold. Loops cannot be renamed.", "properties": { "goal": { "type": "string" }, "enabled": { "type": "boolean", "description": "false stops the loop immediately" }, "autostart": { "type": "boolean" }, "autonomous": { "type": "boolean" }, "model": { "oneOf": [ { "$ref": "#/components/schemas/ModelConfig" }, { "type": "null" } ] }, "compact_threshold": { "type": [ "integer", "null" ] }, "tools": { "type": "array", "items": { "type": "string" } } }, "example": { "enabled": false } }, "LoopResponse": { "type": "object", "required": [ "agentId", "loop" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "loop": { "$ref": "#/components/schemas/LoopInfo" } } }, "LoopSendResult": { "type": "object", "required": [ "delivered", "woke" ], "properties": { "delivered": { "type": "boolean" }, "woke": { "type": "boolean" }, "reason": { "type": "string" } } }, "LoopTokenUsage": { "type": "object", "properties": { "input": { "type": "integer" }, "output": { "type": "integer" }, "cache_read": { "type": "integer" }, "cache_write": { "type": "integer" }, "reasoning": { "type": "integer" }, "cost_usd": { "type": "number" } } }, "LoopUpdateResponse": { "type": "object", "required": [ "agentId", "loop", "updated", "excludedTools" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "loop": { "$ref": "#/components/schemas/LoopInfo" }, "updated": { "type": "array", "items": { "type": "string" } }, "excludedTools": { "type": "array", "items": { "type": "string" } } } }, "McpAttachBody": { "type": "object", "description": "`server` (alias `serverConfig`) with name and transport.", "required": [ "server" ], "properties": { "server": { "$ref": "#/components/schemas/McpServerConfig" }, "serverConfig": { "$ref": "#/components/schemas/McpServerConfig" } } }, "McpAttachResponse": { "type": "object", "required": [ "agentId", "serverName", "success", "alreadyAttached", "config" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "serverName": { "type": "string" }, "success": { "type": "boolean", "const": true }, "alreadyAttached": { "type": "boolean" }, "config": { "$ref": "#/components/schemas/AgentConfig" } } }, "McpCredentialBody": { "type": "object", "required": [ "npmPackage", "envKey", "value" ], "properties": { "npmPackage": { "type": "string", "description": "Package or server name the credential belongs to" }, "envKey": { "type": "string" }, "value": { "type": "string" }, "replace": { "type": "boolean", "description": "Owner override while the agent's credentials envelope is locked on this daemon: a locked sealed value is discarded unread and the new value is stored plain, sealed again on unlock; logged to adf_logs (`credential_replaced`). Without it such a write answers 409 `credentials_locked`." } }, "example": { "npmPackage": "@acme/mcp-server", "envKey": "ACME_TOKEN", "value": "…" } }, "McpCredentialsResponse": { "type": "object", "required": [ "agentId", "npmPackage", "credentials" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "npmPackage": { "type": "string" }, "credentials": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/CredentialMeta" }, "description": "By env key" } } }, "McpCredentialWriteResponse": { "type": "object", "required": [ "agentId", "npmPackage", "envKey", "success" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "npmPackage": { "type": "string" }, "envKey": { "type": "string" }, "success": { "type": "boolean", "const": true }, "replaced": { "type": "boolean" } } }, "McpDetachResponse": { "type": "object", "required": [ "agentId", "serverName", "success", "deletedCredentials", "config" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "serverName": { "type": "string" }, "success": { "type": "boolean", "const": true }, "deletedCredentials": { "type": "integer" }, "config": { "$ref": "#/components/schemas/AgentConfig" } } }, "McpRegistrationsDiagnostics": { "type": "object", "required": [ "servers" ], "properties": { "servers": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "type", "managed", "credentialStorage", "env", "headers", "headerEnv", "bearerTokenEnvVar", "toolCallTimeout" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "npmPackage": { "type": "string" }, "pypiPackage": { "type": "string" }, "command": { "type": "string" }, "args": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "managed": { "type": "boolean" }, "version": { "type": "string" }, "credentialStorage": { "type": "string" }, "env": { "type": "array", "items": { "type": "object", "required": [ "key", "hasValue" ], "properties": { "key": { "type": "string" }, "hasValue": { "type": "boolean" } } } }, "headers": { "type": "array", "items": { "type": "object", "required": [ "key", "hasValue" ], "properties": { "key": { "type": "string" }, "hasValue": { "type": "boolean" } } } }, "headerEnv": { "type": "array", "items": { "type": "object", "required": [ "header", "env" ], "properties": { "header": { "type": "string" }, "env": { "type": "string" } } } }, "bearerTokenEnvVar": { "type": [ "string", "null" ] }, "toolCallTimeout": { "type": [ "integer", "null" ] } } } } } }, "McpRestartResponse": { "type": "object", "required": [ "agentId", "serverName", "success", "toolsDiscovered" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "serverName": { "type": "string" }, "success": { "type": "boolean", "description": "Connected with at least one tool" }, "toolsDiscovered": { "type": "integer" }, "location": { "type": "string" }, "error": { "type": "string" }, "hostDenied": { "type": "string" }, "stderrTail": { "type": "array", "items": { "type": "string" } } } }, "McpServerConfig": { "type": "object", "required": [ "name", "transport" ], "properties": { "name": { "type": "string" }, "transport": { "type": "string", "enum": [ "stdio", "http" ] }, "command": { "type": "string" }, "args": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "oauth": { "type": "boolean" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "header_env": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "bearer_token_env_var": { "type": "string" }, "env": { "type": "object", "additionalProperties": { "type": "string" } }, "env_keys": { "type": "array", "items": { "type": "string" } }, "env_schema": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "npm_package": { "type": "string" }, "pypi_package": { "type": "string" }, "source": { "type": "string" }, "available_tools": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "tool_call_timeout_ms": { "type": "integer" }, "restricted": { "type": "boolean" }, "run_location": { "type": "string", "enum": [ "host", "shared" ] }, "credential_files": { "type": "array", "items": { "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string" }, "required": { "type": "boolean" }, "write_back": { "type": "boolean" } } } } }, "additionalProperties": true, "example": { "name": "filesystem", "transport": "stdio", "npm_package": "@modelcontextprotocol/server-filesystem" } }, "McpServerState": { "type": "object", "required": [ "name", "status", "restartCount", "toolCount", "logs" ], "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": [ "stopped", "connecting", "connected", "error", "installing" ] }, "error": { "type": "string" }, "connectedAt": { "type": "integer" }, "restartCount": { "type": "integer" }, "toolCount": { "type": "integer" }, "logs": { "type": "array", "items": { "type": "object", "required": [ "timestamp", "stream", "message" ], "properties": { "timestamp": { "type": "integer" }, "stream": { "type": "string", "enum": [ "stdout", "stderr", "system" ] }, "message": { "type": "string" } } } } } }, "MeshAgentStatus": { "type": "object", "required": [ "filePath", "handle", "state" ], "properties": { "filePath": { "type": "string" }, "handle": { "type": "string" }, "did": { "type": "string" }, "agentId": { "type": "string" }, "icon": { "type": "string" }, "state": { "$ref": "#/components/schemas/DisplayState" }, "status": { "type": "string" }, "model": { "type": "string" } }, "additionalProperties": true }, "MeshServerActionResponse": { "allOf": [ { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } }, { "$ref": "#/components/schemas/MeshServerStatus" } ] }, "MeshServerStatus": { "type": "object", "required": [ "running", "port", "host" ], "properties": { "running": { "type": "boolean" }, "port": { "type": "integer" }, "host": { "type": "string" } }, "example": { "running": true, "port": 7295, "host": "127.0.0.1" } }, "MeshStatus": { "type": "object", "required": [ "meshEnabled", "meshServerRunning", "meshServer", "agents", "debug" ], "properties": { "meshEnabled": { "type": "boolean" }, "meshServerRunning": { "type": "boolean" }, "meshServer": { "$ref": "#/components/schemas/MeshServerStatus" }, "agents": { "type": "array", "items": { "$ref": "#/components/schemas/MeshAgentStatus" } }, "debug": { "type": "object", "additionalProperties": true, "description": "Mesh manager internals (unstable)" } } }, "MeshToggleResponse": { "type": "object", "required": [ "success", "meshEnabled", "agents" ], "properties": { "success": { "type": "boolean" }, "meshEnabled": { "type": "boolean" }, "agents": { "type": "array", "items": { "$ref": "#/components/schemas/MeshAgentStatus" } } } }, "MetaEntry": { "type": "object", "required": [ "key", "value", "protection" ], "properties": { "key": { "type": "string" }, "value": { "type": "string" }, "protection": { "$ref": "#/components/schemas/MetaProtection" } } }, "MetaProtection": { "type": "string", "enum": [ "none", "readonly", "increment" ] }, "MetaProtectionBody": { "type": "object", "required": [ "protection" ], "properties": { "protection": { "$ref": "#/components/schemas/MetaProtection" } }, "additionalProperties": false }, "MetaResponse": { "type": "object", "required": [ "agentId", "entries" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/MetaEntry" } } } }, "MetaSetBody": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "string" }, "protection": { "$ref": "#/components/schemas/MetaProtection" } }, "additionalProperties": false, "example": { "value": "42" } }, "ModelConfig": { "type": "object", "required": [ "provider", "model_id" ], "properties": { "provider": { "type": "string", "description": "Provider id (app provider or one of the agent's own providers)" }, "model_id": { "type": "string" }, "temperature": { "type": [ "number", "null" ] }, "max_tokens": { "type": [ "integer", "null" ] }, "top_p": { "type": [ "number", "null" ] }, "reasoning": { "type": "object", "additionalProperties": true, "description": "Provider-agnostic reasoning (\"thinking\") config" }, "multimodal": { "type": "object", "properties": { "image": { "type": "boolean" }, "audio": { "type": "boolean" }, "video": { "type": "boolean" } } }, "params": { "type": "array", "items": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string" }, "value": { "type": "string" } } } }, "provider_params": { "type": "object", "additionalProperties": true } }, "additionalProperties": true, "example": { "provider": "anthropic", "model_id": "claude-sonnet-4-5" } }, "ModelsResponse": { "type": "object", "required": [ "provider", "models" ], "properties": { "provider": { "type": "string" }, "models": { "type": "array", "items": { "type": "string" } }, "error": { "type": "string", "description": "Listing failed (the call itself still answers 200)" } }, "example": { "provider": "anthropic", "models": [ "claude-sonnet-4-5", "claude-opus-4-1" ] } }, "NetworkDiagnostics": { "type": "object", "required": [ "host", "mesh", "websocket", "agents" ], "properties": { "host": { "$ref": "#/components/schemas/LanAddressInfo" }, "mesh": { "type": "object", "required": [ "enabledSetting", "lan", "port", "status" ], "properties": { "enabledSetting": { "type": "boolean" }, "lan": { "type": "boolean" }, "port": { "type": "integer" }, "status": { "oneOf": [ { "$ref": "#/components/schemas/MeshStatus" }, { "type": "null" } ] } } }, "websocket": { "type": "object", "required": [ "activeConnections", "inboundConnections", "outboundConnections" ], "properties": { "activeConnections": { "type": "integer" }, "inboundConnections": { "type": "integer" }, "outboundConnections": { "type": "integer" } } }, "agents": { "type": "array", "items": { "type": "object", "required": [ "agentId", "name", "filePath", "receive", "sendMode", "network", "wsConnectionsConfigured", "servingRoutes", "publicServingEnabled" ], "properties": { "agentId": { "type": "string" }, "handle": { "type": "string" }, "name": { "type": "string" }, "filePath": { "type": [ "string", "null" ] }, "receive": { "type": "boolean" }, "sendMode": { "type": [ "string", "null" ] }, "network": { "type": [ "string", "null" ] }, "wsConnectionsConfigured": { "type": "integer" }, "servingRoutes": { "type": "integer" }, "publicServingEnabled": { "type": "boolean" } } } } } }, "OpenApiDocument": { "type": "object", "additionalProperties": true, "description": "An OpenAPI 3.1 document (this one)." }, "OutboxMessage": { "type": "object", "required": [ "id", "from", "to", "content", "created_at", "status" ], "properties": { "id": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "address": { "type": "string" }, "reply_to": { "type": "string" }, "network": { "type": "string" }, "thread_id": { "type": "string" }, "parent_id": { "type": "string" }, "subject": { "type": "string" }, "content": { "type": "string" }, "content_type": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "meta": { "type": "object", "additionalProperties": true }, "sender_alias": { "type": "string" }, "recipient_alias": { "type": "string" }, "message_id": { "type": "string" }, "owner": { "type": "string" }, "card": { "type": "string" }, "return_path": { "type": "string" }, "status_code": { "type": "integer" }, "created_at": { "type": "integer" }, "delivered_at": { "type": "integer" }, "status": { "type": "string", "enum": [ "pending", "sent", "delivered", "failed" ] }, "original_message": { "type": "string" } } }, "OutboxResponse": { "type": "object", "required": [ "agentId", "messages" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/OutboxMessage" } } } }, "PackageInstallBody": { "type": "object", "properties": { "package": { "type": "string", "description": "Package name (alias: name)" }, "name": { "type": "string" }, "version": { "type": "string", "description": "Python and sandbox packages" }, "agentName": { "type": "string", "description": "Sandbox: recorded as installedBy" } }, "example": { "package": "@modelcontextprotocol/server-filesystem" } }, "PackageInstallResponse": { "type": "object", "required": [ "success", "installed" ], "properties": { "success": { "type": "boolean", "const": true }, "installed": { "$ref": "#/components/schemas/InstalledPackage" } } }, "PackagesResponse": { "type": "object", "required": [ "packages" ], "properties": { "packages": { "type": "array", "items": { "$ref": "#/components/schemas/InstalledPackage" } } } }, "ProviderAttachBody": { "type": "object", "required": [ "provider" ], "properties": { "provider": { "$ref": "#/components/schemas/AgentProviderConfig" } } }, "ProviderAttachResponse": { "type": "object", "required": [ "agentId", "providerId", "success", "alreadyAttached", "config" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "providerId": { "type": "string" }, "success": { "type": "boolean", "const": true }, "alreadyAttached": { "type": "boolean" }, "config": { "$ref": "#/components/schemas/AgentConfig" } } }, "ProviderCredentialsResponse": { "type": "object", "required": [ "agentId", "providerId", "credentials" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "providerId": { "type": "string" }, "credentials": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/CredentialMeta" }, "description": "By credential key (e.g. apiKey)" }, "providerConfig": { "type": "object", "properties": { "defaultModel": { "type": "string" }, "params": { "type": "array", "items": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string" }, "value": { "type": "string" } } } }, "requestDelayMs": { "type": "integer" } } } } }, "ProviderCredentialWriteResponse": { "type": "object", "required": [ "agentId", "providerId", "success" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "providerId": { "type": "string" }, "success": { "type": "boolean", "const": true }, "replaced": { "type": "boolean" } } }, "ProviderDetachResponse": { "type": "object", "required": [ "agentId", "providerId", "success", "deletedCredentials", "config" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "providerId": { "type": "string" }, "success": { "type": "boolean", "const": true }, "deletedCredentials": { "type": "integer" }, "config": { "$ref": "#/components/schemas/AgentConfig" } } }, "ProviderDiagnostics": { "type": "object", "required": [ "providers", "agentUsage" ], "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderDiagnosticsEntry" } }, "agentUsage": { "type": "array", "items": { "type": "object", "required": [ "agentId", "name", "providerId", "modelId", "source", "credentialStorage" ], "properties": { "agentId": { "type": "string" }, "handle": { "type": "string" }, "name": { "type": "string" }, "providerId": { "type": "string" }, "modelId": { "type": "string" }, "source": { "type": "string", "enum": [ "agent", "app", "missing" ] }, "credentialStorage": { "type": [ "string", "null" ] } } } } } }, "ProviderDiagnosticsEntry": { "allOf": [ { "$ref": "#/components/schemas/PublicProvider" }, { "type": "object", "required": [ "requestDelayMs", "params" ], "properties": { "requestDelayMs": { "type": "integer" }, "params": { "type": "array", "items": { "type": "object", "required": [ "key", "hasValue" ], "properties": { "key": { "type": "string" }, "hasValue": { "type": "boolean" } } } } } } ] }, "PublicProvider": { "type": "object", "description": "An app-level provider as clients see it: never the key.", "required": [ "id", "type", "name", "baseUrl", "credentialStorage", "hasApiKey" ], "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "baseUrl": { "type": "string" }, "defaultModel": { "type": "string" }, "preset": { "type": "string" }, "credentialStorage": { "type": "string", "description": "`app` or `agent`" }, "apiKeyStorage": { "type": "string" }, "hasApiKey": { "type": "boolean" } }, "example": { "id": "custom:ab12cd", "type": "anthropic", "name": "Anthropic", "baseUrl": "", "defaultModel": "", "credentialStorage": "app", "apiKeyStorage": "secret-store", "hasApiKey": true } }, "RecentMeshToolsResponse": { "type": "object", "required": [ "tools" ], "properties": { "tools": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "required": [ "name", "timestamp" ], "properties": { "name": { "type": "string" }, "args": { "type": "string" }, "isError": { "type": "boolean" }, "timestamp": { "type": "integer" } } } }, "description": "By agent handle" } } }, "RemoveProviderResponse": { "type": "object", "required": [ "removed", "providers" ], "properties": { "removed": { "type": "string" }, "providers": { "type": "array", "items": { "$ref": "#/components/schemas/PublicProvider" } } } }, "ReviewAcceptBody": { "type": "object", "required": [ "filePath" ], "properties": { "filePath": { "type": "string" } }, "example": { "filePath": "/home/me/agents/agent-2.adf" } }, "ReviewInfo": { "type": "object", "required": [ "agentId", "filePath", "reviewed", "summary" ], "properties": { "agentId": { "type": "string" }, "filePath": { "type": "string" }, "reviewed": { "type": "boolean" }, "summary": { "$ref": "#/components/schemas/ReviewSummary" } } }, "ReviewRequiredResponse": { "type": "object", "description": "The .adf has not been reviewed on this machine; review it (GET /agents/review) and accept (POST /agents/review/accept) first.", "required": [ "error", "code", "agentId", "filePath" ], "properties": { "error": { "type": "string" }, "code": { "type": "string", "const": "AGENT_REVIEW_REQUIRED" }, "agentId": { "type": "string" }, "filePath": { "type": "string" } } }, "ReviewSummary": { "type": "object", "description": "What the agent can do, as the review dialog shows it (Studio's AgentConfigSummary).", "required": [ "name", "description", "identity", "computeTier", "autostart", "tools", "mcpServers", "triggers", "codeExecution", "messaging", "network", "security" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "identity": { "type": "object", "additionalProperties": true, "description": "agentDid, fileOwnerDid, ownerIsYou, scenario (mine | recognized | foreign | unclaimed), needsClaim, …" }, "computeTier": { "type": "string", "enum": [ "shared", "isolated", "host" ] }, "autostart": { "type": "boolean" }, "tools": { "type": "array", "items": { "type": "object", "required": [ "name", "enabled", "notable" ], "properties": { "name": { "type": "string" }, "enabled": { "type": "boolean" }, "notable": { "type": "boolean" } } } }, "mcpServers": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "triggers": { "type": "array", "items": { "type": "object", "required": [ "type", "enabled", "targetCount" ], "properties": { "type": { "type": "string" }, "enabled": { "type": "boolean" }, "targetCount": { "type": "integer" } } } }, "codeExecution": { "type": "boolean" }, "messaging": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string" } } }, "network": { "type": "object", "additionalProperties": true }, "security": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "RuntimeOverview": { "type": "object", "required": [ "daemon", "settings", "providers", "auth", "mcp", "adapters", "network", "compute", "agents" ], "properties": { "daemon": { "type": "object", "required": [ "uptime", "pid", "version", "node", "platform" ], "properties": { "uptime": { "type": "number", "description": "Seconds" }, "pid": { "type": "integer" }, "version": { "type": [ "string", "null" ] }, "node": { "type": "string" }, "platform": { "type": "string" } } }, "settings": { "$ref": "#/components/schemas/RuntimeSettingsDiagnostics" }, "providers": { "$ref": "#/components/schemas/ProviderDiagnostics" }, "auth": { "$ref": "#/components/schemas/AuthDiagnostics" }, "mcp": { "$ref": "#/components/schemas/McpRegistrationsDiagnostics" }, "adapters": { "$ref": "#/components/schemas/AdapterRegistrationsDiagnostics" }, "network": { "$ref": "#/components/schemas/NetworkDiagnostics" }, "compute": { "oneOf": [ { "$ref": "#/components/schemas/ComputeStatus" }, { "type": "null" } ] }, "agents": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "filePath" ], "properties": { "id": { "type": "string" }, "handle": { "type": "string" }, "name": { "type": "string" }, "filePath": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/AgentStatus" } } } } } }, "RuntimeSettingsDiagnostics": { "type": "object", "required": [ "configured", "filePath", "trackedDirectories", "maxDirectoryScanDepth", "autoCompactThreshold", "promptOverrides", "packageCounts" ], "properties": { "configured": { "type": "boolean" }, "filePath": { "type": [ "string", "null" ] }, "trackedDirectories": { "type": "array", "items": { "type": "string" } }, "maxDirectoryScanDepth": { "type": [ "integer", "null" ] }, "autoCompactThreshold": { "type": [ "integer", "null" ] }, "promptOverrides": { "type": "object", "required": [ "globalSystemPrompt", "compactionPrompt", "toolPrompts" ], "properties": { "globalSystemPrompt": { "type": "boolean" }, "compactionPrompt": { "type": "boolean" }, "toolPrompts": { "type": "integer" } } }, "packageCounts": { "type": "object", "required": [ "sandboxPackages", "mcpServers", "adapters", "providers" ], "properties": { "sandboxPackages": { "type": "integer" }, "mcpServers": { "type": "integer" }, "adapters": { "type": "integer" }, "providers": { "type": "integer" } } } } }, "RuntimeUsageResponse": { "type": "object", "required": [ "source", "note", "totals", "byProvider", "byModel", "usage" ], "properties": { "source": { "type": "string", "const": "token-usage-service" }, "note": { "type": "string" }, "totals": { "type": "object", "required": [ "input", "output", "total" ], "properties": { "input": { "type": "integer" }, "output": { "type": "integer" }, "total": { "type": "integer" } } }, "byProvider": { "type": "array", "items": { "type": "object", "required": [ "provider", "input", "output", "total" ], "properties": { "provider": { "type": "string" }, "input": { "type": "integer" }, "output": { "type": "integer" }, "total": { "type": "integer" } } } }, "byModel": { "type": "array", "items": { "type": "object", "required": [ "provider", "model", "days", "input", "output", "total" ], "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "days": { "type": "integer", "description": "Days with usage" }, "input": { "type": "integer" }, "output": { "type": "integer" }, "total": { "type": "integer" } } } }, "usage": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "object", "required": [ "input", "output" ], "properties": { "input": { "type": "integer" }, "output": { "type": "integer" } } } } }, "description": "date → provider → model → { input, output }" } } }, "SandboxCheckBody": { "type": "object", "required": [ "packages" ], "properties": { "packages": { "type": "array", "items": { "type": "object", "required": [ "name", "version" ], "properties": { "name": { "type": "string" }, "version": { "type": "string" } }, "additionalProperties": true } } }, "example": { "packages": [ { "name": "lodash", "version": "4.17.21" } ] } }, "SandboxCheckResponse": { "type": "object", "required": [ "success", "missing" ], "properties": { "success": { "type": "boolean", "const": true }, "missing": { "type": "array", "items": { "type": "object", "required": [ "name", "version" ], "properties": { "name": { "type": "string" }, "version": { "type": "string" } }, "additionalProperties": true } } } }, "SandboxInstallResponse": { "type": "object", "required": [ "success", "installed" ], "properties": { "success": { "type": "boolean", "const": true }, "installed": { "type": "object", "required": [ "name", "version", "size_mb", "already_installed" ], "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "size_mb": { "type": "number" }, "already_installed": { "type": "boolean" } } } } }, "SandboxPackage": { "type": "object", "required": [ "name", "version", "installedAt", "size_mb" ], "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "installedAt": { "type": "integer" }, "size_mb": { "type": "number" }, "installedBy": { "type": "string" } } }, "SandboxPackagesResponse": { "type": "object", "required": [ "basePath", "modules", "packages" ], "properties": { "basePath": { "type": "string" }, "modules": { "type": "array", "items": { "type": "string" } }, "packages": { "type": "array", "items": { "$ref": "#/components/schemas/SandboxPackage" } } } }, "SettingPutBody": { "type": "object", "required": [ "value" ], "properties": { "value": { "description": "Any JSON value" } }, "example": { "value": true } }, "SettingsPatchBody": { "type": "object", "additionalProperties": true, "description": "Keys to merge. Secret and identity keys are refused (403); providers[].apiKey `__redacted__` keeps the stored key." }, "SettingsResponse": { "type": "object", "required": [ "filePath", "settings" ], "properties": { "filePath": { "type": [ "string", "null" ] }, "settings": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Secret keys removed; providers[].apiKey reads `__redacted__`" } } }, "SettingValueResponse": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string" }, "value": { "description": "Any JSON value; null for secret keys" } }, "example": { "key": "meshEnabled", "value": true } }, "ShutdownAccepted": { "type": "object", "required": [ "accepted", "pid" ], "properties": { "accepted": { "type": "boolean", "const": true }, "pid": { "type": "integer", "description": "Daemon process id" } }, "example": { "accepted": true, "pid": 41230 } }, "StartAgentResponse": { "type": "object", "required": [ "success", "loaded", "startupTriggered" ], "properties": { "success": { "type": "boolean", "const": true }, "loaded": { "type": "boolean", "description": "The agent was loaded from a tracked folder first" }, "startupTriggered": { "type": "boolean" }, "agent": { "$ref": "#/components/schemas/AgentStatus" } }, "example": { "success": true, "loaded": false, "startupTriggered": true, "agent": { "id": "Xk3v9QpLm2", "filePath": "/home/me/agents/agent-1.adf", "name": "agent-1", "autostart": true, "runtimeState": "idle", "targetState": null, "loopCount": 1 } } }, "SubscriptionAuthStatus": { "type": "object", "required": [ "authenticated" ], "properties": { "authenticated": { "type": "boolean" }, "email": { "type": "string" }, "expiresAt": { "type": "integer", "description": "Epoch ms" }, "flowPending": { "type": "boolean" }, "flowError": { "type": "string" } }, "example": { "authenticated": true, "email": "me@example.com", "expiresAt": 1790003600000 } }, "SuccessResponse": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } }, "example": { "success": true } }, "SuspendRespondBody": { "type": "object", "required": [ "resume" ], "properties": { "resume": { "type": "boolean" } }, "example": { "resume": true } }, "SuspendRespondResponse": { "type": "object", "required": [ "agentId", "resume", "resolved" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "resume": { "type": "boolean" }, "resolved": { "type": "boolean" } } }, "TableQueryResponse": { "type": "object", "required": [ "agentId", "columns", "rows" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "columns": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "TablesResponse": { "type": "object", "required": [ "agentId", "tables" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "tables": { "type": "array", "items": { "type": "object", "required": [ "name", "row_count" ], "properties": { "name": { "type": "string" }, "row_count": { "type": "integer" } } } } } }, "Task": { "type": "object", "required": [ "id", "tool", "args", "status", "created_at" ], "properties": { "id": { "type": "string" }, "tool": { "type": "string" }, "args": { "type": "string", "description": "JSON text of the tool arguments" }, "status": { "$ref": "#/components/schemas/TaskStatus" }, "result": { "type": "string" }, "error": { "type": "string" }, "created_at": { "type": "integer" }, "completed_at": { "type": "integer" }, "origin": { "type": "string" }, "requires_authorization": { "type": "boolean" }, "executor_managed": { "type": "boolean" }, "approval_meta": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string", "enum": [ "restricted", "protection" ] }, "protection": { "type": "object", "required": [ "kind", "target", "level" ], "properties": { "kind": { "type": "string" }, "target": { "type": "string" }, "level": { "type": "string" }, "description": { "type": "string" } } } } }, "canAlwaysApprove": { "type": "boolean", "description": "pending_approval rows: whether POST …/always-approve would be accepted" }, "alwaysApproveBlockedReason": { "type": "string", "description": "Why canAlwaysApprove is false" } }, "example": { "id": "task_8hX2", "tool": "sys_update_config", "args": "{\"patch\":{}}", "status": "pending_approval", "created_at": 1790000000000, "requires_authorization": true, "approval_meta": { "reason": "restricted" }, "canAlwaysApprove": true } }, "TaskAlwaysApproveResponse": { "type": "object", "required": [ "agentId", "taskId", "loop", "tool", "resolution", "task" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "taskId": { "type": "string" }, "loop": { "type": "string", "description": "Loop whose executor held the request" }, "tool": { "type": "string", "description": "Tool whose host declaration was un-restricted" }, "resolution": {}, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ] } } }, "TaskResolutionResponse": { "type": "object", "required": [ "agentId", "taskId", "resolution", "task" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "taskId": { "type": "string" }, "resolution": { "description": "What the executor or task store returned" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ] } } }, "TaskResolveBody": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "approve", "deny", "pending_approval" ] }, "reason": { "type": "string", "description": "On deny: stored as the task error and handed back to the agent as the owner's feedback" }, "modifiedArgs": { "type": "object", "additionalProperties": true, "description": "Approve with these arguments instead (alias: modified_args)" }, "modified_args": { "type": "object", "additionalProperties": true } }, "example": { "action": "approve" } }, "TaskResponse": { "type": "object", "required": [ "agentId", "task" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "task": { "$ref": "#/components/schemas/Task" } } }, "TasksResponse": { "type": "object", "required": [ "agentId", "tasks" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } } } }, "TaskStatus": { "type": "string", "enum": [ "pending", "pending_approval", "running", "completed", "failed", "denied", "cancelled" ] }, "TemplateConfigBody": { "type": "object", "required": [ "config" ], "properties": { "config": { "$ref": "#/components/schemas/AgentConfig" } } }, "TemplateConfigResponse": { "type": "object", "required": [ "id", "success" ], "properties": { "id": { "type": "string" }, "success": { "type": "boolean", "const": true } } }, "TemplateContents": { "type": "object", "required": [ "config", "files", "extra" ], "properties": { "config": { "$ref": "#/components/schemas/AgentConfig" }, "files": { "type": "object", "required": [ "readme", "mind", "soul" ], "properties": { "readme": { "type": "string" }, "mind": { "type": "string" }, "soul": { "type": "string" } } }, "extra": { "type": "array", "items": { "type": "object", "required": [ "path", "size", "mime" ], "properties": { "path": { "type": "string" }, "size": { "type": "integer" }, "mime": { "type": "string" } } } } } }, "TemplateCreateBody": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "fromId": { "type": "string", "description": "Duplicate this template (no identity or history carried)" } }, "example": { "name": "Researcher", "fromId": "standard" } }, "TemplateDefaultResponse": { "type": "object", "required": [ "defaultId" ], "properties": { "defaultId": { "type": "string" } } }, "TemplateDeleteResponse": { "type": "object", "required": [ "deleted", "id", "trashFolder", "defaultId" ], "properties": { "deleted": { "type": "boolean", "const": true }, "id": { "type": "string" }, "trashFolder": { "type": "string" }, "defaultId": { "type": "string" } } }, "TemplateDetail": { "type": "object", "required": [ "template", "isDefault", "defaultId", "contents" ], "properties": { "template": { "oneOf": [ { "$ref": "#/components/schemas/TemplateSummary" }, { "type": "null" } ] }, "isDefault": { "type": "boolean" }, "defaultId": { "type": "string" }, "contents": { "$ref": "#/components/schemas/TemplateContents" } } }, "TemplateFileBody": { "type": "object", "required": [ "path", "content" ], "properties": { "path": { "type": "string", "description": "README.md, mind.md, soul.md or an extra file path" }, "content": { "type": "string" } }, "example": { "path": "mind.md", "content": "# Mind\n" } }, "TemplateFileResponse": { "type": "object", "required": [ "id", "path", "success" ], "properties": { "id": { "type": "string" }, "path": { "type": "string" }, "success": { "type": "boolean", "const": true } } }, "TemplateList": { "type": "object", "required": [ "templates", "defaultId", "folder", "defaultDirectory" ], "properties": { "templates": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateSummary" } }, "defaultId": { "type": "string" }, "folder": { "type": "string" }, "defaultDirectory": { "type": "string", "description": "Where POST /agents/create puts agents without `directory`" } } }, "TemplatePatchBody": { "type": "object", "properties": { "name": { "type": "string", "description": "Rename (moves the file; the response carries the new id)" }, "description": { "type": "string", "description": "Empty string clears" }, "warning": { "type": "string", "description": "Empty string clears" } }, "example": { "description": "For research agents" } }, "TemplateRef": { "type": "object", "required": [ "id", "template" ], "properties": { "id": { "type": "string", "description": "The (possibly new) template id" }, "template": { "oneOf": [ { "$ref": "#/components/schemas/TemplateSummary" }, { "type": "null" } ] } } }, "TemplateReview": { "type": "object", "required": [ "id", "needsReview", "reviewed", "summary" ], "properties": { "id": { "type": "string" }, "needsReview": { "type": "boolean" }, "reviewed": { "type": "boolean" }, "summary": { "$ref": "#/components/schemas/ReviewSummary" } } }, "TemplateReviewAcceptBody": { "type": "object", "properties": { "password": { "type": "string", "description": "For a password-protected template file" } } }, "TemplateReviewAcceptResponse": { "type": "object", "required": [ "id", "reviewed", "template" ], "properties": { "id": { "type": "string" }, "reviewed": { "type": "boolean", "const": true }, "template": { "oneOf": [ { "$ref": "#/components/schemas/TemplateSummary" }, { "type": "null" } ] } } }, "TemplateSummary": { "type": "object", "required": [ "id", "name", "filePath", "reviewed", "modifiedAt", "hasHistory" ], "properties": { "id": { "type": "string", "description": "File stem in the templates folder" }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "filePath": { "type": "string" }, "shipped": { "type": "string", "enum": [ "standard", "sandboxed", "full-access" ] }, "templateDescription": { "type": "string" }, "warning": { "type": "string" }, "reviewed": { "type": "boolean", "description": "false = from someone else and not accepted yet" }, "modelProvider": { "type": "string" }, "modelId": { "type": "string" }, "modifiedAt": { "type": "integer" }, "hasHistory": { "type": "boolean" } }, "example": { "id": "standard", "name": "Standard", "filePath": "/home/me/.config/adf/templates/standard.adf", "shipped": "standard", "reviewed": true, "modifiedAt": 1790000000000, "hasHistory": false } }, "TextContentBody": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string" } }, "example": { "content": "# Notes\n" } }, "TextContentResponse": { "type": "object", "required": [ "agentId", "content" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "content": { "type": "string" } } }, "Timer": { "type": "object", "required": [ "id", "schedule", "next_wake_at", "scope", "run_count", "created_at" ], "properties": { "id": { "type": "integer" }, "schedule": { "oneOf": [ { "type": "object", "required": [ "mode", "at" ], "properties": { "mode": { "type": "string", "const": "once" }, "at": { "type": "integer" } } }, { "type": "object", "required": [ "mode", "every_ms" ], "properties": { "mode": { "type": "string", "const": "interval" }, "every_ms": { "type": "integer" }, "start_at": { "type": "integer" }, "end_at": { "type": "integer" }, "max_runs": { "type": "integer" } } }, { "type": "object", "required": [ "mode", "cron" ], "properties": { "mode": { "type": "string", "const": "cron" }, "cron": { "type": "string" }, "end_at": { "type": "integer" }, "max_runs": { "type": "integer" } } } ] }, "next_wake_at": { "type": "integer" }, "payload": { "type": "string" }, "scope": { "type": "array", "items": { "type": "string", "enum": [ "system", "agent" ] } }, "lambda": { "type": "string" }, "warm": { "type": "boolean" }, "run_count": { "type": "integer" }, "created_at": { "type": "integer" }, "last_fired_at": { "type": "integer" }, "locked": { "type": "boolean" }, "loop": { "type": "string" }, "expired": { "type": "boolean" } } }, "TimerCreateResponse": { "type": "object", "required": [ "agentId", "success", "id" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "success": { "type": "boolean", "const": true }, "id": { "type": "integer" } } }, "TimerMutationBody": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "once_at", "once_delay", "interval", "cron" ] }, "at": { "type": "integer", "description": "once_at: epoch ms" }, "delay_ms": { "type": "integer", "description": "once_delay" }, "every_ms": { "type": "integer", "description": "interval" }, "start_at": { "type": "integer" }, "end_at": { "type": "integer" }, "max_runs": { "type": "integer" }, "cron": { "type": "string", "description": "cron" }, "scope": { "type": "array", "items": { "type": "string", "enum": [ "system", "agent" ] } }, "lambda": { "type": "string" }, "warm": { "type": "boolean" }, "payload": { "type": "string" }, "locked": { "type": "boolean" }, "loop": { "type": "string", "description": "Cognition loop the agent-scope wake targets. Create: absent = main. Update: moves the timer (`main` moves it back); absent keeps its loop." } }, "additionalProperties": false, "example": { "mode": "interval", "every_ms": 3600000, "scope": [ "agent" ], "payload": "hourly check-in" } }, "TimersResponse": { "type": "object", "required": [ "agentId", "timers" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "timers": { "type": "array", "items": { "$ref": "#/components/schemas/Timer" } } } }, "TokenCountBatchBody": { "type": "object", "required": [ "texts" ], "properties": { "texts": { "type": "array", "items": { "type": "string" } }, "provider": { "type": "string" }, "model": { "type": "string" }, "agentId": { "type": "string" } } }, "TokenCountBatchResponse": { "type": "object", "required": [ "counts", "provider", "model" ], "properties": { "counts": { "type": "array", "items": { "type": "integer" } }, "provider": { "type": "string" }, "model": { "type": "string" } } }, "TokenCountBody": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string" }, "provider": { "type": "string" }, "model": { "type": "string" }, "agentId": { "type": "string", "description": "Use this agent's provider/model" } }, "example": { "text": "Hello, world", "provider": "anthropic" } }, "TokenCountResponse": { "type": "object", "required": [ "count", "provider", "model" ], "properties": { "count": { "type": "integer" }, "provider": { "type": "string" }, "model": { "type": "string" } }, "example": { "count": 4, "provider": "anthropic", "model": "" } }, "ToolEntry": { "type": "object", "required": [ "name", "enabled", "visible", "restricted", "locked", "source", "description", "schema", "restrictions" ], "properties": { "name": { "type": "string" }, "enabled": { "type": "boolean" }, "visible": { "type": "boolean", "description": "Exposed in the LLM's active tool list (when enabled)" }, "restricted": { "type": "boolean", "description": "Authorized code only; an LLM call needs owner approval" }, "locked": { "type": "boolean", "description": "Owner lock: the agent cannot change this entry" }, "source": { "type": "string", "description": "`builtin` or `mcp:`" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": true, "description": "The tool's JSON input schema" }, "restrictions": { "type": "object", "required": [ "restricted", "locked" ], "properties": { "restricted": { "type": "boolean" }, "locked": { "type": "boolean" } } } } }, "TrackDirBody": { "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string", "description": "Absolute path to an existing directory" } }, "example": { "path": "/home/me/agents" } }, "TrackDirResult": { "type": "object", "required": [ "entry", "directories", "absorbed", "autostart", "needsReview", "agents" ], "properties": { "entry": { "$ref": "#/components/schemas/TrackedDirEntry" }, "directories": { "type": "array", "items": { "type": "string" }, "description": "The tracked list after the change" }, "absorbed": { "type": "array", "items": { "type": "string" }, "description": "Tracked subfolders the new folder replaced" }, "autostart": { "$ref": "#/components/schemas/AutostartReport" }, "needsReview": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Autostart skips with reason `unreviewed`" }, "agents": { "type": "array", "items": { "$ref": "#/components/schemas/FolderAgent" } } } }, "TrackedAgentsList": { "type": "object", "required": [ "maxDepth", "folders" ], "properties": { "maxDepth": { "type": "integer" }, "folders": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/TrackedDirEntry" }, { "type": "object", "required": [ "agents" ], "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/FolderAgent" } } } } ] } } } }, "TrackedDirEntry": { "type": "object", "required": [ "path", "exists", "agentCount", "loadedCount" ], "properties": { "path": { "type": "string", "description": "As stored in settings.trackedDirectories" }, "exists": { "type": "boolean" }, "agentCount": { "type": "integer", "description": ".adf files an autostart scan finds (maxDirectoryScanDepth)" }, "loadedCount": { "type": "integer", "description": "Of those, loaded in this daemon" } } }, "TrackedDirErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "coveredBy": { "type": "string", "description": "409 only: the tracked folder that already covers the path" } } }, "TrackedDirsList": { "type": "object", "required": [ "maxDepth", "directories" ], "properties": { "maxDepth": { "type": "integer" }, "directories": { "type": "array", "items": { "$ref": "#/components/schemas/TrackedDirEntry" } } } }, "TriggerBody": { "description": "A dispatch, `{ dispatch: … }`, a bare event, or a batch dispatch.", "oneOf": [ { "$ref": "#/components/schemas/AdfEventDispatch" }, { "$ref": "#/components/schemas/AdfBatchDispatch" }, { "type": "object", "required": [ "dispatch" ], "properties": { "dispatch": { "oneOf": [ { "$ref": "#/components/schemas/AdfEventDispatch" }, { "$ref": "#/components/schemas/AdfBatchDispatch" } ] } } }, { "$ref": "#/components/schemas/AdfEvent" } ], "example": { "event": { "type": "chat", "data": { "text": "ping" } }, "target": { "scope": "agent" } } }, "TriggerConfig": { "type": "object", "required": [ "enabled", "targets" ], "properties": { "enabled": { "type": "boolean" }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/TriggerTarget" } }, "locked": { "type": "boolean" } } }, "TriggerTarget": { "type": "object", "required": [ "scope" ], "properties": { "scope": { "type": "string", "enum": [ "agent", "system" ] }, "lambda": { "type": "string", "description": "System scope: `path/file.ts:functionName`" }, "command": { "type": "string", "description": "System scope: shell command (alternative to lambda)" }, "warm": { "type": "boolean" }, "filter": { "type": "object", "additionalProperties": true }, "debounce_ms": { "type": "integer" }, "interval_ms": { "type": "integer" }, "batch_ms": { "type": "integer" }, "batch_count": { "type": "integer" }, "locked": { "type": "boolean" }, "loop": { "type": "string", "description": "Cognition loop this target wakes; absent = main" } } }, "UmbilicalEvent": { "type": "object", "required": [ "seq", "event_type", "timestamp", "source", "payload" ], "properties": { "seq": { "type": "integer", "description": "Per-agent sequence number" }, "event_type": { "type": "string", "description": "e.g. agent.state.changed, turn.completed, task.created — see docs/guides/umbilical-events.md" }, "timestamp": { "type": "integer", "description": "Epoch ms" }, "source": { "type": "string" }, "agent_id": { "type": [ "string", "null" ] }, "loop": { "type": "string", "description": "Inner loop that produced it; absent = main" }, "payload": { "type": "object", "additionalProperties": true }, "sig": { "type": "string" }, "turn_id": { "type": "string", "description": "The turn that produced it: the `turnId` POST /agents/{id}/chat or /trigger answered with (kept when an interrupting chat is replayed), else the runtime's own turn id. Absent outside a turn. A chat consumed into a running turn (it arrived mid-tool-use) is listed in that turn's `turn.completed` / `agent.error` payload as `absorbed_turn_ids`." } } }, "UmbilicalEventsResponse": { "type": "object", "description": "A page of the agent's in-memory replay window. Not durable.", "required": [ "agentId", "events", "last_seq", "log_enabled" ], "properties": { "agentId": { "type": "string", "description": "Agent id", "example": "Xk3v9QpLm2" }, "events": { "type": "array", "items": { "type": "object", "required": [ "seq", "event_type", "timestamp", "source", "payload", "truncated" ], "properties": { "seq": { "type": "integer" }, "event_type": { "type": "string" }, "timestamp": { "type": "integer" }, "source": { "type": "string" }, "payload": {}, "truncated": { "type": "boolean", "description": "Payload JSON exceeded 4 KB and was replaced by { _truncated, preview }" } } } }, "last_seq": { "type": [ "integer", "null" ], "description": "Highest seq returned, or the since_seq passed when nothing is new" }, "log_enabled": { "type": "boolean" }, "oldest_seq": { "type": "integer", "description": "Lowest seq still retained; since_seq < oldest_seq - 1 means the client fell off the back and must re-snapshot" } } }, "UntrackDirResult": { "type": "object", "required": [ "removed", "directories", "unloaded" ], "properties": { "removed": { "type": "string" }, "directories": { "type": "array", "items": { "type": "string" } }, "unloaded": { "type": "array", "items": { "type": "object", "required": [ "agentId", "filePath", "name" ], "properties": { "agentId": { "type": "string" }, "filePath": { "type": "string" }, "name": { "type": "string" } } } } } }, "UsageTotals": { "type": "object", "required": [ "input", "output", "cacheRead", "cacheWrite", "total" ], "properties": { "input": { "type": "integer" }, "output": { "type": "integer" }, "cacheRead": { "type": "integer" }, "cacheWrite": { "type": "integer" }, "total": { "type": "integer" } } }, "WsConnectionInfo": { "type": "object", "required": [ "connection_id", "remote_did", "direction", "connected_at", "last_message_at" ], "properties": { "connection_id": { "type": "string" }, "remote_did": { "type": "string" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "connected_at": { "type": "integer" }, "last_message_at": { "type": "integer" } } }, "StreamHello": { "type": "object", "description": "Data of the `stream.hello` control frame, sent on every connect.", "required": [ "epoch", "oldestCursor", "latestCursor" ], "properties": { "epoch": { "type": "string", "description": "Identifies this daemon run; cursors are only comparable within one epoch" }, "oldestCursor": { "type": [ "integer", "null" ], "description": "Oldest buffered cursor (null: nothing buffered)" }, "latestCursor": { "type": "integer", "description": "Newest cursor published (0: none yet)" } }, "example": { "epoch": "6f1c1f9e-2b7a-4f2e-9d59-0c6f5c3f1a10", "oldestCursor": 1, "latestCursor": 42 } }, "StreamGap": { "type": "object", "description": "Data of the `stream.gap` control frame: the resume could not be exact; reload state from the REST API.", "required": [ "reason", "epoch", "requestedCursor", "oldestCursor", "latestCursor" ], "properties": { "reason": { "type": "string", "enum": [ "evicted", "epoch_changed" ], "description": "`evicted`: frames after the cursor were dropped from the buffer. `epoch_changed`: the cursor is from an earlier daemon run." }, "epoch": { "type": "string" }, "requestedCursor": { "type": [ "integer", "null" ] }, "oldestCursor": { "type": [ "integer", "null" ] }, "latestCursor": { "type": "integer" } }, "example": { "reason": "evicted", "epoch": "6f1c1f9e-2b7a-4f2e-9d59-0c6f5c3f1a10", "requestedCursor": 12, "oldestCursor": 40, "latestCursor": 1039 } }, "AmbiguousAgentResponse": { "allOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "type": "object", "required": [ "candidates" ], "properties": { "candidates": { "type": "array", "items": { "type": "object", "required": [ "name", "handle", "filePath" ], "properties": { "name": { "type": "string" }, "handle": { "type": [ "string", "null" ] }, "filePath": { "type": "string" } } } } } } ], "example": { "error": "Agent identifier \"twin\" matches 2 agent files: twin (twin): /work/a/twin.adf, twin (twin): /work/b/twin.adf. Start it by file path instead.", "code": "ambiguous_agent", "candidates": [ { "name": "twin", "handle": "twin", "filePath": "/work/a/twin.adf" }, { "name": "twin", "handle": "twin", "filePath": "/work/b/twin.adf" } ] } } } } }