Pages

Custom blocks are in private alpha:

Do not discuss publicly or share with anyone outside your workspace.
Access must be enabled per workspace. Installing the SDK does not grant access.
These APIs may experience breaking changes without notice.

The pages API lets a block write to Notion. It works with or without React.

import { pages } from "@notionhq/custom-blocks"

Every method resolves to a discriminated union rather than throwing:

const result = await pages.get(pageId)

if (result.status === "error") {
	// result.error.code, result.error.message, result.error.isRetryable
	return
}

// result.page

Create a page

const result = await pages.create({
	parent: { type: "data_source_key", key: "issues" },
	properties: {
		title: { type: "title", title: [{ text: { content: "Fix the login bug" } }] },
		status: { type: "status", status: { name: "To do" } },
	},
})

Field	Description
`parent`	Required. Where the page goes.
`properties`	Required. Property values keyed by either a declared property key or a raw property ID.
`position`	Optional. Where the page lands relative to siblings.

Choosing a parent

pages.create() accepts these parent inputs. These inputs are separate from the NotionParent values returned in app context and page responses.

Parent input	Use when
`{ type: "data_source_key", key }`	Creating a page in a data source declared and bound by the block.
`{ type: "data_source_id", data_source_id }`	Creating a page in a specific data source.
`{ type: "page_id", page_id }`	Creating a child page under a regular page or a wiki root.

Prefer data_source_key when the block uses one of its declared data sources. This keeps the block independent of the user’s data source ID. The returned result.page.parent uses the same parent shapes as app context. See App context for the complete list of parent values.

Position

position controls where the new page is inserted:

start and end insert the page directly under the page surface.
before and after insert the page beside the anchor block.
The anchor can be nested inside a toggle, column, or another block.
If the anchor is inside a toggle or column, the new page is also inserted inside that block.
The page_id must identify a regular page or a wiki root.

icon and cover cannot be set at creation time. Create the page, then set them with pages.update().

Read a page

pages.get() returns page metadata and properties. It does not return block or Markdown content.

const result = await pages.get(pageId)

pages.get() and pages.update() accept a regular page ID or a wiki root ID. On success, result.page is a NotionPage: its id, parent, properties, and — when available — created_time, last_edited_time, icon, cover, url, public_url, and in_trash.

Read archive status

Archiving keeps content you no longer actively use without deleting it. Learn about Archive. Read is_archived on a page or data source row. It is true when the page or an ancestor is archived.

Read Trash status

Pages in Trash are scheduled for permanent deletion. By default, Notion permanently deletes them 30 days after they enter Trash, unless you restore them first. Enterprise workspaces can configure a different retention period. Learn about Trash retention. Read in_trash on a page or data source row. It is true when the page or an ancestor is in Trash.

Update a page

Unlike pages.create, properties here is keyed by raw property ID only — declared keys are not resolved for you. Map them yourself with propertyIdsByKey from useDataSource:

const statusPropertyId = propertyIdsByKey.status
if (!statusPropertyId) return

const result = await pages.update({
	pageId,
	properties: {
		[statusPropertyId]: {
			id: statusPropertyId,
			type: "status",
			status: { name: "Done" },
		},
	},
	icon: { type: "emoji", emoji: "✅" },
})

Field	Description
`pageId`	Required.
`properties`	This field is optional. Use raw property IDs as keys. Repeat each key in the value’s `id` field. The API changes only the supplied properties.
`icon`	Optional.
`cover`	Optional.
`is_archived`	Optional. Set `true` to archive, `false` to unarchive.

For a row in one of your block’s bound data sources, prefer that row’s own update method from useDataSource. It takes your declared keys and resolves them against the binding, so you avoid the ID mapping entirely.

Archive and unarchive a page

Use pages.archive(pageId) to archive a page. Use pages.unarchive(pageId) to remove its archive state.

import { pages } from "@notionhq/custom-blocks"

const result = await pages.archive(pageId)
if (result.status === "error") {
	console.error(result.error.message)
}

const restored = await pages.unarchive(pageId)
if (restored.status === "error") {
	console.error(restored.error.message)
}

pages.archive is shorthand for calling pages.update with is_archived: true. pages.unarchive is shorthand for calling pages.update with is_archived: false. Both methods return an UpdatePageResult.

Trashing and untrashing pages

This is not currently supported by the custom blocks SDK.

Property support

This table shows property support for custom blocks running in Notion.

Read value shows page.properties in responses from pages.get, pages.create, and pages.update. The table identifies top-level fields separately. Unavailable values are absent from page.properties.
Create covers property writes through pages.create.
Update covers property writes through pages.update.

