V2

对象模型

了解 V2 API 中的核心对象结构，包括 user、page、database 和 block。

对象模型

适用范围

本页定义 V2 API 中最基础、最常被复用的对象外形。这里关注“对象长什么样”，不解释具体接口的权限、分页、过滤或写入规则。

核心定义

对象	说明
`user`	普通用户对象，表示可被引用的成员或访客。
`bot_user`	当前 token 对应的集成身份。
`page`	页面对象，承载页面元数据和页面属性。
`database`	数据库对象，承载数据库标题、描述和属性 schema。
`block`	内容块对象，承载页面正文、结构和嵌套内容。
`list`	统一分页列表包装。
`search_result`	语义搜索返回的结果对象。

字段说明或规则

`user`

user 用于表示具体的人或可被引用的身份。典型字段包括 id、type、name、avatar_url 和 person。

object 固定为 "user"
id 是用户的唯一标识
person.email 是否可见，取决于是否具备 users.email.read

`bot_user`

bot_user 描述当前 token 所代表的集成身份，而不是创建集成的人本身。

object 固定为 "bot_user"
workspace_id 和 workspace_name 标识所属空间
owner 是创建者的 user 引用
capabilities 展示当前 token 可用的能力集合
type 固定为 "integration"
integration_id 关联外部集成身份

`page`

page 表示页面实体，既可以是普通页面，也可以是文件夹或思维导图等 FlowUs 扩展页面类型。

object 固定为 "page"
page_type 是 FlowUs 扩展字段，取值为 "page"、"folder" 或 "mind_map"
parent 可以指向 workspace、page、database 或 block
properties 是页面属性值集合，具体字段定义见页面属性模型
icon、cover 可以为 null

`database`

database 表示数据库实体，用来组织结构化数据。

object 固定为 "database"
title 和 description 都是 rich_text 数组
properties 是数据库属性 schema，具体字段定义见页面属性模型
is_inline 表示是否为行内数据库
parent 可以指向 workspace 根级、页面或数据库
当对象位于工作区根级时，parent 可能是 { type: "workspace", workspace: true }

`block`

block 表示可嵌套的内容块，是页面正文和结构的基础单元。

object 固定为 "block"
type 决定当前块的内容外形，完整类型集见 Block 类型
has_children 表示是否还有子块
in_trash 表示是否已进入回收站
parent 可以指向 workspace 根级、页面、数据库或其他块
当对象位于工作区根级时，parent 可能是 { type: "workspace", workspace: true }

`list`

list 是统一分页包装。

object 固定为 "list"
results 是当前页结果数组
has_more 表示是否还有下一页
next_cursor 是下一页游标，无更多数据时为 null

list 只定义外壳，不限定 results 中一定是同一种对象；具体元素类型由对应接口决定。

`search_result`

search_result 用于语义搜索结果，而不是普通的页面或数据库对象。

object 固定为 "search_result"
page_id 和 page_title 用于定位结果来源
score 表示匹配分数，可能为 null
snippet 是可展示的命中摘要
url 指向结果页面

常见注意事项

page 和 database 都是“对象”，但一个表达页面，一个表达结构化集合，不要把它们当成同一类资源。
page_type 只在 page 上出现，是 FlowUs 扩展字段，不要把它当成独立对象类型。
search_result 只出现在语义搜索场景，不等同于关键词搜索返回的页面或数据库对象。

相关文档

相关能力

相关参考