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 runtime API

`GET /api/services/list`

List service runtime 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" }
}

Extension runtime API

`GET /api/extensions/list`

List extension runtime states.

`POST /api/extensions/control`

{ "extensionName": "voice", "action": "status" }

`POST /api/extensions/command`

{
  "extensionName": "voice",
  "command": "status",
  "payload": {}
}

Console UI API (summary)

`GET /api/ui/extensions`

Returns extension runtime state plus config summary (used by Console UI panels).

Example:

{
  "success": true,
  "extensions": [
    {
      "name": "voice",
      "state": "idle",
      "supportsLifecycle": true,
      "supportsCommand": true,
      "config": {
        "lifecycle": { "start": true, "stop": true, "command": true },
        "actions": [
          {
            "name": "status",
            "supportsCommand": true,
            "supportsApi": true,
            "apiMethod": "GET",
            "apiPath": "/extension/voice/status"
          }
        ]
      }
    }
  ]
}

`POST /api/tui/contexts/:contextId/execute`

Execute one turn in a specific context (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:

contextId should be the exact target context returned by runtime. For chat contexts, this is an opaque ID managed by chat service (not a parseable platform key).
Attachments are materialized by runtime and injected as @attach lines before the user instruction.
If contextId 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/extension action also has a default route:

/service/<serviceName>/<actionName>
/extension/<extensionName>/<actionName>

Examples:

POST /service/chat/send
GET /extension/voice/status

Debug baseline

Make sure runtime is up before calling APIs:

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

HTTP API Reference

Table of Contents