> ## Documentation Index
> Fetch the complete documentation index at: https://octop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

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

## 基础地址

```text theme={null}
http://127.0.0.1:8088/api
```

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

## 获取令牌

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

```text theme={null}
Authorization: Bearer <access_token>
```

对话 WebSocket 用同一个令牌，放在 `?token=<access_token>`。也可以用 OIDC 或邀请链接登录，见[认证](https://octop.mintlify.site/zh/api/authentication.md)。

## 交互式文档

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

**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** | 仅管理员 |

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

## 确认服务器可用

```bash theme={null}
curl http://127.0.0.1:8088/api/health
# {"status": "ok", "version": "0.9.28"}
```

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

## 浏览 API

> [card] [认证](https://octop.mintlify.site/zh/api/authentication.md)
>
> 登录、续期令牌，以及 OIDC 或邀请登录。

> [card] [用户与管理](https://octop.mintlify.site/zh/api/users-admin.md)
>
> 创建账号、发送邀请、查看审计。

> [card] [专家](https://octop.mintlify.site/zh/api/agents.md)
>
> 创建、共享并运行专家。

> [card] [对话](https://octop.mintlify.site/zh/api/chat.md)
>
> 流式对话并管理线程。

> [card] [知识库](https://octop.mintlify.site/zh/api/knowledge.md)
>
> 创建知识库并上传文档。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.