Skip to main content
POST
/
v1
/
pages
TypeScript SDK
import { Client } from "@notionhq/client"

const notion = new Client({ auth: process.env.NOTION_API_KEY })

const response = await notion.pages.create({
  parent: {
    data_source_id: "d9824bdc-8445-4327-be8b-5b47500af6ce"
  },
  properties: {
    Name: {
      title: [{ text: { content: "New Page Title" } }]
    }
  }
})
{
  "object": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_time": "2023-11-07T05:31:56Z",
  "last_edited_time": "2023-11-07T05:31:56Z",
  "in_trash": true,
  "is_archived": true,
  "is_locked": true,
  "url": "<string>",
  "public_url": "<string>",
  "parent": {
    "type": "<string>",
    "database_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "properties": {},
  "icon": {
    "type": "<string>",
    "emoji": "<string>"
  },
  "cover": {
    "type": "<string>",
    "file": {
      "url": "<string>",
      "expiry_time": "2023-11-07T05:31:56Z"
    }
  },
  "created_by": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "object": "<string>"
  },
  "last_edited_by": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "object": "<string>"
  }
}

Documentation Index

Fetch the complete documentation index at: https://developers.notion.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Use cases

​
Choosing a parent

In most cases, provide a page_id or data_source under the parent parameter to create a page under an existing page, or data source, respectively. There is a 3rd option, available for public connections and personal access tokens: creating a private page at the workspace level. To do this, omit the parent parameter, or provide parent[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 connections, 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 existing data 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 the children option. To add content to a page after creating it, use the Append block children endpoint. Templates: As an alternative to building up page content manually, the template 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 is template[type]=none, which means no template is applied. The other options for template[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 specific template_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 the template[template_id], we recommend only using pages that are configured as actual database 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 using default or template_id, you can optionally provide template[timezone] — an IANA timezone string (e.g. America/New_York) — to control the timezone used when resolving template variables like @now and @today. If omitted, the associated user’s timezone is used for public connections and personal access tokens, or UTC for internal connections. An invalid timezone returns a validation_error. When applying a template, the children parameter is not 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 on creating pages from templates.

​
General behavior

Returns a new page object.
Newlines in markdown contentWhen using the markdown body parameter, newlines must be encoded as \n in the JSON string — for example, "# Heading\n\nParagraph". The interactive API explorer on this page does not support multiline input, so use cURL, an SDK, or any HTTP client that sends properly encoded JSON. When using cURL, wrap the --data body in single quotes ('...') so that \n is preserved for the JSON parser.
Some page properties are not supported via the APIA request body that includes rollup, created_by, created_time, last_edited_by, or last_edited_time values in the properties object returns an error. These Notion-generated values cannot be created or updated via the API. If the parent contains any of these properties, then the new page’s corresponding values are automatically created.
RequirementsYour connection must have Insert Content capabilities on the target parent page or database in order to call this endpoint. To update your connection’s capabilities, navigate to the Developer portal, select your connection, open the Configuration tab, and scroll to the Capabilities section.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 the Error codes section of the Status codes documentation for more information.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
Notion-Version
enum<string>
required

The API version to use for this request. The latest version is 2026-03-11.

Available options:
2026-03-11

Body

application/json
​
parent
Page Id · object
​
properties
object
​
icon
File Upload · object
​
cover
File Upload · object
​
content
(Embed · object | Bookmark · object | Image · object | Video · object | Pdf · object | File · object | Audio · object | Code · object | Equation · object | Divider · object | Breadcrumb · object | Tab · object | Table Of Contents · object | Link To Page · object | Table Row · object | Table · object | Column List · object | Column · object | Heading 1 · object | Heading 2 · object | Heading 3 · object | Heading 4 · object | Paragraph · object | Bulleted List Item · object | Numbered List Item · object | Quote · object | To Do · object | Toggle · object | Template · object | Callout · object | Synced Block · object)[]
Maximum array length: 100
​
children
(Embed · object | Bookmark · object | Image · object | Video · object | Pdf · object | File · object | Audio · object | Code · object | Equation · object | Divider · object | Breadcrumb · object | Tab · object | Table Of Contents · object | Link To Page · object | Table Row · object | Table · object | Column List · object | Column · object | Heading 1 · object | Heading 2 · object | Heading 3 · object | Heading 4 · object | Paragraph · object | Bulleted List Item · object | Numbered List Item · object | Quote · object | To Do · object | Toggle · object | Template · object | Callout · object | Synced Block · object)[]
Maximum array length: 100
​
markdown
string

Page content as Notion-flavored Markdown. Mutually exclusive with content/children.

​
template
object
​
position
object

Response

​
object
string
required

The page object type name.

Allowed value: "page"
​
id
string<uuid>
required

The ID of the page.

​
created_time
string<date-time>
required

Date and time when this page was created.

​
last_edited_time
string<date-time>
required

Date and time when this page was last edited.

​
in_trash
boolean
required

Whether the page is in trash.

​
is_archived
boolean
required

Whether the page has been archived.

​
is_locked
boolean
required

Whether the page is locked from editing in the Notion app UI.

​
url
string
required

The URL of the Notion page.

​
public_url
string | null
required

The public URL of the Notion page, if it has been published to the web.

​
parent
object
required

Information about the page's parent.

​
properties
object
required

Property values of this page.

​
icon
Emoji · object
required

Page icon.

​
cover
File · object
required

Page cover image.

​
created_by
object
required

User who created the page.

​
last_edited_by
object
required

User who last edited the page.