[metadata]
apple-mobile-web-app-title: Notion Docs
application-name: Notion Docs
description: Create a page in your Notion workspace with a personal access token and a single API request.
generator: Mintlify
msapplication-TileColor: #000
msapplication-config: /mintlify-assets/_mintlify/favicons/notion-demo/1PaJq9z3waub4TpE/_generated/favicon/browserconfig.xml
og:description: Create a page in your Notion workspace with a personal access token and a single API request.
og:image: https://notion-demo.mintlify.app/images/og-image.png
og:image:height: 630
og:image:width: 1200
og:site_name: Notion Docs
og:title: API quickstart - Notion Docs
og:type: website
og:url: https://developers.notion.com/guides/get-started/quick-start
twitter:card: summary_large_image
twitter:description: Create a page in your Notion workspace with a personal access token and a single API request.
twitter:image: https://notion-demo.mintlify.app/images/og-image.png
twitter:image:height: 630
twitter:image:width: 1200
twitter:title: API quickstart - Notion Docs
viewport: width=device-width, initial-scale=1, viewport-fit=cover

[canonical-links]
https://developers.notion.com/guides/get-started/quick-start

[document-links]
/llms.txt: /llms.txt
API Reference: /reference/intro
API reference Browse every endpoint, request parameter, and response field.: /reference/intro
API token security: /guides/get-started/handling-api-keys
Admin API: /reference/admin/intro
Authorization: /guides/get-started/authorization
CLI Reference: /cli/get-started/overview
Changelog: /page/changelog
Create a page: /reference/post-page
Developer portal: https://www.notion.so/developers
Example code: https://developers.notion.com/page/examples
Examples: /page/examples
Guides: /guides/get-started/overview
Historical changelog: /guides/resources/historical-changelog
Internal connections: /guides/get-started/internal-connections
Introduction: /guides/link-previews/introduction
JavaScript SDK Official client library for Node.js.: https://github.com/makenotion/notion-sdk-js
List on the Marketplace: /guides/get-started/marketplace-listing
Log in: https://www.notion.com/login
Notion Docs home page: /
Notion-flavored Markdown: /guides/data-apis/enhanced-markdown
Overview Previous: /guides/get-started/overview
Overview: /compliance/overview
Overview: /guides/get-started/overview
Personal access tokens Next: /guides/get-started/personal-access-tokens
Personal access tokens: /guides/get-started/personal-access-tokens
Personal access tokens: https://www.notion.so/developers/tokens
Postman workspace: https://www.postman.com/notionhq/notion-s-api-workspace/collection/52041987-03f70d8f-b6e5-4306-805c-f95f7cdf05b9
Preparing for users: /guides/get-started/preparing-for-users
Public connections: /guides/get-started/public-connections
Quickstart: /guides/get-started/quick-start
Status codes: /reference/status-codes
Who can create PATs: /guides/get-started/personal-access-tokens#who-can-create-pats
Workers: /workers/get-started/overview
Working with comments: /guides/data-apis/working-with-comments
Working with page content: /guides/data-apis/working-with-page-content
Working with views: /guides/data-apis/working-with-views
slack: https://join.slack.com/t/notiondevs/shared_invite/zt-3u9oid9q8-HLUBmMVWYK~g9HFo4U4raA
x: https://x.com/NotionDevs

