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 user messages 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.
  • sessionId should 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 sessionId maps 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.