HTTP API Reference
Public runtime HTTP endpoints with request examples
User-facing runtime API. For most operations, CLI (
downcity ...) is recommended first.
Core endpoints
GET /health
{ "status": "ok", "timestamp": "2026-03-08T12:00:00.000Z" }GET /api/status
{ "name": "downcity", "status": "running", "timestamp": "..." }POST /api/execute
Request body:
{
"instructions": "Summarize today's changes",
"chatId": "default"
}Managed power API
GET /api/powers/list
List managed power states.
Power API
GET /api/powers/catalog
List registered powers.
POST /api/powers/availability
{ "power_name": "sound" }POST /api/powers/action
{
"power_name": "sound",
"action_name": "models",
"payload": { "capability": "asr" }
}Console UI API (summary)
GET /api/ui/powers
Returns power summary plus availability state (used by Console UI panels).
Example:
{
"success": true,
"powers": [
{
"name": "sound",
"actions": ["models", "asr", "tts"],
"pipelines": ["chat.augmentInbound"],
"guards": [],
"effects": [],
"resolves": [],
"hasSystem": true,
"hasAvailability": true,
"availability": {
"enabled": true,
"available": true,
"reasons": []
},
"config": {
"actions": [
{
"name": "models",
"supportsCommand": false,
"supportsApi": false,
"apiMethod": "",
"apiPath": ""
}
]
}
}
]
}POST /api/dashboard/sessions/:sessionId/execute
Execute one turn in a specific session (for example a selected chatKey).
Request body example with attachment:
{
"instructions": "Please read the attached markdown and provide an actionable summary.",
"attachments": [
{
"type": "document",
"fileName": "page.md",
"contentType": "text/markdown; charset=utf-8",
"content": "# Captured Web Page\n\n..."
}
]
}Notes:
- Canonical
usermessages represent human submissions. Automated Task/delegation prompts, background results, tool media, and recovery instructions are Agent input Parts, committed at complete Step checkpoints without closing the current writer. Interactions live inside their owning Tool Part. See Messages and Parts for input identities and model projection. sessionIdshould be the exact target session returned by agent. For chat sessions, this is an opaque ID managed by the chat power (not a parseable platform key).- The runtime saves attachments to disk, and canonical files store their paths. Attachments always provide paths and metadata. Header-verified static PNG/JPEG/WebP images may also be included automatically, up to 2 MiB each and within the 4 MiB total request media limit and model input budget. Recent images take priority; current and historical attachments use the same rules. PDFs and other files require explicit
read, and budget-omitted images retain their references. Remote URLs are not implicitly downloaded, and one missing attachment does not block the entire Session. - If
sessionIdmaps to a chat conversation, execution is enqueued into the same chat power queue (same behavior as platform inbound messages), and chat history is appended before execution. - Chat-context calls return immediately with queue metadata (
queued=true,queueItemId,queuePosition).
Action routes
Power actions use:
/api/powers/action
Except for GET /health, Agent HTTP APIs require a Bearer Token issued for that Agent. Tokens do not contain Users, Roles, or Permissions; they only grant access to their owning Agent.
Debug baseline
Make sure the agent is running before calling APIs. Runtime startup belongs to the Agent start workflow; the health endpoint belongs to the running Agent HTTP surface.