[structured-data]
{"@context":"https://schema.org","@graph":[{"@id":"https://developers.notion.com/#organization","@type":"Organization","logo":{"@type":"ImageObject","url":"https://mintcdn.com/notion-demo/5YdhSbldE14t5Rna/logo/light.svg?fit=max&auto=format&n=5YdhSbldE14t5Rna&q=85&s=249f5693ad929397409bf9b51d6d539d"},"name":"Notion Docs","url":"https://developers.notion.com"},{"@id":"https://developers.notion.com#website","@type":"WebSite","name":"Notion Docs","publisher":{"@id":"https://developers.notion.com/#organization"},"url":"https://developers.notion.com"},{"@id":"https://developers.notion.com/guides/get-started/quick-start#webpage","@type":"WebPage","breadcrumb":{"@id":"https://developers.notion.com/guides/get-started/quick-start#breadcrumb"},"dateModified":"2026-08-04T23:01:38.859Z","description":"Create a page in your Notion workspace with a personal access token and a single API request.","isPartOf":{"@id":"https://developers.notion.com#website"},"name":"API quickstart","url":"https://developers.notion.com/guides/get-started/quick-start"},{"@id":"https://developers.notion.com/guides/get-started/quick-start#breadcrumb","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","item":"https://developers.notion.com/guides/get-started/overview","name":"Get started","position":1},{"@type":"ListItem","item":"https://developers.notion.com/guides/get-started/quick-start","name":"API quickstart","position":2}]},{"@id":"https://developers.notion.com/guides/get-started/quick-start#article","@type":["Article","TechArticle"],"dateModified":"2026-08-04T23:01:38.859Z","description":"Create a page in your Notion workspace with a personal access token and a single API request.","headline":"API quickstart","image":"https://developers.notion.com/images/og-image.png","isPartOf":{"@id":"https://developers.notion.com#website"},"mainEntityOfPage":{"@id":"https://developers.notion.com/guides/get-started/quick-start#webpage"},"name":"API quickstart","publisher":{"@id":"https://developers.notion.com/#organization"},"url":"https://developers.notion.com/guides/get-started/quick-start"}]}

[content]
API quickstart - Notion Docs
Documentation Index
Fetch the complete documentation index at:
/llms.txt
Use this file to discover all available pages before exploring further.
Skip to main content
Notion Docs
home page
Search...
⌘
K
Ask Assistant
Log in
Developer portal
Developer portal
Search...
Navigation
Get started
API quickstart
Guides
API Reference
CLI Reference
Workers
Admin API
Changelog
Examples
Get started
Overview
Quickstart
Personal access tokens
Internal connections
Public connections
Authorization
API token security
Preparing for users
List on the Marketplace
Agent APIs
Notion MCP
API versions
Upgrading to 2026-03-11
Upgrading to 2025-09-03
Data APIs
Working with page content
Working with databases
Working with views
Working with comments
Working with markdown content
Working with files and media
Resources
Example code
Postman workspace
Historical changelog
Compliance
Overview
Event reference
Link previews
Introduction
On this page
Step 1: Get a personal access token
Step 2: Create a page
Check the result
Next steps
Get started
API quickstart
Copy page
Copy page
Create a page in your Notion workspace with a personal access token and a single API request.
Copy page
Copy page
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
Windows (PowerShell)
export
NOTION_API_KEY
=
ntn_
***
$
env:
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
HTTP
JavaScript
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)"
}'
POST
https://api.notion.com/v1/pages
Authorization
:
Bearer {PERSONAL_ACCESS_TOKEN}
Content-Type
:
application/json
Notion-Version
:
2026-03-11
{
"icon"
: {
"emoji"
:
"🚀"
},
"markdown"
:
"# Hello from the API
\n\n
## Welcome
\n\n
This 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)"
}
// Save as quickstart.mjs after running: npm install @notionhq/client
import
{
Client
}
from
"@notionhq/client"
;
const
notion
=
new
Client
({
auth:
process
.
env
.
NOTION_API_KEY
});
async
function
main
() {
const
page
=
await
notion
.
pages
.
create
({
icon:
{
emoji:
"🚀"
},
markdown:
[
"# Hello from the API"
,
""
,
"## Welcome"
,
""
,
"This page was created with the Notion API. You just made your first request!"
,
""
,
"- Read the [API reference](https://developers.notion.com/reference/intro)"
,
"- Explore [examples](https://developers.notion.com/page/examples)"
,
].
join
(
"
\n
"
),
});
console
.
log
(
"Created page:"
,
page
.
url
);
}
main
();
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.
Overview
Previous
Personal access tokens
Next
⌘
I
x
slack
Assistant
Responses are generated using AI and may contain mistakes.
