pages.move

Move a page to a different parent location

Moves a page to a new parent location. The page can be moved to a different page (making it a child page) or to a different data source (database).

Method Signature

notion.pages.move(args: MovePageParameters): Promise<PageObjectResponse | PartialPageObjectResponse>

Parameters

page_id · string · required

The ID of the page to move (with or without dashes).

parent · object · required

The new parent location for the page.

Show Parent Types

page_id · string

The ID of the parent page (with or without dashes). The page will become a child of this page.

Example: "195de9221179449fab8075a27c979105"

data_source_id · string

The ID of the parent data source (collection), with or without dashes. The page will be moved into this database.

Example: "f336d0bc-b841-465b-8045-024475c079dd"

auth · string

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

Response

object · string

Always "page"

id · string

The ID of the moved 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 (updated after the move)

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

url · string

The URL of the Notion page (may change after move)

public_url · string | null

The public URL if published to the web

parent · object

Information about the page’s new parent location

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

Move Page to Another Page

Move a page to become a child of another page:

const page = await notion.pages.move({
  page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  parent: {
    page_id: "b55c9c91-384d-452b-81db-d1ef79372b75",
  },
})

console.log("Page moved successfully")
console.log("New parent:", page.parent)

Move Page to a Data Source

Move a page into a database (data source):

const page = await notion.pages.move({
  page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  parent: {
    data_source_id: "f336d0bc-b841-465b-8045-024475c079dd",
  },
})

console.log("Page moved to data source")

Move with Type Guard

import { isFullPage } from "@notionhq/client"

const response = await notion.pages.move({
  page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  parent: {
    page_id: "b55c9c91-384d-452b-81db-d1ef79372b75",
  },
})

if (isFullPage(response)) {
  console.log("New URL:", response.url)
  console.log("Parent type:", response.parent.type)
  
  if (response.parent.type === "page_id") {
    console.log("Parent page ID:", response.parent.page_id)
  } else if (response.parent.type === "data_source_id") {
    console.log("Parent data source:", response.parent.data_source_id)
  }
}

Organize Pages into Sections

// Move multiple pages under a section page
const sectionPageId = "b55c9c91-384d-452b-81db-d1ef79372b75"

const pageIdsToMove = [
  "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  "c66d0c02-495e-563c-92ec-e80f8496c186",
  "d77e1d13-506f-674d-03fd-f91f9507d297",
]

for (const pageId of pageIdsToMove) {
  await notion.pages.move({
    page_id: pageId,
    parent: {
      page_id: sectionPageId,
    },
  })
  console.log(`Moved page ${pageId} to section`)
}

Move Page from Database to Page

// Extract a database item and convert it to a standalone page
const page = await notion.pages.move({
  page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  parent: {
    page_id: "b55c9c91-384d-452b-81db-d1ef79372b75",
  },
})

console.log("Converted database item to child page")

Error Handling

import { APIResponseError, APIErrorCode } from "@notionhq/client"

try {
  const page = await notion.pages.move({
    page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
    parent: {
      page_id: "invalid-parent-id",
    },
  })
} catch (error) {
  if (APIResponseError.isAPIResponseError(error)) {
    if (error.code === APIErrorCode.ObjectNotFound) {
      console.error("Page or parent not found")
    } else if (error.code === APIErrorCode.ValidationError) {
      console.error("Invalid parent or insufficient permissions")
    } else {
      console.error("API error:", error.message)
    }
  } else {
    console.error("Unexpected error:", error)
  }
}

Conditional Move Based on Property

import { isFullPage } from "@notionhq/client"

// Retrieve the page first
const page = await notion.pages.retrieve({
  page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
})

if (isFullPage(page)) {
  const statusProp = page.properties.Status
  
  if (statusProp.type === "select" && statusProp.select?.name === "Done") {
    // Move completed items to archive page
    await notion.pages.move({
      page_id: page.id,
      parent: {
        page_id: "archive-page-id",
      },
    })
    console.log("Moved completed page to archive")
  }
}

Important Notes

When moving a page from one database to another, ensure the target database has compatible properties. The page will retain its property values, but incompatible properties may be lost.

Moving a page updates its last_edited_time and last_edited_by fields. The page URL may also change after the move.

You need appropriate permissions to move a page. The integration must have access to both the page being moved and the destination parent.

Use Cases

• Organize content: Move pages into different sections or categories
• Archive completed items: Move finished tasks to an archive page
• Restructure hierarchy: Reorganize your workspace structure
• Promote database items: Convert database entries to standalone pages
• Migrate data: Move pages between databases

Related Methods

• pages.retrieve - Retrieve a page before moving
• pages.update - Update page properties after moving
• pages.create - Create a new page in a specific location

See Also

• Notion API: Move a page
• Understanding page hierarchy