Pages outside a data source support only title. Other property writes require a data source row and a property in its schema.

🟢 Supported: The SDK supports this operation in Notion.
🟡 Limited: The SDK supports this operation with the restrictions shown in the cell.
🔴 Unavailable: The SDK does not expose this operation.
⚫ Not supported in Notion: Notion itself does not support this operation in the stated case.

Property type	Read value (`pages.get`)	Create (`pages.create`)	Update (`pages.update`)
`title`	🟡 Text array with plain text only	🟡 Plain text only	🟡 Plain text only
`rich_text`	🟡 Text array with plain text only	🟡 Plain text only	🟡 Plain text only
`number`	🟢 Number or `null`	🟢 Supported	🟢 Supported
`checkbox`	🟢 Boolean	🟢 Supported	🟢 Supported
`url`	🟢 String or `null`	🟢 Supported	🟢 Supported
`email`	🟢 String or `null`	🟢 Supported	🟢 Supported
`phone_number`	🟢 String or `null`	🟢 Supported	🟢 Supported
`select`	🟡 Does not return available options	🟡 Set value only	🟡 Set value only
`multi_select`	🟡 Does not return available options	🟡 Set value only	🟡 Set value only
`status`	🟡 Does not return available options	🟡 Set value only	🟡 Set value only
`date`	🟢 `start` and optional `end` strings, or `null`	🟡 Minute precision	🟡 Minute precision
`people`	🟢 Array of user/group ID objects	🟢 Supported	🟢 Supported
`files`	🟡 External file links only	🟡 File URLs only	🟡 File URLs only
`unique_id`	🔴 Unavailable	🔴 Unavailable	🔴 Unavailable
`relation`	🟢 Array of page ID objects	🟡 Replaces value. Rejects `has_more: true`.	🟡 Replaces value. Rejects `has_more: true`.
`place`	🟢 Coordinates and optional place details, or `null`	🟢 Supported	🟢 Supported
`formula`	🔴 Unavailable	🔴 Unavailable	🔴 Unavailable
`rollup`	🔴 Unavailable	🔴 Unavailable	🔴 Unavailable
`button`	🔴 Unavailable	🔴 Unavailable	🔴 Unavailable
`verification`	🔴 Unavailable	🔴 Unavailable	🔴 Unavailable
`last_visited_time`	🔴 Unavailable	🔴 Unavailable	🔴 Unavailable
`location`	🔴 Unavailable	🔴 Unavailable	🔴 Unavailable
`created_time`	🟡 Top-level ISO timestamp only	🔴 Unavailable	🔴 Unavailable
`last_edited_time`	🟡 Top-level ISO timestamp only	🔴 Unavailable	🔴 Unavailable
`created_by`	🔴 Unavailable	🔴 Unavailable	🔴 Unavailable
`last_edited_by`	🔴 Unavailable	🔴 Unavailable	🔴 Unavailable

Notes

Select, multi-select, and status reads return option names and colors. They also return IDs when the options match the schema. Writes accept an existing option ID or a name and set the selected value. They do not edit option definitions. If you supply both an ID and a name, the host uses the ID. The host rejects unknown IDs.
Date-time writes preserve hours and minutes but discard seconds and milliseconds.
Title and rich text use text arrays, but reads and writes preserve only plain text. Reads and writes do not preserve formatting, links, mentions, or equations as structured rich text.
File reads include link items only. File writes accept external URLs and existing file URLs and store them as links. Upload references (file_upload) are unsupported.
Relation writes replace the value and reject has_more: true.
created_time and last_edited_time are read-only top-level fields on page, when available. The host omits them from page.properties. The host does not return created_by or last_edited_by, even as top-level fields. The host does not return structured page values for formula, rollup, unique ID, or the other omitted types.

For flattened query values, filters, and sorts, see Data source property support.

Permissions

A block acts within what the viewing user can already see and edit. A write the user could not perform themselves fails with an access error rather than succeeding with elevated permissions, so treat every result as something that can legitimately fail per user.

Get started

Guides

Workers SDK reference

Custom blocks SDK reference

CLI reference

Create a page

Choosing a parent

Position

Read a page

Read archive status

Read Trash status

Update a page

Archive and unarchive a page

Trashing and untrashing pages

Property support

Notes

Permissions

​Create a page

​Choosing a parent

​Position

​Read a page

​Read archive status

​Read Trash status

​Update a page

​Archive and unarchive a page

​Trashing and untrashing pages

​Property support

​Notes

​Permissions

Create a page

Choosing a parent

Position

Read a page

Read archive status

Read Trash status

Update a page

Archive and unarchive a page

Trashing and untrashing pages

Property support

Notes

Permissions