Create a page | Notion

curl 'https://api.notion.com/v1/pages' \
  -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2022-06-28" \
  --data '{
  "parent": {
    "data_source_id": "d9824bdc84454327be8b5b47500af6ce"
  },
  "icon": {
    "emoji": "🥬"
  },
  "cover": {
    "external": {
      "url": "https://upload.wikimedia.org/wikipedia/commons/6/62/Tuscankale.jpg"
    }
  },
  "properties": {
    "Name": {
      "title": [
        {
          "text": {
            "content": "Tuscan Kale"
          }
        }
      ]
    },
    "Description": {
      "rich_text": [
        {
          "text": {
            "content": "A dark green leafy vegetable"
          }
        }
      ]
    },
    "Food group": {
      "select": {
        "name": "Vegetable"
      }
    },
    "Price": { "number": 2.5 }
  },
  "children": [
    {
      "object": "block",
      "type": "heading_2",
      "heading_2": {
        "rich_text": [{ "type": "text", "text": { "content": "Lacinato kale" } }]
      }
    },
    {
      "object": "block",
      "type": "paragraph",
      "paragraph": {
        "rich_text": [
          {
            "type": "text",
            "text": {
              "content": "Lacinato kale is a variety of kale with a long tradition in Italian cuisine, especially that of Tuscany. It is also known as Tuscan kale, Italian kale, dinosaur kale, kale, flat back kale, palm tree kale, or black Tuscan palm.",
              "link": { "url": "https://en.wikipedia.org/wiki/Lacinato_kale" }
            }
          }
        ]
      }
    }
  ]
}'

{
  "Result": {
    "value": "{\n  \"object\": \"page\",\n  \"id\": \"59833787-2cf9-4fdf-8782-e53db20768a5\",\n  \"created_time\": \"2022-03-01T19:05:00.000Z\",\n  \"last_edited_time\": \"2022-07-06T19:16:00.000Z\",\n  \"created_by\": {\n    \"object\": \"user\",\n    \"id\": \"ee5f0f84-409a-440f-983a-a5315961c6e4\"\n  },\n  \"last_edited_by\": {\n    \"object\": \"user\",\n    \"id\": \"ee5f0f84-409a-440f-983a-a5315961c6e4\"\n  },\n  \"cover\": {\n    \"type\": \"external\",\n    \"external\": {\n      \"url\": \"https://upload.wikimedia.org/wikipedia/commons/6/62/Tuscankale.jpg\"\n    }\n  },\n  \"icon\": {\n    \"type\": \"emoji\",\n    \"emoji\": \"🥬\"\n  },\n  \"parent\": {\n    \"type\": \"data_source_id\",\n    \"data_source_id\": \"d9824bdc-8445-4327-be8b-5b47500af6ce\",\n    \"database_id\": \"9ce034a5-74ca-4259-8b01-8494453204fe\"\n  },\n  \"archived\": false,\n  \"properties\": {\n    \"Store availability\": {\n      \"id\": \"%3AUPp\"\n    },\n    \"Food group\": {\n      \"id\": \"A%40Hk\"\n    },\n    \"Price\": {\n      \"id\": \"BJXS\"\n    },\n    \"Responsible Person\": {\n      \"id\": \"Iowm\"\n    },\n    \"Last ordered\": {\n      \"id\": \"Jsfb\"\n    },\n    \"Cost of next trip\": {\n      \"id\": \"WOd%3B\"\n    },\n    \"Recipes\": {\n      \"id\": \"YfIu\"\n    },\n    \"Description\": {\n      \"id\": \"_Tc_\"\n    },\n    \"In stock\": {\n      \"id\": \"%60%5Bq%3F\"\n    },\n    \"Number of meals\": {\n      \"id\": \"zag~\"\n    },\n    \"Photo\": {\n      \"id\": \"%7DF_L\"\n    },\n    \"Name\": {\n      \"id\": \"title\"\n    }\n  },\n  \"url\": \"https://www.notion.so/Tuscan-Kale-598337872cf94fdf8782e53db20768a5\"\n}"
  }
}

Creates a new page that is a child of an existing page or data source.

If the new page is a child of an existing page,title is the only valid property in the properties body param.

If the new page is a child of an existing database, the keys of the properties object body param must match the parent data source’s properties.

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.

Returns a new page object.

Some page properties are not supported via the API.

A 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.

Requirements

Your integration must have Insert Content capabilities on the target parent page or database in order to call this endpoint. To update your integrations capabilities, navigation to the My integrations dashboard, select your integration, go to the Capabilities tab, and update your settings as needed.

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.

Request

This endpoint expects an object.

parentstringRequiredformat: "json"

The parent page or data source where the new page is inserted, represented as a JSON object with a page_id or data_source_id key, and the corresponding ID.

propertiesstringRequiredformat: "json"

The values of the page’s properties. If the parent is a database, then the schema must match the parent database’s properties. If the parent is a page, then the only valid object key is title.

childrenlist of stringsOptional

The content to be rendered on the new page, represented as an array of block objects.

iconstringOptionalformat: "json"

The icon of the new page. Either an emoji object or an external file object..

coverstringOptionalformat: "json"

The cover image of the new page, represented as a file object.

Response

200

objectstringOptional

idstringOptional

created_timestringOptional

last_edited_timestringOptional

created_byobjectOptional

last_edited_byobjectOptional

coverobjectOptional

iconobjectOptional

parentobjectOptional

archivedbooleanOptionalDefaults to true

propertiesobjectOptional

urlstringOptional

Errors

400

Bad Request Error

404

Not Found Error

429

Too Many Requests Error

Errors

Headers

Request

Response

Errors