飞书开放平台 Server API 文档

主题

文档搜索 ​

该接口用于根据搜索关键词（query）对当前用户可见的云文档进行搜索

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/search/v2/doc_wiki/search
HTTP MethodPOST
接口频率限制100 次/分钟
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用search:docs:read 搜索云文档

请求头 ​

名称类型必填描述
Authorizationstring是user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token
Content-Typestring是固定值："application/json; charset=utf-8"

请求体 ​

名称类型必填描述
querystring是搜索关键词（query至少搭配一种doc/wiki筛选器）
示例值："飞书文档使用指南"
数据校验规则：
- 长度范围：0 ～ 50 字符
doc_filterdoc_filter否文档过滤参数（doc_filter与wiki_filter至少传一个）
示例值：{"folder_tokens": ["fld_123456"]}
  └ creator_idsstring\[\]否文档所有者OpenID
示例值：["ou_789012"]
数据校验规则：
- 长度范围：0 ～ 20
  └ doc_typesstring\[\]否文档类型
示例值：["SHORTCUT"]
可选值有：
- DOC: 文档 - SHEET: 表格 - BITABLE: 多维表格 - MINDNOTE: 思维导图 - FILE: 文件 - WIKI: wiki - DOCX: 新版文档 - FOLDER: space文件夹 - CATALOG: wiki2.0文件夹 - SLIDES: 新版本幻灯片 - SHORTCUT: 快捷方式
数据校验规则：
- 长度范围：0 ～ 10
  └ folder_tokensstring\[\]否搜索文件夹内的文档（文件夹token列表） 注：如果存在该字段则wiki筛选器失效
示例值：["fld_123456"]
数据校验规则：
- 长度范围：0 ～ 50
  └ only_titleboolean否仅搜文档标题
示例值：false
默认值：false
  └ open_timetime_range否浏览文档的时间范围（秒级时间戳，包含start和end字段）
    └ startint否时间范围的起始时间戳
示例值：1742348544
数据校验规则：
- 取值范围：0 ～ 9223372036854775807
    └ endint否时间范围的截止时间戳
示例值：1742348544
数据校验规则：
- 取值范围：0 ～ 9223372036854775807
  └ sort_typestring否排序方式
示例值："CREATE_TIME"
可选值有：
- DEFAULT_TYPE: 默认排序 - OPEN_TIME: User打开时间排序 - EDIT_TIME: User编辑时间降序 - EDIT_TIME_ASC: User编辑时间升序 - ENTITY_CREATE_TIME_ASC: 实体创建时间升序（已废弃） - ENTITY_CREATE_TIME_DESC: 实体创建时间降序（已废弃） - CREATE_TIME: 按文档创建时间排序 - CREATE_TIME_ASC: 按文档创建时间正序（该排序暂不支持）
  └ create_timetime_range否文档创建的时间范围（秒级时间戳，包含start和end字段）
    └ startint否时间范围的起始时间戳
示例值：1742348544
数据校验规则：
- 取值范围：0 ～ 9223372036854775807
    └ endint否时间范围的截止时间戳
示例值：1742348544
数据校验规则：
- 取值范围：0 ～ 9223372036854775807
wiki_filterwiki_filter否Wiki过滤参数（doc_filter与wiki_filter至少传一个）
示例值：{"creator_ids": ["ou_789012"], "space_ids": ["space_123456"]}
  └ creator_idsstring\[\]否Wiki所有者OpenID
示例值：["ou_7890123456abcdef"]
数据校验规则：
- 长度范围：0 ～ 20
  └ doc_typesstring\[\]否Wiki类型
示例值：["SHORTCUT"]
可选值有：
- DOC: 文档 - SHEET: 表格 - BITABLE: 多维表格 - MINDNOTE: 思维导图 - FILE: 文件 - WIKI: 维基 - DOCX: 新版文档 - FOLDER: space文件夹 - CATALOG: wiki2.0文件夹 - SLIDES: 新版本幻灯片 - SHORTCUT: 快捷方式
数据校验规则：
- 长度范围：0 ～ 10
  └ space_idsstring\[\]否搜索某个Space下的Wiki（Space ID列表）
示例值：["space_1234567890fedcba"]
数据校验规则：
- 长度范围：0 ～ 50
  └ only_titleboolean否仅搜Wiki标题
示例值：false
默认值：false
  └ open_timetime_range否浏览文档的时间范围（秒级时间戳，包含start和end字段）
    └ startint否时间范围的起始时间戳
示例值：1742348544
数据校验规则：
- 取值范围：0 ～ 9223372036854775807
    └ endint否时间范围的截止时间戳
示例值：1742348544
数据校验规则：
- 取值范围：0 ～ 9223372036854775807
  └ sort_typestring否排序方式
