更新块

适用场景

当你要对单个 block 做局部修改时使用这个接口。它会按 block 类型展开对应字段，只改你传入的那部分内容。

接口信息

权限要求

需要 blocks.write。

请求参数

常见可更新块类型示例：

• paragraph
• heading_2
• to_do
• code

下面这个请求示例只演示 paragraph，但同样的部分更新模式也适用于其他可写块类型：

请求体示例：

{
  "paragraph": {
    "rich_text": [
      {
        "type": "text",
        "text": {
          "content": "这里是一段更新后的正文内容。"
        }
      }
    ]
  }
}

响应结果

{
  "object": "block",
  "id": "88888888-8888-4888-8888-888888888888",
  "type": "paragraph",
  "paragraph": {
    "rich_text": [
      {
        "type": "text",
        "text": {
          "content": "这里是一段更新后的正文内容。",
          "link": null
        },
        "plain_text": "这里是一段更新后的正文内容。",
        "href": null
      }
    ],
    "color": "default"
  }
}

行为说明或限制

• 这是部分更新接口，只会修改你传入的字段。
• block 类型字段会按当前 block 的类型展开，例如 paragraph、heading_2、to_do、code。
• 传入 type 时只能用于校验，不能把一个 block 改成另一种类型。
• in_trash 和 archived 都会改变块的回收站状态；常规场景优先使用 in_trash。

错误提示

• 400 validation_error：试图修改 block 类型，或传入了不合法的内容。
• 401 unauthorized：token 无效或已过期。
• 403 forbidden：缺少 blocks.write 或无权访问该 block。
• 404 not_found：block 不存在。

相关文档

前置阅读

• 获取块

下一步

• 删除块

相关参考

• Block 类型
• 错误码