Octop REST 与 WebSocket API：端点与访问说明

Octop 在 /api 提供 REST 与 WebSocket。需要在浏览器里试调用时，打开 /api/docs。

Octop 的功能都可以通过 /api 下的 HTTP 和 WebSocket 调用。大多数端点需要先用 POST /api/auth/login 拿到 JWT。响应一般是 JSON；流式接口和文件下载除外。

​

基础地址

http://127.0.0.1:8088/api

若 Octop 跑在其他主机或端口，请替换这里的地址。

​

获取令牌

把用户名和密码发到 POST /api/auth/login，之后在请求里带上：

Authorization: Bearer <access_token>

对话 WebSocket 用同一个令牌，放在 ?token=<access_token>。也可以用 OIDC 或邀请链接登录，见认证。

​

交互式文档

Octop 内置 Scalar 页面，方便在浏览器里试接口。默认关闭。

1. 打开开关

   在 ~/.octop/config.json 中设置 "enable_api_docs": true，或设置 OCTOP_ENABLE_API_DOCS=1。

2. 重启 Octop

   重启 octop run。

3. 打开文档

   访问 http://127.0.0.1:8088/api/docs。原始 OpenAPI 始终在 /api/openapi.json。

​

谁可以调用

级别	含义
public	不需要令牌（健康检查、登录、首次设置、OAuth 回调）
user	任意已登录账号
owner	资源所有者，或管理员
admin	仅管理员

管理员可以做所有事。普通用户只有被授予对应权限后，才能改设置类接口。

​

确认服务器可用

curl http://127.0.0.1:8088/api/health
# {"status": "ok", "version": "0.9.28"}

登录有次数限制（默认 5 次失败后锁定 15 分钟）。管理员可以在管理 → 用户中解锁账号。

​

浏览 API

认证

登录、续期令牌，以及 OIDC 或邀请登录。

用户与管理

创建账号、发送邀请、查看审计。

专家

创建、共享并运行专家。

对话

流式对话并管理线程。

知识库

创建知识库并上传文档。