---
title: "HTTP API"
description: "本地服务端可编程接口的概览与认证方式。"
---

Bi 自带一个本地 HTTP 服务（默认 `8080` 端口），前端界面和外部脚本都通过它交互。这篇文章给出可编程接口的全貌，方便你写脚本或集成。

> 安全提示：服务默认监听 `:8080`（所有网卡）。详见本文末尾的「安全边界」。

## 认证

大部分端点要求登录，认证方式是 JWT：

```
Authorization: Bearer <token>
```

WebSocket 无法携带请求头，改用 `?token=` 查询参数。

- `POST /api/auth/register` — 注册
- `POST /api/auth/login` — 登录，返回 JWT
- `POST /api/auth/logout` — 登出
- `GET /api/auth/me` — 当前用户

## 会话与对话

| 端点 | 方法 | 说明 |
| --- | --- | --- |
| `/api/user/sessions` | `GET` / `POST` | 列会话 / 建会话 |
| `/api/user/sessions/{id}` | `GET` / `PUT` / `DELETE` | 取 / 改 / 删 |
| `/api/user/sessions/{id}/messages` | `POST` | 增量追加消息 |
| `/api/user/sessions/{id}/export` | `POST` | 导出 Markdown |
| `/api/chat` | `POST` | 驱动智能体执行一轮任务 |
| `/api/remote.mux` | WebSocket | 流式消息通道 |
| `/api/terminal` | WebSocket | 终端面板 |

## 配置与模型

| 端点 | 方法 | 说明 |
| --- | --- | --- |
| `/api/config` | `GET` / `POST` | 读 / 写运行配置 |
| `/api/models` | `GET` / `PUT` | 读 / 写多模型配置（`.bi/llm.json`） |
| `/api/models/probe` | `POST` | 探测模型端点 |
| `/api/agent/config` | `GET` / `POST` | 智能体运行参数 |

## 权限与规则

| 端点 | 方法 | 说明 |
| --- | --- | --- |
| `/api/rules` | `GET` / `POST` | 拦截规则读写 |
| `/api/permission` | `POST` | 批准一次权限请求 |
| `/api/permission/cancel` | `POST` | 取消权限请求 |
| `/api/auto-approve-rules` | `GET` / `POST` | 自动放行规则 |

## 工作区与文件

| 端点 | 方法 | 说明 |
| --- | --- | --- |
| `/api/workspace/tree` | `GET` | 目录树 |
| `/api/workspace/file` | `GET` | 读文件（文本） |
| `/api/workspace/raw` | `GET` | 读文件（原始字节） |
| `/api/workspace/write` | `POST` | 写文件 |
| `/api/workspace/move` | `POST` | 移动 / 重命名 |
| `/api/workspace/mkdir` | `POST` | 建目录 |
| `/api/workspace/exec` | `POST` | 执行命令 |
| `/api/workspace/changes` | `GET` | 工作区变更 |
| `/api/workspace/restore` | `POST` | 还原文件 |
| `/api/workspace/roots` | `GET` | 可用的项目根目录 |
| `/api/workspace/validate` | `POST` | 校验目录为合法工作区 |
| `/api/upload` | `POST` | 上传文件 |
| `/uploads/` | `GET` | 访问上传的文件 |

## 检查点与产物

| 端点 | 方法 | 说明 |
| --- | --- | --- |
| `/api/checkpoint` | `GET` / `POST` | 检查点列表 / 创建 |
| `/api/checkpoint/{id}` | `GET` / `POST` | 检查点详情 / 回退 |

## 其它

| 端点 | 方法 | 说明 |
| --- | --- | --- |
| `/api/stats` | `GET` | 用量统计 |
| `/api/system/info` | `GET` | 系统信息（含遥测开关状态） |
| `/api/skills` | `GET` | 技能列表 |
| `/api/conversation/network` | `GET` | 网络活动记录 |

## 安全边界

**默认监听所有网卡（`0.0.0.0:8080`），且部分端点无登录校验。** 请自行确认谁可以访问这个端口：

- 同网段的其它设备、本机其它进程、端口转发都可能触达
- 请根据使用场景决定是否通过防火墙、反向代理或改监听地址来收窄暴露面
- 不要把它当作用户认证层来依赖——它首先是本地开发工具