pages.create

Creates a new page in a database, as a child of an existing page, or in a workspace.

Method Signature

notion.pages.create(args: CreatePageParameters): Promise<PageObjectResponse | PartialPageObjectResponse>

Parameters

object

required

The parent location where the page will be created. Can be a database, page, or workspace.

Show Parent Types

string

The ID of the parent database (with or without dashes)

string

The ID of the parent page (with or without dashes)

boolean

Set to true to create the page in the workspace root

object

required

Property values for the new page. The required properties depend on the parent database schema.Each property value is keyed by the property name and includes a type field.

Show Property Types

array

Array of rich text objects for title properties

array

Array of rich text objects for text properties

number

Numeric value for number properties

object

Select option with name or id

array

Array of select options

object

Date object with start and optional end and time_zone

boolean

Boolean value for checkbox properties

string

URL string

string

Email address string

string

Phone number string

array

Array of user objects with id fields

array

Array of file objects (external or uploaded)

array

Array of relation objects with id fields

object

Status option with name or id

object

Page icon. Can be an emoji, external URL, file upload, or custom emoji.

Show Icon Types

string

A single emoji character (e.g., ”📄”)

object

External file with url property

object

File upload with id property (must have status uploaded)

object

Page cover image.

Show Cover Types

object

External file with url property

object

File upload with id property (must have status uploaded)

array

Array of block objects to add as the page’s initial content. Mutually exclusive with content and markdown.

array

Array of block objects to add as the page’s initial content. Mutually exclusive with children and markdown.

string

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

object

Template to apply to the page.

Show Template Types

string

One of: none, default, template_id

string

ID of the template to use (when type is template_id)

object

Position where the page should be inserted.

Show Position Types

string

One of: after_block, page_start, page_end

object

Block reference with id (when type is after_block)

string

Bearer token for authentication. Overrides the client-level authentication.

Response

string

Always "page"

string

The ID of the newly created page

string

ISO 8601 timestamp when the page was created

string

ISO 8601 timestamp when the page was last edited

boolean

Whether the page is archived

boolean

Whether the page is in trash

boolean

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

string

The URL of the Notion page

string | null

The public URL if the page has been published to the web

object

Information about the page’s parent

object

Property values of the page

object | null

Page icon

object | null

Page cover image

object

User who created the page

object

User who last edited the page

Examples

Create a Page in a Database

const page = await notion.pages.create({
  parent: {
    database_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  },
  properties: {
    Name: {
      title: [
        {
          text: {
            content: "My New Page",
          },
        },
      ],
    },
    Status: {
      status: {
        name: "In Progress",
      },
    },
    Priority: {
      select: {
        name: "High",
      },
    },
  },
})

console.log("Created page with ID:", page.id)

Create a Page with Content

const page = await notion.pages.create({
  parent: {
    database_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  },
  properties: {
    Name: {
      title: [
        {
          text: {
            content: "Meeting Notes",
          },
        },
      ],
    },
  },
  children: [
    {
      heading_1: {
        rich_text: [
          {
            text: {
              content: "Agenda",
            },
          },
        ],
      },
    },
    {
      paragraph: {
        rich_text: [
          {
            text: {
              content: "Discuss project timeline and deliverables.",
            },
          },
        ],
      },
    },
  ],
})

Create a Page with Markdown

const page = await notion.pages.create({
  parent: {
    page_id: "b55c9c91-384d-452b-81db-d1ef79372b75",
  },
  properties: {
    title: [
      {
        text: {
          content: "Documentation",
        },
      },
    ],
  },
  markdown: `# Getting Started

Welcome to our documentation!

## Installation

\`\`\`bash
npm install @notionhq/client
\`\`\`

## Usage

Initialize the client with your API token.
`,
})

Create a Child Page

const childPage = await notion.pages.create({
  parent: {
    page_id: "b55c9c91-384d-452b-81db-d1ef79372b75",
  },
  properties: {
    title: [
      {
        text: {
          content: "Subpage Title",
        },
      },
    ],
  },
  icon: {
    emoji: "📝",
  },
})

Create a Page with Multiple Properties

const page = await notion.pages.create({
  parent: {
    database_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  },
  properties: {
    Name: {
      title: [
        {
          text: {
            content: "Project Task",
          },
        },
      ],
    },
    "Due Date": {
      date: {
        start: "2026-03-15",
        end: "2026-03-20",
      },
    },
    Assignee: {
      people: [
        {
          id: "d40e767c-d7af-4b18-a86d-55c61f1e39a4",
        },
      ],
    },
    Tags: {
      multi_select: [
        { name: "urgent" },
        { name: "feature" },
      ],
    },
    Completed: {
      checkbox: false,
    },
  },
  cover: {
    external: {
      url: "https://images.unsplash.com/photo-1484480974693-6ca0a78fb36b",
    },
  },
})

pages.retrieve - Retrieve an existing page
pages.update - Update page properties
pages.move - Move a page to a different location

Client

Blocks

Pages

Databases

Data Sources

Users

Comments

File Uploads

Search & OAuth

Helpers

Errors

Method Signature

Parameters

Response

Examples

Create a Page in a Database

Create a Page with Content

Create a Page with Markdown

Create a Child Page

Create a Page with Multiple Properties

See Also

​Method Signature

​Parameters

​Response

​Examples

​Create a Page in a Database

​Create a Page with Content

​Create a Page with Markdown

​Create a Child Page

​Create a Page with Multiple Properties

​Related Methods

​See Also

Method Signature

Parameters

Response

Examples

Create a Page in a Database

Create a Page with Content

Create a Page with Markdown

Create a Child Page

Create a Page with Multiple Properties

Related Methods

See Also