示例值："CREATE_TIME"
可选值有：
- DEFAULT_TYPE: 默认排序 - OPEN_TIME: User打开时间排序 - EDIT_TIME: User编辑时间降序 - EDIT_TIME_ASC: User编辑时间升序 - ENTITY_CREATE_TIME_ASC: 实体创建时间升序（已废弃） - ENTITY_CREATE_TIME_DESC: 实体创建时间降序（已废弃） - CREATE_TIME: 按文档创建时间排序 - CREATE_TIME_ASC: 按文档创建时间正序（该排序暂不支持）
  └ create_timetime_range否Wiki创建的时间范围（秒级时间戳，包含start和end字段）
    └ startint否时间范围的起始时间戳
示例值：1742348544
数据校验规则：
- 取值范围：0 ～ 9223372036854775807
    └ endint否时间范围的截止时间戳
示例值：1742348544
数据校验规则：
- 取值范围：0 ～ 9223372036854775807
page_tokenstring否分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果
示例值："token_1234567890fedcba"
page_sizeint否分页大小
示例值：15
默认值：0
数据校验规则：
- 取值范围：0 ～ 20

请求体示例 ​

json
{
    "query": "飞书文档使用指南",
    "doc_filter": {
        "creator_ids": [
            "ou_789012"
        ],
        "doc_types": [
            "SHORTCUT"
        ],
        "folder_tokens": [
            "fld_123456"
        ],
        "only_title": false,
        "open_time": {
            "start": 1742348544,
            "end": 1742348544
        },
        "sort_type": "CREATE_TIME",
        "create_time": {
            "start": 1742348544,
            "end": 1742348544
        }
    },
    "wiki_filter": {
        "creator_ids": [
            "ou_7890123456abcdef"
        ],
        "doc_types": [
            "SHORTCUT"
        ],
        "space_ids": [
            "space_1234567890fedcba"
        ],
        "only_title": false,
        "open_time": {
            "start": 1742348544,
            "end": 1742348544
        },
        "sort_type": "CREATE_TIME",
        "create_time": {
            "start": 1742348544,
            "end": 1742348544
        }
    },
    "page_token": "token_1234567890fedcba",
    "page_size": 15
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ totalint匹配结果总数（辅助分页参考）
  └ has_moreboolean是否还有更多项
  └ res_unitsdoc_res_unit\[\]搜索结果列表
    └ title_highlightedstring标题高亮
    └ summary_highlightedstring摘要高亮
    └ entity_typestring结果类型
可选值有：
- DOC: doc实体 - WIKI: wiki类型
    └ result_metadoc_meta文档搜索元信息
      └ doc_typesstring文档类型
可选值有：
- DOC: 文档 - SHEET: 表格 - BITABLE: 多维表格 - MINDNOTE: 思维导图 - FILE: 文件 - WIKI: 维基 - DOCX: 新版文档 - FOLDER: space文件夹 - CATALOG: wiki2.0文件夹 - SLIDES: 新版本幻灯片 - SHORTCUT: 快捷方式
      └ update_timeint更新时间戳（秒）
      └ urlstring文档链接
      └ owner_namestring所有者名称
      └ owner_idstring所有者OpenID
      └ is_cross_tenantboolean是否跨租户
      └ create_timeint文档创建时间戳（秒）
      └ last_open_timeint上次打开时间戳（秒）
      └ edit_user_idstring最后一次编辑用户OpenID
      └ edit_user_namestring最后一次编辑用户名称
      └ tokenstring文档token
  └ page_tokenstring分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "total": 100,
        "has_more": true,
        "res_units": [
            {
                "title_highlighted": "飞书文档使用指南",
                "summary_highlighted": "本文介绍飞书文档的创建、编辑与分享功能",
                "entity_type": "DOC",
                "result_meta": {
                    "doc_types": "SHORTCUT",
                    "update_time": 1766567446,
                    "url": "https://www.feishu.cn/docs/dox-1234567890abcdef",
                    "owner_name": "张三",
                    "owner_id": "ou-7890123456abcdef",
                    "is_cross_tenant": false,
                    "create_time": 1766567446,
                    "last_open_time": 1766567446,
                    "edit_user_id": "ou-1122334455aabbcc",
                    "edit_user_name": "李四",
                    "token": "dox_9876543210fedcba"
                }
            }
        ],
        "page_token": "token_1234567890fedcba"
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
4001274001invalid param: missing required fields检查请求头和请求体中是否包含必要的认证信息且字段是否完整
4001274002invalid param: illegal enum value验证枚举字段的值是否符合定义的合法枚举范围
4011274011user_access_token is invalid or expired检查user_access_token是否正确或过期
4291277001rate limit exceeded检查当前请求频率是否超过接口限制阈值

内容来源：飞书开放平台 · 自动爬取整理

本镜像仅供学习与查阅，文档版权归飞书所有