Use cases

Choosing a parent

In most cases, provide apage_id ordata_source under theparent parameter to create a page under an existingpage, ordata source, respectively.

There is a 3rd option, available only for bots ofpublic integrations: creating a private page at the workspace level. To do this, omit theparent parameter, or provideparent[workspace]=true. This can be useful for quickly creating pages that can then be organized manually in the Notion app later, helping you get to your life's work faster.

For internal integrations, a page or data source parent is currently required in the API, because there is no one specific Notion user associated with them that could be used as the "owner" of the new private page.

Setting up page properties

If the new page is a child of an existing page,title is the only valid property in the properties body parameter.

If the new page is a child of an existingdata source, the keys of the properties object body param must match the parent data source's properties.

Setting up page content

This endpoint can be used to create a new page with or without content using thechildren option. To add content to a page after creating it, use theAppend block children endpoint.

Templates: As an alternative to building up page content manually, thetemplate body parameter can be used to specify an existing data source template to be used to populate the content and properties of the new page.

When omitted, the default istemplate[type]=none, which means no template is applied. The other options fortemplate[type] are:

• default: Apply the data source's default template.
  • This is only allowed for pages created under a data source that has a default template configured in the Notion app.
• template_id: Provide a specifictemplate_id to use as the blueprint for your page.
  • The API bot must have access to the template page, and it must be within the same workspace.
  • Although any valid page ID can be used as thetemplate[template_id], we recommend only using pages that are configured as actualdatabase templates under the same data source as the parent of your new page to make sure that page properties can get merged in correctly.

When applying a template, thechildren parameter isnot allowed. The page is returned as blank initially in the API response, and then Notion's systems apply the template asynchronously after the API request finishes. For more information, see our full guide oncreating pages from templates.

General behavior

Returns a newpage object.

🚧

Some pageproperties are not supported via the API.

A request body that includesrollup,created_by,created_time,last_edited_by, orlast_edited_time values in the properties object returns an error. These Notion-generated values cannot be created or updated via the API. If theparent contains any of these properties, then the new page’s corresponding values are automatically created.

📘

Requirements

Your integration must haveInsert Content capabilities on the target parent page or database in order to call this endpoint. To update your integrations capabilities, navigation to theMy integrations dashboard, select your integration, go to theCapabilities tab, and update your settings as needed.

Attempting a query without update content capabilities returns an HTTP response with a 403 status code.

Errors

Each Public API endpoint can return several possible error codes. See theError codes section of the Status codes documentation for more information.