> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://notion.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://notion.ferndocs.com/_mcp/server.

# Create a page

POST https://api.notion.com/v1/pages
Content-Type: application/json

Creates a new [page](/reference/page) that is a child of an existing page or [data source](/reference/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](/reference/property-object).

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](https://developers.notion.com/reference/patch-block-children) endpoint.

Returns a new [page object](https://developers.notion.com/reference/page).

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.

Your integration must have [Insert Content capabilities](https://developers.notion.com/reference/capabilities#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](https://www.notion.so/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](https://developers.notion.com/reference/status-codes#error-codes) of the Status codes documentation for more information.

Reference: https://notion.ferndocs.com/reference/post-page

## Request

### Headers

- `Notion-Version` (string, required) — The [API version](/reference/versioning) to use for this request. The latest version is `<<latestNotionVersion>>`.

### Body (application/json)

This endpoint expects an object.

- `parent` (string, required) — 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.
- `properties` (string, required) — 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`.
- `children` (list of string, optional) — The content to be rendered on the new page, represented as an array of [block objects](https://developers.notion.com/reference/block).
- `icon` (string, optional) — The icon of the new page. Either an [emoji object](https://developers.notion.com/reference/emoji-object) or an [external file object](https://developers.notion.com/reference/file-object)..
- `cover` (string, optional) — The cover image of the new page, represented as a [file object](https://developers.notion.com/reference/file-object).

## Response

### 200

200

- `object` (string, optional)
- `id` (string, optional)
- `created_time` (string, optional)
- `last_edited_time` (string, optional)
- `created_by` (V1PagesPostResponsesContentApplicationJsonSchemaCreatedBy, optional)
- `last_edited_by` (V1PagesPostResponsesContentApplicationJsonSchemaLastEditedBy, optional)
- `cover` (V1PagesPostResponsesContentApplicationJsonSchemaCover, optional)
- `icon` (V1PagesPostResponsesContentApplicationJsonSchemaIcon, optional)
- `parent` (V1PagesPostResponsesContentApplicationJsonSchemaParent, optional)
- `archived` (boolean, optional, default: true)
- `properties` (V1PagesPostResponsesContentApplicationJsonSchema, optional)
- `url` (string, optional)

## Errors

### 400 Bad Request Error

400

### 404 Not Found Error

404

- `object` (string, optional)
- `status` (integer, optional, default: 0)
- `code` (string, optional)
- `message` (string, optional)

### 429 Too Many Requests Error

429

- `object` (string, optional)
- `status` (integer, optional, default: 0)
- `code` (string, optional)
- `message` (string, optional)

## Types

### V1PagesPostResponsesContentApplicationJsonSchemaCreatedBy

- `object` (string, optional)
- `id` (string, optional)

### V1PagesPostResponsesContentApplicationJsonSchemaLastEditedBy

- `object` (string, optional)
- `id` (string, optional)

### V1PagesPostResponsesContentApplicationJsonSchemaCover

- `type` (string, optional)
- `external` (V1PagesPostResponsesContentApplicationJsonSchemaCoverExternal, optional)

### V1PagesPostResponsesContentApplicationJsonSchemaIcon

- `type` (string, optional)
- `emoji` (string, optional)

### V1PagesPostResponsesContentApplicationJsonSchemaParent

- `type` (string, optional)
- `data_source_id` (string, optional)
- `database_id` (string, optional)

### V1PagesPostResponsesContentApplicationJsonSchema

- `Store availability` (V1PagesPostResponsesContentApplicationJsonSchemaStoreAvailability, optional)
- `Food group` (V1PagesPostResponsesContentApplicationJsonSchemaFoodGroup, optional)
- `Price` (V1PagesPostResponsesContentApplicationJsonSchemaPrice, optional)
- `Responsible Person` (V1PagesPostResponsesContentApplicationJsonSchemaResponsiblePerson, optional)
- `Last ordered` (V1PagesPostResponsesContentApplicationJsonSchemaLastOrdered, optional)
- `Cost of next trip` (V1PagesPostResponsesContentApplicationJsonSchemaCostOfNextTrip, optional)
- `Recipes` (V1PagesPostResponsesContentApplicationJsonSchemaRecipes, optional)
- `Description` (V1PagesPostResponsesContentApplicationJsonSchemaDescription, optional)
- `In stock` (V1PagesPostResponsesContentApplicationJsonSchemaInStock, optional)
- `Number of meals` (V1PagesPostResponsesContentApplicationJsonSchemaNumberOfMeals, optional)
- `Photo` (V1PagesPostResponsesContentApplicationJsonSchemaPhoto, optional)
- `Name` (V1PagesPostResponsesContentApplicationJsonSchemaName, optional)

### V1PagesPostResponsesContentApplicationJsonSchemaCoverExternal

- `url` (string, optional)

### V1PagesPostResponsesContentApplicationJsonSchemaStoreAvailability

- `id` (string, optional)

### V1PagesPostResponsesContentApplicationJsonSchemaFoodGroup

- `id` (string, optional)

### V1PagesPostResponsesContentApplicationJsonSchemaPrice

- `id` (string, optional)

### V1PagesPostResponsesContentApplicationJsonSchemaResponsiblePerson

- `id` (string, optional)

### V1PagesPostResponsesContentApplicationJsonSchemaLastOrdered

- `id` (string, optional)

### V1PagesPostResponsesContentApplicationJsonSchemaCostOfNextTrip

- `id` (string, optional)

### V1PagesPostResponsesContentApplicationJsonSchemaRecipes

- `id` (string, optional)

### V1PagesPostResponsesContentApplicationJsonSchemaDescription

- `id` (string, optional)

### V1PagesPostResponsesContentApplicationJsonSchemaInStock

- `id` (string, optional)

### V1PagesPostResponsesContentApplicationJsonSchemaNumberOfMeals

- `id` (string, optional)

### V1PagesPostResponsesContentApplicationJsonSchemaPhoto

- `id` (string, optional)

### V1PagesPostResponsesContentApplicationJsonSchemaName

- `id` (string, optional)

## Examples

**Request**

```json
{
  "parent": "string",
  "properties": "string"
}
```

**Response**

```json
{
  "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}"
  }
}
```

**SDK Code**

```javascript Notion SDK for JavaScript
const { Client } = require('@notionhq/client');

const notion = new Client({ auth: process.env.NOTION_API_KEY });

(async () => {
  const response = await notion.pages.create({
    cover: {
      type: "external",
      external: {
        url: "https://upload.wikimedia.org/wikipedia/commons/6/62/Tuscankale.jpg"
      }
    },
    icon: {
      type: "emoji",
      emoji: "🥬"
    },
    parent: {
      type: "data_source_id",
      data_source_id: "d9824bdc-8445-4327-be8b-5b47500af6ce"
    },
    properties: {
      Name: {
        title: [
          {
            text: {
              content: "Tuscan kale"
            }
          }
        ]
      },
      Description: {
        rich_text: [
          {
            text: {
              content: "A dark green leafy vegetable"
            }
          }
        ]
      },
      "Food group": {
        select: {
          name: "🥬 Vegetable"
        }
      }
    },
    children: [
      {
        object: "block",
        heading_2: {
          rich_text: [
            {
              text: {
                content: "Lacinato kale"
              }
            }
          ]
        }
      },
      {
        object: "block",
        paragraph: {
          rich_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"
                }
              },
              href: "https://en.wikipedia.org/wiki/Lacinato_kale"
            }
          ],
          color: "default"
        }
      }
    ]
  });

  console.log(response);
})();
```

```python
import requests

url = "https://api.notion.com/v1/pages"

payload = {
    "parent": "string",
    "properties": "string"
}
headers = {
    "Notion-Version": "Notion-Version",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.notion.com/v1/pages"

	payload := strings.NewReader("{\n  \"parent\": \"string\",\n  \"properties\": \"string\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Notion-Version", "Notion-Version")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.notion.com/v1/pages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Notion-Version"] = 'Notion-Version'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"parent\": \"string\",\n  \"properties\": \"string\"\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.notion.com/v1/pages")
  .header("Notion-Version", "Notion-Version")
  .header("Content-Type", "application/json")
  .body("{\n  \"parent\": \"string\",\n  \"properties\": \"string\"\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.notion.com/v1/pages', [
  'body' => '{
  "parent": "string",
  "properties": "string"
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'Notion-Version' => 'Notion-Version',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.notion.com/v1/pages");
var request = new RestRequest(Method.POST);
request.AddHeader("Notion-Version", "Notion-Version");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"parent\": \"string\",\n  \"properties\": \"string\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Notion-Version": "Notion-Version",
  "Content-Type": "application/json"
]
let parameters = [
  "parent": "string",
  "properties": "string"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.notion.com/v1/pages")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```