REST API 参考

manager 暴露单个 REST API，根在 /api。web/ 里的 SPA 调它；你可以用任何 HTTP client 直接调。没有 GraphQL，没有给应用流量用的 gRPC（gRPC 只用于 manager 内部的 geminio tunnel）。

这一页是路由目录，不是手写的 swagger spec。真理之源：cmd/ongrid/main.go （chi.Router 挂载）和 internal/manager/server/*/http.go（按 BC 的 handler）。 点进 handler 看精确的请求/响应结构字段。

约定

• base path：每条路由前缀 /api。所以 GET /v1/edges 在 https://<manager>/api/v1/edges 访问。
• 版本：所有路由在 /v1/ 下。没有 /v2/。向后不兼容的改动走 feature flag 或新路由。
• 认证：Authorization: Bearer ... 里的 bearer JWT。公开路由（登录、 refresh、注册、IM webhook、Prometheus 的 auth_request 探针）跳过中间件。 下面 "公开" 表里列。
• 角色：admin、user、viewer。写路由需要 admin（或相关 casbin 动作如 edge:* / write）；读路由接受任何已认证角色。viewer 能 chat 但 agent 的工具包被过滤到 ClassSafe。见 ADR-022 三角色 RBAC。
• 错误：JSON {"error":"code","message":"human text"}。code 是稳定枚举 （not_found、invalid_argument、unauthorized、forbidden、conflict）。
• content type：除非明说，每个请求和响应都是 application/json （流式 chat 是 SSE，日志/链路摄入是 OTLP-protobuf 或 Loki-JSON）。

公开路由（无认证）

方法	路径	用途
GET	/healthz	liveness 探针
GET	/readyz	readiness 探针
GET	/internal/auth/dataplane-verify	日志/链路摄入的 nginx auth_request 探针
POST	/api/v1/auth/login	email+密码 换 JWT
POST	/api/v1/auth/refresh	refresh token 换新 access token
POST	/api/v1/auth/register	自助注册（按 config 卡）
GET	/api/v1/prometheus/auth	Grafana 嵌入的 nginx auth_request 探针
POST	/api/v1/im/feishu/events	飞书入站回调；webhook 签名就是认证

已认证路由

iam（users、orgs、sessions）

方法	路径	角色	来源
GET	/v1/version	any	cmd/ongrid/main.go（内联）
GET	/v1/me	any	internal/iam/server/http.go
GET	/v1/self	any	internal/iam/server/http.go
GET	/v1/users	any	列用户
POST	/v1/users	admin	建用户
PATCH	/v1/users/{id}	admin	更新用户（name、email）
PATCH	/v1/users/{id}/password	self 或 admin	改密
PATCH	/v1/users/{id}/role	admin	改角色（admin/user/viewer）
DELETE	/v1/users/{id}	admin	删用户
GET	/v1/orgs	any	列组织
POST	/v1/orgs	admin	建组织
PATCH	/v1/orgs/{id}	admin	更新组织
DELETE	/v1/orgs/{id}	admin	删组织
GET	/v1/orgs/{id}/members	any	列成员
POST	/v1/orgs/{id}/members	admin	加成员
PATCH	/v1/orgs/{id}/members/{user_id}	admin	改成员角色
DELETE	/v1/orgs/{id}/members/{user_id}	admin	删成员

edge（tunnel 连接的 agent）

方法	路径	角色	描述
POST	/v1/edges	edge:*	建 edge，发 access+secret key
GET	/v1/edges	any	列 edge
GET	/v1/edges/{id}	any	取 edge 详情
DELETE	/v1/edges/{id}	edge:*	删 edge
POST	/v1/edges/{id}/rotate-secret	edge:*	轮换 secret key
POST	/v1/edges/{id}/upgrade	edge:*	触发远程 agent 升级，显式 URL+sha256
POST	/v1/edges/{id}/upgrade-package	edge:*	一键 bundle 升级（ADR-024）
GET	/v1/edges/{id}/processes	any	只读进程列表（按需 RPC）
GET	/v1/edges/{id}/plugins	any	列 edge 配置 + 活的插件（含健康）
PUT	/v1/edges/{id}/plugins/{name}	edge:plugin	启用/禁用 + 调插件
GET	/v1/integrations/plugin-counts	any	全局插件启用/禁用计数（给首页 tile）

device（host 实体，跟 tunnel 状态解耦）

方法	路径	角色	描述
GET	/v1/devices	any	列 host 设备
GET	/v1/devices/{id}	any	取设备详情
PATCH	/v1/devices/{id}	device:*	更新显示名、tag
DELETE	/v1/devices/{id}	device:*	删设备
PATCH	/v1/devices/{id}/roles	device:*	派角色（db、web、cache……）
GET	/v1/devices/{id}/edges	any	当前代表这台设备的 edge
GET	/v1/devices/{device_id}/shell	webshell	开 WebSSH 流（websocket 升级）

topology（带类型 CMDB）

方法	路径	角色	描述
GET	/v1/topology/node-types	any	列 node 类型 schema
POST	/v1/topology/node-types	topology:*	建 node 类型
GET	/v1/topology/node-types/{name}	any	取一个 node 类型
DELETE	/v1/topology/node-types/{name}	topology:*	删 node 类型
GET	/v1/topology/nodes	any	列 node（按 type、tag 过滤）
POST	/v1/topology/nodes	topology:*	建 node
GET	/v1/topology/nodes/{id}	any	取 node
PATCH	/v1/topology/nodes/{id}	topology:*	更新 node
DELETE	/v1/topology/nodes/{id}	topology:*	删 node
GET	/v1/topology/relation-types	any	列 relation 类型 schema
POST	/v1/topology/relation-types	topology:*	建 relation 类型
GET	/v1/topology/relation-types/{name}	any	取一个 relation 类型
DELETE	/v1/topology/relation-types/{name}	topology:*	删 relation 类型
GET	/v1/topology/relations	any	列边（relation）
POST	/v1/topology/relations	topology:*	建 relation
GET	/v1/topology/relations/{id}	any	取 relation
PATCH	/v1/topology/relations/{id}	topology:*	更新 relation
DELETE	/v1/topology/relations/{id}	topology:*	删 relation

alert（规则、incident、通道）

方法	路径	角色	描述
GET	/v1/alert-rules	any	列规则
POST	/v1/alert-rules	alert:*	建规则
GET	/v1/alert-rules/{id}	any	取规则
PUT	/v1/alert-rules/{id}	alert:*	替换规则
DELETE	/v1/alert-rules/{id}	alert:*	删规则
POST	/v1/alert-rules/{id}/enabled	alert:*	翻 enabled flag
POST	/v1/alert-rules/preview	alert:*	用当前数据对规则定义做 dry-run
GET	/v1/alerts/incidents	any	列 incident（过滤：status、severity、scope）
GET	/v1/alerts/incidents/{id}	any	取 incident
GET	/v1/alerts/incidents/{id}/events	any	事件 timeline
POST	/v1/alerts/incidents/{id}/ack	any	确认
POST	/v1/alerts/incidents/{id}/resolve	any	标 resolved
POST	/v1/alerts/incidents/{id}/silence	any	静默 N 小时
GET	/v1/alerts/incidents/{id}/investigation	any	取 AI 生成的调查报告
POST	/v1/alerts/incidents/{id}/investigation	any	触发或重跑调查
GET	/v1/alerts/runtime-info	any	evaluator 节奏 + 上次周期统计
GET	/v1/notification-channels	any	列通道
POST	/v1/notification-channels	channel:*	建通道
GET	/v1/notification-channels/{id}	any	取通道
PUT	/v1/notification-channels/{id}	channel:*	替换通道
DELETE	/v1/notification-channels/{id}	channel:*	删通道
POST	/v1/notification-channels/{id}/test	channel:*	发一条合成通知

规则的 JSON 形状见 告警规则 schema。

aiops（chat、agent、model）

方法	路径	角色	描述
GET	/v1/agents	any	列 agent persona
GET	/v1/agents/{name}	any	取 persona 详情
DELETE	/v1/agents/{name}	agent:*	删内置 / 磁盘 persona（罕见；通常只 custom 可删）
POST	/v1/agents/custom	agent:*	建用户定义的 persona
PATCH	/v1/agents/custom/{name}	agent:*	更新用户 persona
DELETE	/v1/agents/custom/{name}	agent:*	删用户 persona
GET	/v1/chat/sessions	any	列会话
POST	/v1/chat/sessions	any	建会话
PATCH	/v1/chat/sessions/{id}	any	改名 / 给会话打 tag
DELETE	/v1/chat/sessions/{id}	any	删会话
GET	/v1/chat/sessions/{id}/messages	any	消息历史
POST	/v1/chat/sessions/{id}/messages	any	发消息（非流式，返最终 reply）
POST	/v1/chat/sessions/{id}/messages/stream	any	发消息（SSE 流 token + tool 调用事件）
GET	/v1/aiops/models	any	可用 provider + 模型（按已配 API key 卡）
POST	/v1/aiops/query-translate	any	LLM 辅助的 PromQL / LogQL / TraceQL 组合
GET	/v1/aiops/mentions/search	any	@edge、@device、@dashboard 提及的自动补全
GET	/v1/usage/today	any	当前 UTC 日的 token 用量

markdown frontmatter 形状见 Agent persona 格式。

knowledge（RAG、vault、repo、上传）

方法	路径	角色	描述
GET	/v1/knowledge/docs	any	列文档（tree）
POST	/v1/knowledge/docs	knowledge:*	建文档
GET	/v1/knowledge/docs/{id}	any	取文档
PATCH	/v1/knowledge/docs/{id}	knowledge:*	改文档正文
PATCH	/v1/knowledge/docs/{id}/move	knowledge:*	移到另一路径
DELETE	/v1/knowledge/docs/{id}	knowledge:*	删文档
GET	/v1/knowledge/paths	any	列 path 节点（给 tree）
GET	/v1/knowledge/repos	any	列 Git repo
POST	/v1/knowledge/repos	knowledge:*	注册 repo
DELETE	/v1/knowledge/repos/{id}	knowledge:*	删 repo
POST	/v1/knowledge/repos/{id}/sync	knowledge:*	触发重新同步
POST	/v1/knowledge/upload	knowledge:*	上传 .md / .txt / .pdf / .docx（经 docextract 解析）
GET	/v1/knowledge/search	any	RAG 查询（返 chunk + score）
POST	/v1/knowledge/vault/sync	knowledge:*	重拉内置 vault from GitHub
GET	/v1/knowledge/ssh-identities	knowledge:*	列 Git 认证用的 SSH key
POST	/v1/knowledge/ssh-identities	knowledge:*	注册已有 SSH key
POST	/v1/knowledge/ssh-identities/generate	knowledge:*	生成新密钥对（私钥从不离开服务端）
PATCH	/v1/knowledge/ssh-identities/{id}	knowledge:*	改身份（name、comment）
DELETE	/v1/knowledge/ssh-identities/{id}	knowledge:*	删身份

skill（工具包内省）

方法	路径	角色	描述
GET	/v1/skills	any	列技能（manager scope + edge scope）
GET	/v1/skills/{key}	any	取技能详情（schema、description、scope、class）
POST	/v1/skills/{key}/execute	skill:*	直接执行技能（测试 / 调试）

磁盘 skill.json 形状见 Skill manifest。

logs / traces（只读代理）

方法	路径	角色	描述
GET	/v1/logs/query_range	any	代理 LogQL query_range
GET	/v1/logs/labels	any	代理 label 名
GET	/v1/logs/labels/{name}/values	any	代理 label 值
GET	/v1/traces/search	any	代理 TraceQL /api/search
GET	/v1/traces/{trace_id}	any	按 ID 取一条 trace
GET	/v1/traces/tags/{tag}/values	any	代理 /api/search/tag/.../values

monitor（dashboard / 面板）

方法	路径	角色	描述
GET	/v1/monitor/panels	any	列面板
POST	/v1/monitor/panels	monitor:*	建面板
PATCH	/v1/monitor/panels/{id}	monitor:*	改面板
DELETE	/v1/monitor/panels/{id}	monitor:*	删面板
GET	/v1/observability/dashboards/{uid}	any	render-ready Grafana dashboard JSON

metric（按 edge 指标快照）

方法	路径	角色	描述
GET	/v1/edges/{id}/metrics	any	最新的闭合集主机指标快照

prometheus（admin）

方法	路径	角色	描述
POST	/v1/prometheus/launch	admin	（重新）启动内嵌 Prometheus
POST	/v1/prometheus/query_range	any	LLM 工具面的 query_range（返规范化的 matrix）

imbridge（chat 面 —— Slack / Telegram / 飞书 / 钉钉 / 企业微信）

方法	路径	角色	描述
GET	/v1/im/apps	any	列已连 IM app
POST	/v1/im/apps	im:*	注册 IM app
GET	/v1/im/apps/{id}	any	取 app
PUT	/v1/im/apps/{id}	im:*	更新 app
DELETE	/v1/im/apps/{id}	im:*	删 app
POST	/v1/im/apps/{id}/reveal	admin	显示被掩码的 secret

marketplace（技能包）

方法	路径	角色	描述
GET	/v1/marketplace/registries	any	列配置的 registry
GET	/v1/marketplace/installed	any	列已装 pack
POST	/v1/marketplace/install	marketplace:*	从 registry 装 pack
DELETE	/v1/marketplace/installed/{pack_id}	marketplace:*	卸载 pack

setting（系统设置：集成、默认、secret）

方法	路径	角色	描述
GET	/v1/system-settings	any	列可见设置
PUT	/v1/system-settings/{category}/{key}	admin	upsert 设置
DELETE	/v1/system-settings/{category}/{key}	admin	删设置
GET	/v1/system-settings/{category}/{key}/reveal	admin	显示被掩码的 secret

integration（连通性测试）

方法	路径	角色	描述
POST	/v1/integrations/grafana/sync	admin	同步 dashboard + datasource
POST	/v1/integrations/grafana/test	admin	测 Grafana 连接
POST	/v1/integrations/llm/invalidate	admin	失效缓存 LLM client（强制重读 API key）
POST	/v1/integrations/loki/test	admin	测 Loki 连接
POST	/v1/integrations/prom/test	admin	测 Prometheus 连接
POST	/v1/integrations/tempo/test	admin	测 Tempo 连接
POST	/v1/integrations/websearch/test	admin	测 SearXNG / web-search 后端

webshell（基于 tunnel 的交互 shell）

方法	路径	角色	描述
GET	/v1/devices/{device_id}/shell	webshell	开 WebSocket 升级的 SSH 流
GET	/v1/webshell/sessions	any	列活会话
DELETE	/v1/webshell/sessions/{id}	webshell	kill 一个会话

audit（admin 日志）

方法	路径	角色	描述
GET	/v1/admin/audit-logs	admin	全租户审计链路（HLD-010）

分页

列表 endpoint 用不透明 cursor：

GET /v1/edges?limit=50&cursor=eyJpZCI6MTAwMH0

响应带 {"items":[...], "next_cursor":"...", "total":...}。next_cursor 在最后一页为空。

限流

开源构建里没有全局限流。LLM 预算门（ONGRID_LLM_DAILY_TOKEN_LIMIT）约束 chat 流量 —— 其他每个 endpoint 取决于你在 manager 前放了什么（nginx、你 自己的网关）。

版本

GET /v1/version 返回 {"manager_version":"vX.Y.Z"}。SPA 读它来标记 agent 版本跟 manager 漂移的 edge。给升级工具用。

另见

• 环境变量 —— 控制 API 行为的旋钮。
• 告警规则 schema —— /v1/alert-rules 的请求体。
• Skill manifest —— /v1/skills 和 marketplace install 的请求体。
• Agent persona 格式 —— /v1/agents/custom 的请求体。