接入指南

Note 在接入新版文档 OpenAPI 前，请先阅读新版文档 OpenAPI 接入指引。

形态

新版文档编辑器由文档级演进到段落级，「段落」通常也称之为「块」，在新版文档的数据结构中将其定义为 Block。Block 作为内容结构化的组成元素，是有着明确含义的信息单元。多个 Block 间可以形成树状关系的层级内容，树的根节点本身也是一个特殊类型的 Block，其被称为 Page Block。对于形成了父子关系的 Block，儿子 Block 被称之为 Children。

块列表

类型	描述
page	文档 Block，是整个文档树的根节点
text	文本 Block
headingN	标题 Block，headingN，N 取值范围1~9
bullet	无序列表 Block
ordered	有序列表 Block
code	代码块 Block
quote	引用 Block
todo	任务 Block
bitable	多维表格 Block
callout	高亮块 Block
chat_card	会话卡片 Block
diagram	UML 图 Block
divider	分割线 Block
file	文件 Block
grid	分栏 Block
grid_column	分栏列 Block
iframe	内嵌 Block
image	图片 Block
isv	三方 Block
mindnote	思维笔记 Block
sheet	电子表格 Block
table	表格 Block
table_cell	单元格 Block
view	视图 Block
quote_container	引用容器 Block
task	任务 Block
okr	OKR Block
okr_objective	OKR Objective Block
okr_key_result	OKR Key Result Block
okr_progress	OKR 进展 Block
add_ons	文档小组件 Block
jira_issue	Jira 问题 Block
wiki_catalog	Wiki 子目录 Block
undefined	未支持 Block

Block 类型枚举值定义：点击查看 BlockType。

限制

QPS 限制

每个接口都有调用频率限制，具体可参考对应接口文档的频控说明。

接口错误

当请求不符合某些特定条件时会报错，具体可参考对应接口文档「错误码」部分。

能力边界

当前新版文档 OpenAPI 操作 Block 能力边界：

Block	创建	读取内容	编辑内容
Callout	支持	支持	支持
Table	支持	支持	支持
Text	支持	支持	支持
Divider	支持	-	-
Grid	支持	支持	支持
Iframe	支持	支持	不支持
ChatCard	支持	-	-
Image	支持	-	-
File	支持	-	-
TableCell	-	支持	支持
GridColumn	-	支持	支持
View	-	支持	不支持
ISV	支持	-	-
Bitable	支持	-	-
Sheet	支持	-	-
Mindnote	不支持	-	-
Diagram	不支持	不支持	不支持
QuoteContainer	支持	支持	支持
Task	不支持	-	-
OKR	支持	支持	-
OKR Objective	-	支持	-
OKR Key Result	-	支持	-
OKR Progress	-	支持	-
Add Ons	支持	支持	-
Jira 问题	-	支持	-
Wiki 子目录	支持	支持	-
Undefined	-	-	-

==-== 表示不在支持范围内，比如：
不支持直接创建 TableCell，因为在对 Table 添加行或列时，会自动创建 TableCell；
不支持直接读取 Bitable，可根据返回的 Bitable ==Token== 调用对应的 Bitable 开放接口。
Block 类型枚举值定义：点击查看 BlockType。

查询文档基本信息

查询文档的最新版本号、标题，该接口只返回文档的基本信息，并不返回文档内容。

bash

curl --location --request GET 'https://open.feishu.cn/open-apis/docx/v1/documents/doxcnAJ9VRRJqVMYZ1MyKnavXWe' \
--header 'Authorization: Bearer u-xxx' # 调用前请替换为真实的访问令牌

查询文档纯文本内容

获取文档的纯文本内容，不包含富文本格式信息。

bash

curl --location --request GET 'https://open.feishu.cn/open-apis/docx/v1/documents/doxcnAJ9VRRJqVMYZ1MyKnavXWe/raw_content' \
--header 'Authorization: Bearer u-xxx' # 调用前请替换为真实的访问令牌

获取文档所有块

对指定文档所有的块进行深度遍历并分页返回。

BASH

curl --location --request GET 'https://open.feishu.cn/open-apis/docx/v1/documents/doxcnAJ9VRRJqVMYZ1MyKnavXWe/blocks?page_size=100&document_revision_id=-1' \
--header 'Authorization: Bearer u-xxx' # 调用前请替换为真实的访问令牌

创建文档

支持通过 folder_token 参数指定云空间目录。

bash

curl --location --request POST 'https://open.feishu.cn/open-apis/docx/v1/documents?folder_token=fldcnbCHL8OAtkcYHnPzZi1yupN' \
--header 'Authorization: Bearer u-xxx' # 调用前请替换为真实的访问令牌

获取块

查询指定块的富文本内容。

此接口不会返回子块信息, 如需获取请结合使用「获取所有子块」。

bash

curl --location --request GET 'https://open.feishu.cn/open-apis/docx/v1/documents/doxcnAJ9VRRJqVMYZ1MyKnavXWe/blocks/doxcnC4cO4qUui6isgnpofh5edc?document_revision_id=-1' \
--header 'Authorization: Bearer u-xxx' # 调用前请替换为真实的访问令牌

创建块

为指定块创建一批子块，并插入到特定位置。此接口返回值是被新创建子块的富文本内容。

如不指定版本，默认使用最新版本。

bash

