API Reference

索引自 VOLO AI 后端真实 Controller。最后同步时间见各页底部「最后更新」字段。

---

概览

VOLO AI 后端基于 Spring Boot 3.4 + WebFlux（响应式）+ R2DBC + SSE。所有端点遵循统一返回结构 ResponseResult<T>，流式端点返回裸 Flux<ServerSentEvent>。

Base URL    https://api.volo.ai
Protocol    HTTPS + Server-Sent Events
Encoding    UTF-8 / application/json
Auth        Bearer Token in Authorization header

---

四大业务域

域	关注	路径前缀	文档
Chat	流式对话、SSE 协议、Tool Approval、HITL Resume	/api/agent/chat/volo-ai/*	Chat →
Memory	记忆相册上传/检索/语义搜索	/api/memories/*	Memory →
Skill	技能市场浏览/安装/卸载	/api/skills/*	Skill →
Agent	Auth / Profile / 控制端点	/api/auth/* /api/user/*	Agent →

---

统一约定

鉴权

除登录注册外，所有端点需在请求头携带：

Authorization: Bearer volo-sk-xxxxxxxxxxxxxxxx

响应包装 · ResponseResult<T>

非流式端点统一返回：

{
  "code": 200,
  "message": "success.xxx",
  "data": { ... }
}

code	含义
200	成功
400	参数错误
401	未授权
403	无权限
404	资源不存在
429	速率限制
500	服务器异常

流式端点 · SSE

Content-Type: text/event-stream，返回 Flux<ServerSentEvent<AgentExecutionEvent>>。客户端按 EventSource 协议消费。

详见 Chat · SSE 协议。

分页约定

列表端点统一返回 PageResult<T>：

{
  "items": [...],
  "total": 1024,
  "page": 0,
  "pageSize": 20,
  "hasMore": true
}

默认 pageSize=20，最大 200（DATA_LOADING_SPEC.md 红线）。

时间格式

所有时间字段使用 OffsetDateTime 序列化为 ISO-8601：

2026-05-14T10:30:00+08:00

UUID

所有 ID 使用 UUID v4，例如 550e8400-e29b-41d4-a716-446655440000。

---

协议规范文档

规范	路径
VOLO AI 协议规范	docs/specs/VOLO_AI_PROTOCOL_SPEC.md
UI 事件协议	docs/specs/UI_EVENT_PROTOCOL.md
事件协议正交性	docs/specs/EVENT_PROTOCOL_ORTHOGONALITY.md
SubAgent 调度协议	docs/specs/SUBAGENT_PROTOCOL_SPEC.md

协议正本

所有协议规范以后端 AgentExecutionEvent.java 枚举为单一权威源。前端 TypeScript 常量 @/types/agent-protocol 自动镜像。