Skip to main content
English 使用 Gateway 作为 API base URL。产品管理调用使用用户身份；业务系统调用已发布能力优先使用 Endpoint。

​
认证与范围

POST /api/auth/login 接受 {"username":"...","password":"..."}，响应包含 token。随后用 Authorization: Bearer TOKEN。GET /api/auth/me 检查身份，POST /api/auth/logout 退出。 空间请求可携带 X-AgentScope-Tenant、X-AgentScope-Namespace；有 tenant/namespace 请求字段时保持一致。单空间安装由服务器确定权威范围；多空间安装使用当前账号已授权的值，不假定存在名为 default 的共享空间。

​
常用资源

以下路径均相对 Gateway，{id} 为响应中的资源 ID，而不是显示名称。

​
Chat 请求示例

使用已有 Agent ID 和已授权空间创建，响应的 chat.id 用于后续消息：
发送消息的 body 是 {"message":"请概括这段材料"}。该产品 API 与运行时 /api/sessions 事件协议不同，不要混用请求格式。

​
Issue 验收与并发编辑

先 GET /api/v1/issues/{id}，核对结果与 issue.version。accept body 为 {"expectedVersion":7}；reject body 为 {"expectedVersion":7,"reason":"缺少来源证据"}，将 7 替换为刚读取的版本。 接口不统一使用同一个版本字段：Chat patch 使用 version，Issue 决策和 Workflow 发布使用 expectedVersion，Endpoint 发布使用 version。409 后重新读取和审阅，不自动用新版本重放旧决策。

​
Endpoint 调用

job 和 conversation 的详细请求、凭据、状态与 SSE 示例见 Endpoint 指南。创建请求必须使用逻辑请求级 Idempotency-Key；使用返回的 statusUrl/eventsUrl 跟踪，不绕过 Endpoint 直接操作内部任务。

​
错误处理

记录请求关联 ID、资源 ID、发生时间、状态码和脱敏错误。SDK 自定义适配器参考 External Agent，执行状态见 Sessions 与 Runs。