> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

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

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

## 基础地址

```text
http://127.0.0.1:8088/api
```

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

## 获取令牌

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

```text
Authorization: Bearer <access_token>
```

对话 WebSocket 用同一个令牌，放在 `?token=<access_token>`。也可以用 OIDC、飞书 / 钉钉 / 企业微信 OAuth、LDAP（同一登录表单）或邀请链接登录，见[认证](/api/authentication.md)。外部程序可通过 [Agent MCP](/api/agent-mcp.md) 调用专家。

## 交互式文档

Octop 内置 [Scalar](https://scalar.com/) 页面，方便在浏览器里试接口。默认**关闭**。


### 打开开关

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

### 重启 Octop

重启 `octop run`。

### 打开文档

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

## 谁可以调用

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

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

## 确认服务器可用

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

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

## 浏览 API


[**认证**](/api/authentication.md)

密码、LDAP、OIDC、OAuth SSO 或邀请登录。

[**用户与管理**](/api/users-admin.md)

账号、角色、邀请与目录登录。

[**专家**](/api/agents.md)

创建、共享并运行专家。

[**Agent MCP**](/api/agent-mcp.md)

让外部 MCP 客户端调用专家。

[**对话**](/api/chat.md)

流式对话并管理线程。

[**知识库**](/api/knowledge.md)

创建知识库并上传文档。
