HTTP API

North Coder 的所有业务逻辑都在后端，CLI 只是一层很薄的 HTTP 客户端。宿主程序（产品 shell、脚本、CI）如果不方便调用 ncoder，可以直接调用后端的控制面 REST API。

本节记录面向宿主集成的控制面端点，不是后端完整 API 表面。会话事件流走 WebSocket，所有会话状态变更（send / cancel / promote）走 REST（RFC-0071）。

Base URL 与发现

端点都挂在后端的 /api 下。Base URL 就是常驻后端地址，默认本地 http://127.0.0.1:8848。宿主程序可复用 CLI 的发现链路定位地址，详见 CLI — 服务发现。

健康检查：GET /api/health 返回 instance_id 等信息，可用于确认地址有效。

认证

• Loopback 受信任：来自 loopback（127.0.0.1 / ::1）的请求无需 token。本地宿主程序与后端同机时可直接调用。
• 非 loopback 需要 server token：远程调用须携带后端启动时输出的 token（与浏览器访问 URL 上的 token 查询参数同源）。缺失或无效返回 401。

错误信封

业务错误返回结构化 detail.code，便于宿主程序据此分支处理：

{
  "detail": {
    "code": "invalid_runtime_token_name",
    "message": "runtime token name must match [A-Za-z_][A-Za-z0-9_]*, got \"bad-name\""
  }
}

端点