curl --location --request POST 'https://open.feishu.cn/open-apis/docx/v1/documents/doxcnAJ9VRRJqVMYZ1MyKnavXWe/blocks/doxcnAJ9VRRJqVMYZ1MyKnavXWe/children?document_revision_id=120' \
--header 'Authorization: Bearer u-xxx' # 调用前请替换为真实的访问令牌 \
--header 'Content-Type: application/json' \
--data-raw '{
    "index": 0,
    "children": [
        {
            "block_type": 2,
            "text": {
                "elements": [
                    {
                        "text_run": {
                            "content": "多人实时协同，插入一切元素。不仅是在线文档，更是",
                            "text_element_style": {
                                "background_color": 14,
                                "text_color": 5
                            }
                        }
                    },
                    {
                        "text_run": {
                            "content": "强大的创作和互动工具",
                            "text_element_style": {
                                "background_color": 14,
                                "bold": true,
                                "text_color": 5
                            }
                        }
                    }
                ],
                "style": {}
            }
        }
    ]
}'

更新块

更新指定块，并返回其更新后的富文本内容。

如不指定版本，默认使用最新版本

bash

curl --location --request PATCH 'https://open.feishu.cn/open-apis/docx/v1/documents/doxcnAJ9VRRJqVMYZ1MyKnavXWe/blocks/doxcnC4cO4qUui6isgnpofh5edc' \
--header 'Authorization: Bearer u-xxx' # 调用前请替换为真实的访问令牌 \
--header 'Content-Type: application/json' \
--data-raw '{
    "update_text_elements":{
        "elements":[
            {
                "text_run": {
                        "content": "云空间",
                        "text_element_style": {
                            "link": {
                                "url": "https%3A%2F%2Fbytedance.feishu.cn%2Fdrive%2Fhome%2F"
                            }
                        }
                    }
            }
        ]
    }
}'

批量更新块

批量更新指定块，并返回其更新后的富文本内容。

如不指定版本，默认使用最新版本

bash

curl --location --request PATCH 'https://open.feishu.cn/open-apis/docx/v1/documents/doxcnAJ9VRRJqVMYZ1MyKnavXWe/blocks/batch_update' \
--header 'Authorization: Bearer u-xxx'  # 调用前请替换为真实的访问令牌  
--header 'Content-Type: application/json' \
--data-raw '{
    "requests": [
        {
            "block_id": "doxcnk0i44OMOaouw8AdXuXrp6b",
            "merge_table_cells": {
                "column_end_index": 2,
                "column_start_index": 0,
                "row_end_index": 1,
                "row_start_index": 0
            }
        },
        {
            "block_id": "doxcn0K8iGSMW4Mqgs9qlyTP50d",
            "update_text_elements": {
                "elements": [
                    {
                        "text_run": {
                            "content": "Hello",
                            "text_element_style": {
                                "background_color": 2,
                                "bold": true,
                                "italic": true,
                                "strikethrough": true,
                                "text_color": 2,
                                "underline": true                            }
                        }
                    },
                    {
                        "text_run": {
                            "content": "World ",
                            "text_element_style": {
                                "italic": true
                            }
                        }
                    },
                    {
                        "mention_doc": {
                            "obj_type": 22,
                            "token": "doxcnAJ9VRRJqVMYZ1MyKnayXWe",
                            "url": "https://test.feishu.cn/docx/doxcnAJ9VRRJqVMYZ1MyKnayXWe"
                        }
                    }
                ]
            }
        }
    ]
}'

删除块

指定需要操作的块，删除其指定范围的子块，并返回应用操作后的文档版本。

我们可以将新版文档看成一颗 Block 树，删除块可看成是删除其父亲块的孩子，即先明确要删除的块是其父亲块的第几个孩子，然后再调用本接口进行删除。

bash

curl --location --request DELETE 'https://open.feishu.cn/open-apis/docx/v1/documents/doxcnAJ9VRRJqVMYZ1MyKnavXWe/blocks/doxcnAJ9VRRJqVMYZ1MyKnavXWe/children/batch_delete?document_revision_id=-1' \
--header 'Authorization: Bearer u-xxx' # 调用前请替换为真实的访问令牌 \
--header 'Content-Type: application/json' \
--data-raw '{
   "start_index": 0,
   "end_index": 1
}'

获取所有子块

指定需要操作的块，分页遍历其子块的富文本内容。

此接口仅返回子块的富文本内容。

bash

curl --location --request GET 'https://open.feishu.cn/open-apis/docx/v1/documents/doxcnAJ9VRRJqVMYZ1MyKnavXWe/blocks/doxcnAJ9VRRJqVMYZ1MyKnavXWe/children?document_revision_id=-1&page_size=10' \
--header 'Authorization: Bearer u-xxx' # 调用前请替换为真实的访问令牌

事件

工作空间枚举

工作空间数据表

工作空间视图

角色

apiRef

内容

文件

文件夹

数据校验

表格操作

货币信息

地点 · 数据

事件

事件

审批 · 搜索

飞书原生审批

应用商店集成

第三方审批集成

接入指南 ​

形态 ​

块列表 ​

限制 ​

QPS 限制 ​

接口错误 ​

能力边界 ​

查询文档基本信息 ​

查询文档纯文本内容 ​

获取文档所有块 ​

创建文档 ​

获取块 ​

创建块 ​

更新块 ​

批量更新块 ​

删除块 ​

获取所有子块 ​

接入指南

形态

块列表

限制

QPS 限制

接口错误

能力边界

查询文档基本信息

查询文档纯文本内容

获取文档所有块

创建文档

获取块

创建块

更新块

批量更新块

删除块

获取所有子块