API quickstart

Create a page in your Notion workspace with a personal access token and a single API request.

You need a Notion account and a terminal.

Step 1: Get a personal access token

A personal access token (PAT) lets you authenticate API requests as yourself without setting up a connection or completing an OAuth flow.

1. Open Personal access tokens in the Developer portal.

2. Select New token.

3. Enter a name, select the Notion API capability, and then select Create token. If a workspace picker appears, select a workspace first.

4. Copy the token and save it somewhere secure. You won’t be able to see it again.

Don’t see the option to create a token?

On Business and Enterprise plans, PAT creation is restricted by default. Ask a workspace owner to enable it in Settings → Connections.

See Who can create PATs.

Set the token as an environment variable so you can use it in the examples below. This lasts for your current terminal session — run it again if you open a new window.

macOS / Linux

export NOTION_API_KEY=ntn_***

Step 2: Create a page

Make a POST request to the Create a page endpoint with markdown content. The API creates a private page in your workspace, using the # heading as the page title automatically.

curl

curl -X POST https://api.notion.com/v1/pages \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  -d '{
    "icon": { "emoji": "🚀" },
    "markdown": "# Hello from the API\n\n## Welcome\n\nThis page was created with the Notion API. You just made your first request!\n\n- Read the [API reference](https://developers.notion.com/reference/intro)\n- Explore [examples](https://developers.notion.com/page/examples)"
  }'

The markdown field accepts Notion-flavored Markdown — headings, lists, code blocks, links, and more. The API converts it to Notion blocks for you.

Under the hood: markdown → blocks

Notion pages are made up of blocks — headings, paragraphs, lists, and more. When you send markdown, the API converts it into this block structure automatically.

You can also build this structure directly using the children field. Here’s what the same page looks like expressed as blocks:

{
  "icon": { "emoji": "🚀" },
  "properties": {
    "title": [{ "text": { "content": "Hello from the API" } }]
  },
  "children": [
    {
      "object": "block",
      "type": "heading_2",
      "heading_2": {
        "rich_text": [{ "text": { "content": "Welcome" } }]
      }
    },
    {
      "object": "block",
      "type": "paragraph",
      "paragraph": {
        "rich_text": [
          {
            "text": {
              "content": "This page was created with the Notion API. You just made your first request!"
            }
          }
        ]
      }
    }
  ]
}

The block model gives you precise control over every element — formatting, colors, toggles, and block types that markdown can’t express. Use markdown when you want simplicity, and children when you need that control.

See Working with page content to learn more about the block model.

Check the result

A successful response returns a page object:

Response

{
  "object": "page",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_time": "2025-01-15T09:30:00.000Z",
  "last_edited_time": "2025-01-15T09:30:00.000Z",
  "icon": {
    "type": "emoji",
    "emoji": "🚀"
  },
  "parent": {
    "type": "workspace",
    "workspace": true
  },
  "properties": {
    "title": {
      "id": "title",
      "type": "title",
      "title": [{ "plain_text": "Hello from the API" }]
    }
  },
  "url": "https://www.notion.com/Hello-from-the-API-a1b2c3d4e5f67890abcdef1234567890",
  "public_url": null
}

To see your new page:

• From the response: Copy the url value and open it in your browser.
• From Notion: Look in Private in your sidebar for 🚀 Hello from the API.

Open the page and you should see your heading, paragraph, and bullet list inside.

Getting an error?

Error responses return a JSON object with a code and message:

{
  "object": "error",
  "status": 401,
  "code": "unauthorized",
  "message": "API token is invalid."
}

Error	Fix
unauthorized	Double-check that your token is correct and hasn’t expired.
validation_error	Check the request body against the Create a page reference.

For the full list of error codes, see Status codes.

Next steps

Now that you’ve made your first request, explore what else you can build — create databases, query content, manage comments, upload files, and more.

API reference

Browse every endpoint, request parameter, and response field.

JavaScript SDK

Official client library for Node.js.