V2
Create Page
Create a page or database record, optionally with initial child blocks.
Create Page
Use Case
Use this endpoint to create a normal page or a database record. You can also include the first batch of child blocks to reduce follow-up requests.
Endpoint
| Item | Value |
|---|---|
| Method | POST |
| Path | /v2/pages |
| Request body | page create parameters |
| Returns | page |
| Scope | pages.write |
Permissions
Requires pages.write and write access to the parent when one is provided.
Headers
| Header | Required | Description |
|---|---|---|
Authorization |
Yes | Bearer <token>. |
Idempotency-Key |
No | Idempotency key. Reusing the same key with the same body returns the same result. |
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
parent |
object | No | Parent object. Use exactly one of page_id or database_id; omit it to create the page in the current workspace root. |
icon |
object or null | No | Page icon. |
cover |
object or null | No | Page cover. |
properties |
object | No | Page properties. Records under a database usually need a title property. |
children |
block input[] | No | Initial child blocks, using the same shape as append block children. |
Request Example
{
"parent": {
"page_id": "55555555-5555-4555-8555-555555555555"
},
"properties": {
"title": {
"type": "title",
"title": [
{
"type": "text",
"text": {
"content": "Launch Plan"
}
}
]
}
},
"children": [
{
"object": "block",
"type": "paragraph",
"paragraph": {
"rich_text": [
{
"type": "text",
"text": {
"content": "Initial release scope and schedule."
}
}
]
}
}
]
}
Response Example
{
"object": "page",
"id": "11111111-1111-4111-8111-111111111111",
"page_type": "page",
"created_time": "2026-04-09T08:00:00.000Z",
"last_edited_time": "2026-04-09T09:30:00.000Z",
"created_by": {
"object": "user",
"id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"
},
"last_edited_by": {
"object": "user",
"id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"
},
"parent": {
"type": "page_id",
"page_id": "55555555-5555-4555-8555-555555555555"
},
"in_trash": false,
"icon": null,
"cover": null,
"properties": {
"title": {
"id": "title",
"type": "title",
"title": [
{
"type": "text",
"text": {
"content": "Launch Plan",
"link": null
},
"plain_text": "Launch Plan",
"href": null
}
]
}
},
"url": "https://buildin.ai/docs/11111111-1111-4111-8111-111111111111"
}
Behavior
parent.page_idandparent.database_idare mutually exclusive.- If
parentis omitted, the page is created in the current token workspace root. - Use
parent.database_idto create a database record. childrenaccepts block input objects and is limited to 100 top-level blocks.- A reused
Idempotency-Keywith a different body returns an idempotency conflict.
Errors
400 validation_error: invalid body, invalid children, or missing required record title.401 unauthorized: invalid or expired token.403 forbidden: missingpages.writeor no access to the parent.404 not_found: parent does not exist.409 idempotency_conflict: key is already associated with a different body.