Pages

Create a page

Changed on
post/v1/pages

Request

  • Base URL
    https://api.notion.com
  • URL
    https://api.notion.com/v1/pages
  • Auth
    HTTP bearer

Query parameters

filter_propertiesstring[]

Property names or IDs to include in each page's properties object. Other properties are left out. Repeat the parameter to pass more than one value, for example filter_properties=title&filter_properties=Status. Pages that aren't in a data source always return only title.

Headers

Notion-Version'2026-03-11' required

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

Request body

propertiesobject
markdownstring

Page content as Markdown, in the syntax set by markdown_version: enhanced markdown (v1, the default) or Notion-flavored Markdown (v2). Mutually exclusive with content/children.

allow_asyncboolean

Set to true to receive an async_task response for markdown page creation. Only supported when markdown is provided.

markdown_version'v1' | 'v2'

The Markdown syntax to use. v1 (the default) is enhanced markdown. v2 is Notion-flavored Markdown, an opt-in preview.

Example request

{
  "icon": {
    "emoji": "😀"
  },
  "content": [
    {
      "embed": {
        "caption": [
          {
            "text": {
              "link": {
                "url": "https://www.notion.com"
              }
            }
          }
        ]
      }
    }
  ],
  "children": [
    {
      "embed": {
        "caption": [
          {
            "text": {
              "link": {
                "url": "https://www.notion.com"
              }
            }
          }
        ]
      }
    }
  ],
  "template": {
    "timezone": "America/New_York"
  }
}

Response

OR

Example response

{
  "icon": {
    "emoji": "😀"
  }
}

Changes

  • ed50532d1d7eRevision changes
    • info

      added the new optional request property

    • info

      added the new optional request property

  • c90a4587bc95Revision changes
    • warning

      added the new idempotency_key_reused enum value to the / response property for the response status