V2
更新页面
更新页面属性、图标、封面或回收站状态，并支持并发控制。
更新页面
适用场景
当你要改写页面标题、页面属性、图标、封面，或切换页面的回收站状态时使用这个接口。它支持并发控制，适合多人协作场景。
接口信息
| 项目 | 内容 |
|---|---|
| 方法 | PATCH |
| 路径 | /v2/pages/:page_id |
| 请求体 | page 局部更新参数 |
| 返回 | page |
| Scope | pages.write |
权限要求
需要 pages.write。
请求参数
请求头
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
Authorization | string | 是 | Bearer <token>。 |
If-Match | string | 否 | 乐观锁标记。建议填入上次读取到的页面版本标识。 |
请求头示例：
If-Match: W/"2026-04-09T09:30:00.000Z"请求体
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
properties | object | 否 | 页面属性，按需部分更新。 |
icon | object | null | 否 | 页面图标，设为 null 表示移除。 |
cover | object | null | 否 | 页面封面，设为 null 表示移除。 |
in_trash | boolean | 否 | 回收站状态。 |
请求体示例：
{
"properties": {
"title": {
"type": "title",
"title": [
{
"type": "text",
"text": {
"content": "季度规划（更新）"
}
}
]
}
},
"icon": {
"type": "emoji",
"emoji": "🚀"
},
"cover": {
"type": "external",
"external": {
"url": "https://example.com/cover.png"
}
},
"in_trash": false
}响应结果
{
"object": "page",
"id": "22222222-2222-4222-8222-222222222222",
"page_type": "page",
"parent": {
"type": "page_id",
"page_id": "55555555-5555-4555-8555-555555555555"
},
"in_trash": false,
"icon": {
"type": "emoji",
"emoji": "🚀"
},
"cover": null,
"properties": {
"title": {
"id": "title",
"type": "title",
"title": [
{
"type": "text",
"text": {
"content": "季度规划（更新）",
"link": null
},
"plain_text": "季度规划（更新）",
"href": null
}
]
}
}
}行为说明或限制
- 这是部分更新接口，只会更新你传入的字段。
properties只会覆盖对应属性，不会清空未传入的其他属性。icon和cover传null时表示移除。in_trash用于切换页面的回收站状态。- 如果传了
If-Match且与当前版本不一致，会拒绝写入。
错误提示
401 unauthorized：token 无效或已过期。403 forbidden：缺少pages.write或无权访问该页面。404 not_found：页面不存在。409 conflict：If-Match与当前页面版本不一致。