V2
搜索内容
使用关键字检索当前 token 可访问的页面、数据库和扩展 page 类型。
搜索内容
适用场景
当你需要按关键词查找当前 token 可访问的内容时，使用这个接口。它既能返回普通页面，也能返回数据库；对于文件夹和思维导图这类扩展 page 类型，也会通过 page 对象返回。
接口信息
| 项目 | 内容 |
|---|---|
| 方法 | POST |
| 路径 | /v2/search |
| 请求体 | JSON |
| 返回 | list |
| Scope | search.read |
权限要求
需要 search.read。没有这个 scope 时，请求会返回 403 forbidden。
请求参数
{
"query": "项目计划",
"filter": {
"property": "object",
"value": "page"
},
"sort": {
"timestamp": "last_edited_time",
"direction": "descending"
},
"start_cursor": null,
"page_size": 20
}| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
query | string | 否 | 搜索关键词；为空时表示不过滤关键词。 |
filter | object | 否 | 过滤条件，property 固定为 object。 |
filter.value | string | 否 | 支持 page、database、folder、mind_map。 |
sort | object | 否 | 排序条件。 |
sort.timestamp | string | 否 | 只支持 last_edited_time 和 created_time。 |
sort.direction | string | 否 | ascending 或 descending。 |
start_cursor | string | 否 | 分页游标。 |
page_size | number | 否 | 继承统一分页默认值，默认 20，最大 100。 |
响应结果
返回 list，results 中是当前 token 可访问的 page 或 database 对象。
{
"object": "list",
"results": [
{
"object": "page",
"id": "11111111-1111-4111-8111-111111111111",
"page_type": "page"
},
{
"object": "page",
"id": "33333333-3333-4333-8333-333333333333",
"page_type": "folder"
},
{
"object": "database",
"id": "66666666-6666-4666-8666-666666666666",
"title": [
{
"type": "text",
"text": {
"content": "任务看板",
"link": null
},
"plain_text": "任务看板",
"href": null
}
]
}
],
"next_cursor": null,
"has_more": false
}如果结果是 page-like 资源，page_type 会进一步区分普通页面、文件夹和思维导图。
行为说明
filter.value = "page"会返回页面类资源，包括普通页面、文件夹和思维导图。filter.value = "database"只返回数据库对象。filter.value = "folder"只返回文件夹类型页面。filter.value = "mind_map"只返回思维导图类型页面。sort.timestamp只接受last_edited_time和created_time，不支持其他时间字段。page_size沿用统一分页逻辑，未传时按20处理，最大不超过100。- 不支持的过滤或排序条件会直接报错，不会静默降级。
错误提示
400 validation_error：请求参数格式不正确。400 unsupported_filter：不支持的过滤条件。400 unsupported_sort：不支持的排序条件。401 unauthorized：token 无效或已过期。403 forbidden：缺少search.read或资源不可访问。