创建页面

适用场景

当你要新建普通页面，或在数据库下创建一条记录时使用这个接口。它也支持在创建时一次性写入首批 block children，减少后续追加请求。

接口信息

权限要求

需要 pages.write。

请求参数

请求头

请求头示例：

Idempotency-Key: 3f6e6cb0-5f6a-4f31-8f7a-0f4b5f7f7f1a

请求体

请求体示例：

{
  "parent": {
    "page_id": "55555555-5555-4555-8555-555555555555"
  },
  "icon": {
    "type": "emoji",
    "emoji": "📝"
  },
  "properties": {
    "title": {
      "type": "title",
      "title": [
        {
          "type": "text",
          "text": {
            "content": "发布计划"
          }
        }
      ]
    }
  },
  "children": [
    {
      "object": "block",
      "type": "paragraph",
      "paragraph": {
        "rich_text": [
          {
            "type": "text",
            "text": {
              "content": "第一版发布范围与时间安排。"
            }
          }
        ]
      }
    }
  ]
}

响应结果

{
  "object": "page",
  "id": "11111111-1111-4111-8111-111111111111",
  "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
        }
      ]
    }
  }
}

行为说明或限制

• parent 支持 page_id 和 database_id，二者互斥。
• 不传 parent 时，会在当前 token 所属工作区的根目录下创建普通页面。
• 如果你要在数据库下创建记录，请使用 parent.database_id。
• children 采用 block input 结构，字段格式与“追加块子块”接口一致。
• children 最多 100 个顶层 block，支持有限层级嵌套。
• 当请求使用同一个 Idempotency-Key 且请求体一致时，会返回相同结果。
• 当相同 Idempotency-Key 对应不同请求体时，会返回幂等冲突。

错误提示

• 400 validation_error：children 格式不正确，或在数据库父级下创建时缺少标题属性。
• 401 unauthorized：token 无效或已过期。
• 403 forbidden：缺少 pages.write 或无权访问父级。
• 404 not_found：父级不存在。
• 409 idempotency_conflict：Idempotency-Key 已被其他请求体占用。

相关文档

前置阅读

• 认证与权限
• 获取数据库

下一步

• 获取页面
• Markdown 读取

相关参考

• 页面属性模型
• Block 类型