HTTP API Reference

User-facing runtime API. For most operations, CLI (city ...) 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"
}

Service state API

`GET /api/services/list`

List service states.

`POST /api/services/control`

{ "serviceName": "chat", "action": "restart" }

Supported action: start | stop | restart | status.

`POST /api/services/command`

{
  "serviceName": "task",
  "command": "list",
  "payload": { "status": "enabled" }
}

Plugin API

`GET /api/plugins/list`

List registered plugins.

`POST /api/plugins/availability`

{ "pluginName": "asr" }

`POST /api/plugins/action`

{
  "pluginName": "asr",
  "actionName": "status",
  "payload": {}
}

Console UI API (summary)

`GET /api/ui/plugins`

Returns plugin summary plus availability state (used by Console UI panels).

Example:

{
  "success": true,
  "plugins": [
    {
      "name": "asr",
      "actions": ["status", "on", "off"],
      "pipelines": ["chat.augmentInbound"],
      "guards": [],
      "effects": [],
      "resolves": [],
      "hasSystem": true,
      "hasAvailability": true,
      "availability": {
        "enabled": true,
        "available": true,
        "reasons": []
      },
      "config": {
        "actions": [
          {
            "name": "status",
            "supportsCommand": true,
            "supportsApi": true,
            "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:

sessionId should be the exact target session returned by agent. For chat sessions, this is an opaque ID managed by chat service (not a parseable platform key).
Attachments are materialized by agent and injected as <file ...> tags before the user instruction.
If sessionId maps to a chat conversation, execution is enqueued into the same chat service 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).

Direct action routes

Each service/plugin action also has a default route:

/service/<serviceName>/<actionName>
/api/plugins/action

Examples:

POST /service/chat/send
POST /api/plugins/action

Debug baseline

Make sure the agent is running before calling APIs:

city agent start
curl http://localhost:5314/health

HTTP API Reference

Table of Contents