pages.create

Create a new page in Notion

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

parent · object · required

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

Show Parent Types

database_id · string

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

page_id · string

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

workspace · boolean

Set to true to create the page in the workspace root

properties · 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

title · array

Array of rich text objects for title properties

rich_text · array

Array of rich text objects for text properties

number · number

Numeric value for number properties

select · object

Select option with name or id

multi_select · array

Array of select options

date · object

Date object with start and optional end and time_zone

checkbox · boolean

Boolean value for checkbox properties

url · string

URL string

email · string

Email address string

phone_number · string

Phone number string

people · array

Array of user objects with id fields

files · array

Array of file objects (external or uploaded)

relation · array

Array of relation objects with id fields

status · object

Status option with name or id

icon · object

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

Show Icon Types

emoji · string

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

external · object

External file with url property

file_upload · object

File upload with id property (must have status uploaded)

cover · object

Page cover image.

Show Cover Types

external · object

External file with url property

file_upload · object

File upload with id property (must have status uploaded)

children · array

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

content · array

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

markdown · string

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

template · object

Template to apply to the page.

Show Template Types

type · string

One of: none, default, template_id

template_id · string

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

position · object

Position where the page should be inserted.

Show Position Types

type · string

One of: after_block, page_start, page_end

after_block · object

Block reference with id (when type is after_block)

auth · string

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

Response

object · string

Always "page"

id · string

The ID of the newly created page

created_time · string

ISO 8601 timestamp when the page was created

last_edited_time · string

ISO 8601 timestamp when the page was last edited

archived · boolean

Whether the page is archived

in_trash · boolean

Whether the page is in trash

is_locked · boolean

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

url · string

The URL of the Notion page

public_url · string | null

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

parent · object

Information about the page’s parent

properties · object

Property values of the page

icon · object | null

Page icon

cover · object | null

Page cover image

created_by · object

User who created the page

last_edited_by · 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",
    },
  },
})

Related Methods

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

See Also

• Notion API: Create a page
• Working with page properties