V2
概览
了解 FlowUs V2 API 的用途、接口分类和推荐接入路径。
概览
FlowUs V2 API 适合用于构建应用集成、自动化脚本、内部工具和内容处理流程。你可以通过统一的 /v2/* 接口读取或写入页面、块、数据库、用户和搜索相关资源，也可以使用 Markdown、文件上传等扩展接口完成更复杂的接入场景。
除公开的 OpenAPI 元数据接口外，V2 API 都使用 Bearer Token 认证。正式接入前，建议先用 GET /v2/users/me 验证 token，再根据业务场景阅读对应的接口文档。
基本信息
| 项目 | 内容 |
|---|---|
| 基础地址 | https://api.flowus.cn |
| 路径前缀 | /v2 |
| 认证方式 | Authorization: Bearer <token> |
| 数据格式 | 请求体和响应体均为 JSON；文件内容上传到预签名地址，不通过 V2 JSON 请求体传输 |
| 公共路由 | GET /v2/openapi.json、GET /v2/openapi/meta |
| 权限模型 | 按 scope 控制读写能力，例如 pages.read、blocks.write、search.read |
接口分类
资源接口
资源接口是 V2 API 的主要入口，覆盖围绕资源对象的读取、创建、更新、删除和查询能力。
| 资源 | 典型能力 |
|---|---|
pages | 创建、读取、更新、删除页面，读取页面属性 |
blocks | 读取 block，读取或追加 block children，更新或删除 block |
databases | 创建、读取、更新、删除数据库，执行数据库查询 |
users | 获取当前身份，按 ID 获取用户信息 |
search | 按关键词搜索当前 token 可访问的页面和数据库 |
这些接口遵循统一的 Bearer Token 鉴权和标准化错误模型，适合按资源逐步接入。
扩展接口
扩展接口仍属于 V2 API，只是面向更具体的接入流程。
| 接口 | 适用场景 |
|---|---|
POST /v2/search/semantic | 按语义检索内容片段 |
GET /v2/pages/:page_id/content/markdown | 以 Markdown 读取页面内容 |
POST /v2/files/upload-url | 获取文件上传地址和后续创建块所需的文件信息 |
这些接口不会引入新的身份体系，仍然使用同一套 Bearer Token、scope 和错误模型。
OpenAPI 接口
OpenAPI 元数据接口只负责“描述 API 本身”，不承载业务资源操作。公开的元数据路由是：
GET /v2/openapi.jsonGET /v2/openapi/meta
它们用于自动化工具、文档生成和调试，不需要 token，可以在接入前直接访问。
接入建议
- 先阅读 认证与权限，确认 token 格式、公共路由和 scope 模型。
- 用 首次请求 中的
GET /v2/users/me验证 token 是否可用。 - 按资源类型阅读
read或write文档，并对照 对象模型 和 通用约定 处理分页、错误和时间字段。 - 如果要生成客户端、做 CI 校验或同步接口定义，直接使用 OpenAPI 参考。
阅读路径
| 路径 | 适合的场景 | 建议阅读顺序 |
|---|---|---|
read | 先了解能做什么，再决定接哪些只读能力 | 概览 → 认证与权限 → 首次请求 → 获取当前身份 |
write | 准备接入创建、更新、删除或上传类接口 | 认证与权限 → 对应资源参考页 → 错误码 |
advanced | 准备接入 Markdown、语义搜索或文件上传前置流程 | 概览 → 认证与权限 → 对应扩展接口页 |
reference | 需要核对 scope、错误模型、OpenAPI 元数据或返回字段 | scopes → error-codes → openapi |
公开契约
请以本文档和 GET /v2/openapi.json 返回的内容作为公开契约。未在文档中列出的路由、字段或行为，不应作为稳定能力依赖。
当 V2 API 新增公开能力时，相关路由、字段、scope 和错误码会同步补充到文档和 OpenAPI 定义中。