Documentation v0.30.0
Home GitHub

REST API

The daemon binds to 127.0.0.1 only — LAN clients cannot reach it. CORS middleware with an origin allowlist gates cross-origin access (required for the web.agenvoy.com dashboard).

Endpoints marked local additionally require the request to originate from 127.0.0.1/::1 (the localhostOnly() guard). They manage credentials, config files, or process lifecycle and are meant for a same-machine dashboard, not remote clients.

Agent execution

Method Path Description
POST /v1/send Run an agent request
POST /v1/chat/completions Stateless OpenAI-compatible chat completion
GET /v1/log SSE stream of events across all sessions
GET /v1/tools List current tools
POST /v1/tool/:tool_name Run a named tool directly

POST /v1/send semantics

persist sid Result
false (default) empty Creates temp-<uuid>, reaped after 30 min idle
true empty Creates http-<uuid>, retained permanently
any provided Uses the supplied sid (persist is ignored) 
curl --fail-with-body -sS \
  -H 'Content-Type: application/json' \
  -d '{"content":"List the available tools","persist":false,"allow_all":false}' \
  http://127.0.0.1:17989/v1/send

/v1/chat/completions is stateless: include prior messages in every request when continuity is needed.

Models

Method Path Description
GET /v1/models List registered models
POST DELETE /v1/models · /v1/models/*name local — add / remove a model
GET POST /v1/model/dispatcher local — get / set the dispatcher model
GET POST /v1/model/summary local — get / set the summary model

Sessions

Method Path Description
GET /v1/sessions List sessions and status
POST PUT DELETE /v1/session local — create / rename / delete a session
POST /v1/session/:id/model Set the model for a session
GET /v1/session/:id/status Session status and usage
GET /v1/session/:id/log SSE stream of events for one session
POST /v1/session/:id/event local — publish an event into a session's stream
GET /v1/session/:id/pending List pending (ask_user / confirm) tasks
GET /v1/session/:id/pending/:task_hash/questions Get a pending task's questions
POST /v1/session/:id/pending/:task_hash/resume Answer a pending task and resume
DELETE /v1/session/:id/pending/:task_hash Discard a pending task without answering
POST /v1/session/:id/cancel/:task_id Cancel one running task; task_id comes from /status. Cancellation is per-task by design — there is no cancel-everything variant
GET POST /v1/session/:id/persona local — get / set a session's persona
POST /v1/session/:id/compact local — compact history in the background (fire-and-forget, 202 Accepted)
GET /v1/session/:id/daemon local — daemon.log lines mentioning this session ID (best-effort grep, not a true per-session log)
GET /v1/session/:id/action local — that session's action.log content
GET /v1/session/:id/usage local — 24 h / 7 d / 28 d per-model token usage (same aggregation as the TUI /usage screen)
GET /v1/session/:id/history local — list archived completed pending-task files
GET /v1/session/:id/history/*file local — read one archived pending-task file

Channels

Method Path Description
GET /v1/channel/status local — Telegram / Discord enabled state, bot username, whether a token is stored
POST /v1/channel/telegram · /v1/channel/discord local — {action:"enable"|"disable", token?}. Enable stores the token and flips the config flag only; the GetMe verification the TUI performs is intentionally skipped, since the daemon's config-file watcher already reconnects the bot and fills in its username

Files & credentials

Method Path Description
GET PUT /v1/file local — read / write a file
GET /v1/file/open local — open a file or URL with the OS default handler
GET DELETE /v1/key local — check / delete a single credential in the keychain
GET POST /v1/keys local — list / set credentials

Providers

Method Path Description
GET /v1/providers local — list providers and their available operations
GET /v1/provider/:provider/check local — whether a credential exists for this provider
POST /v1/provider/:provider/key local — set an API key
GET /v1/provider/:provider/oauth local — SSE device-code OAuth flow
GET /v1/provider/:provider/models local — list models available to this provider

MCP

Method Path Description
GET POST /v1/mcp local — list / add MCP servers
POST /v1/mcp/remove local — remove an MCP server
GET /v1/mcp/status local — connection status per server
GET /v1/mcp/health local — health probe per server
POST /v1/mcp/reconnect local — reconnect all MCP clients and re-register tools

Automation

Method Path Description
GET /v1/schedule/*skill local — read a scheduler skill's contents
GET DELETE /v1/cron local — list / delete cron entries
POST /v1/cron/run local — fire a cron entry now (202 Accepted)
GET DELETE /v1/task local — list / delete one-off tasks
POST /v1/task/run local — fire a task now (202 Accepted)

KuraDB & allowlists

Method Path Description
GET POST /v1/kuradb local — status / enable / disable / start / stop / restart KuraDB. Install and uninstall stay TUI-only (they need a real terminal for sudo and install-script prompts); this API only flips the enabled flag and controls an already-installed kura process
GET POST /v1/allowlist/cmd local — list / append the command allowlist (append-only; a restart is required to take effect)
GET POST /v1/allowlist/skill local — list / toggle the skill allowlist (scope=global|project)

Inspection

Method Path Description
GET /v1/torii/error local — read the tool-error memory store; unfiltered when tool and keyword are both omitted
中文