` tags within a single `>` line: ``` > Line 1
Line 2
Line 3 {color="Color"} ``` Multiple `>` lines render as separate quote blocks, not a single multi-line quote. ### Toggle ```html theme={null}
Toggle title
Children (must be indented)| Cell content |
` | | Color | `text` | ### Mentions ```html theme={null}
` / `` |
| [Quote](/reference/block#quote) | `> quote` |
| [Callout](/reference/block#callout) | `
` |
| [Quote](/reference/block#quote) | `> quote` |
| [Callout](/reference/block#callout) | `` |
| [Divider](/reference/block#divider) | `---` |
| [Code](/reference/block#code) | Fenced code block with language |
| [Equation](/reference/block#equation) | `$$ equation $$` |
| [Table](/reference/block#table) | `` with `` and `` |
| [Image](/reference/block#image) | `` |
| [File](/reference/block#file) | `caption ` |
| [Video](/reference/block#video) | `` |
| [Audio](/reference/block#audio) | `` |
| [PDF](/reference/block#pdf) | `caption ` |
| [Child page](/reference/block#child-page) | `title ` |
| [Child database](/reference/block#child-database) | `title ` |
| [Synced block](/reference/block#synced-block) | `` with content |
| [Column list / Column](/reference/block#column-list-and-column) | `` / `` |
| [Table of contents](/reference/block#table-of-contents) | `` (transcript included when `include_transcript=true`) |
For file-based blocks (image, file, video, audio, PDF), the URLs in the markdown output are pre-signed and ready to download. They expire after a short period, consistent with the [block-based API](/reference/block#file).
### Unsupported block types
The following block types are not yet rendered in the markdown output. When encountered, they appear as `` in the markdown output.
You can use the [block-based API](/reference/block) to retrieve structured data for any unsupported block types you encounter in the markdown output.
## Creating a page with markdown
Use `POST /v1/pages` with the `markdown` parameter instead of `children` to create a page from a markdown string.
The `markdown` field expects actual newline characters. In JSON, use `\n` to encode them — for example, `"# Heading\n\nParagraph"`. When using cURL, wrap the `--data` body in **single quotes** so that `\n` is preserved for the JSON parser.
```bash cURL theme={null}
curl -X POST https://api.notion.com/v1/pages \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Content-Type: application/json" \
-H "Notion-Version: 2026-03-11" \
--data '{
"parent": { "page_id": "YOUR_PAGE_ID" },
"markdown": "# Meeting Notes\n\nDiscussed roadmap priorities.\n\n## Action items\n\n- [ ] Draft proposal\n- [ ] Schedule follow-up"
}'
```
```javascript JavaScript theme={null}
const { Client } = require("@notionhq/client");
const notion = new Client({ auth: process.env.NOTION_API_KEY });
const response = await notion.pages.create({
parent: { page_id: "YOUR_PAGE_ID" },
markdown: "# Meeting Notes\n\nDiscussed roadmap priorities.\n\n## Action items\n\n- [ ] Draft proposal\n- [ ] Schedule follow-up",
});
```
**Key behaviors:**
* The `markdown` parameter is mutually exclusive with `children` and `content`. You cannot use both.
* If `properties.title` is omitted, the first `# h1` heading is extracted as the page title.
* Available to all connection types (public, internal, and personal access tokens).
* Requires `insert_content` and `insert_property` capabilities.
The response is a standard [page object](/reference/page).
## Retrieving a page as markdown
Use `GET /v1/pages/:page_id/markdown` to retrieve a page's content rendered as enhanced markdown.
```bash cURL theme={null}
curl 'https://api.notion.com/v1/pages/YOUR_PAGE_ID/markdown' \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Notion-Version: 2026-03-11"
```
```javascript JavaScript theme={null}
const response = await notion.pages.retrieveMarkdown({
page_id: "YOUR_PAGE_ID",
});
console.log(response.markdown);
```
**Response:**
```json theme={null}
{
"object": "page_markdown",
"id": "page-uuid",
"markdown": "# Meeting Notes\n\nDiscussed roadmap priorities.\n\n## Action items\n\n- [ ] Draft proposal\n- [ ] Schedule follow-up",
"truncated": false,
"unknown_block_ids": []
}
```
### Query parameters
| Parameter | Type | Description |
| -------------------- | ------- | ---------------------------------------------------- |
| `include_transcript` | boolean | Include meeting note transcripts (default: `false`). |
```bash cURL (with transcript) theme={null}
curl 'https://api.notion.com/v1/pages/YOUR_PAGE_ID/markdown?include_transcript=true' \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Notion-Version: 2026-03-11"
```
```javascript JavaScript theme={null}
const response = await notion.pages.retrieveMarkdown({
page_id: "YOUR_PAGE_ID",
include_transcript: true,
});
```
**Key behaviors:**
* Available to all connection types (public, internal, and personal access tokens).
* Requires `read_content` capability.
* File URIs in the content are automatically converted to pre-signed URLs.
### Unknown blocks, truncation, and permissions
Some blocks in a page may appear as `` tags in the markdown output. This can happen for two reasons:
1. **Truncation** — the page exceeds the record limit (approximately 20,000 blocks) and some blocks were not loaded.
2. **Permissions** — the page contains child pages or other content that is not shared with the connection. The connection can access the parent page, but not those specific child blocks.
In both cases:
* The `truncated` field is set to `true`.
* The affected blocks appear as `",
"truncated": true,
"unknown_block_ids": ["def456-with-dashes-uuid"]
}
```
You can attempt to fetch the content of unknown blocks by passing their IDs back to the same endpoint:
```bash cURL (fetching an unknown block) theme={null}
curl 'https://api.notion.com/v1/pages/UNKNOWN_BLOCK_ID/markdown' \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Notion-Version: 2026-03-11"
```
```javascript JavaScript theme={null}
const blockResp = await notion.pages.retrieveMarkdown({
page_id: "UNKNOWN_BLOCK_ID",
});
```
For blocks that were unknown due to truncation, this returns the subtree rooted at that block. For blocks that are unknown due to permissions, the request returns an `object_not_found` error — the connection does not have access to that content.
The `unknown_block_ids` array does not distinguish between truncated and inaccessible blocks. When re-fetching unknown block IDs, handle `object_not_found` errors gracefully as they indicate blocks the connection cannot access.
For the best experience, keep pages under a few thousand blocks. Very large pages may require multiple requests to fully retrieve.
**Example: iteratively fetching a large page**
```python Python theme={null}
import requests
headers = {
"Authorization": f"Bearer {NOTION_API_KEY}",
"Notion-Version": "2026-03-11",
}
resp = requests.get(
f"https://api.notion.com/v1/pages/{page_id}/markdown",
headers=headers,
).json()
all_markdown = resp["markdown"]
for block_id in resp.get("unknown_block_ids", []):
block_resp = requests.get(
f"https://api.notion.com/v1/pages/{block_id}/markdown",
headers=headers,
).json()
all_markdown += "\n" + block_resp["markdown"]
```
```javascript JavaScript theme={null}
const response = await notion.pages.retrieveMarkdown({
page_id: "YOUR_PAGE_ID",
});
let allMarkdown = response.markdown;
for (const blockId of response.unknown_block_ids) {
const blockResp = await notion.pages.retrieveMarkdown({
page_id: blockId,
});
allMarkdown += "\n" + blockResp.markdown;
}
```
## Updating a page with markdown
Use `PATCH /v1/pages/:page_id/markdown` to insert or replace content in an existing page using markdown.
The request body uses a **discriminated union** with four command variants. We recommend `update_content` and `replace_content` for new connections — they offer more precise control and better performance than the older `insert_content` and `replace_content_range` commands.
The `content` field expects standard markdown with actual newline characters. In your JSON request body, use `\n` to encode newlines — for example, `"## Heading\n\nParagraph text"` creates a heading followed by a paragraph. Literal backslash-n sequences (like typing `\n` into a form field) will not be interpreted as newlines.
When using cURL, wrap the `--data` body in **single quotes** so that `\n` is preserved for the JSON parser. Avoid `$'...'` quoting, which converts `\n` into a literal newline and produces invalid JSON.
### Updating content with search-and-replace
Use `update_content` to make targeted edits with an array of search-and-replace operations. Each operation specifies `old_str` (content to find) and `new_str` (replacement content).
```bash cURL theme={null}
curl -X PATCH 'https://api.notion.com/v1/pages/YOUR_PAGE_ID/markdown' \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Content-Type: application/json" \
-H "Notion-Version: 2026-03-11" \
--data '{
"type": "update_content",
"update_content": {
"content_updates": [
{
"old_str": "Draft proposal",
"new_str": "Draft proposal (due Friday)"
},
{
"old_str": "Schedule follow-up",
"new_str": "Schedule follow-up with design team"
}
]
}
}'
```
```javascript JavaScript theme={null}
const response = await notion.pages.updateMarkdown({
page_id: "YOUR_PAGE_ID",
type: "update_content",
update_content: {
content_updates: [
{ old_str: "Draft proposal", new_str: "Draft proposal (due Friday)" },
{ old_str: "Schedule follow-up", new_str: "Schedule follow-up with design team" },
],
},
});
```
Each `old_str` must match exactly one location in the page. If it matches multiple locations, a `validation_error` is returned — set `replace_all_matches: true` on that operation to replace all occurrences.
### Replacing all page content
Use `replace_content` to replace the entire page content with new markdown.
```bash cURL theme={null}
curl -X PATCH 'https://api.notion.com/v1/pages/YOUR_PAGE_ID/markdown' \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Content-Type: application/json" \
-H "Notion-Version: 2026-03-11" \
--data '{
"type": "replace_content",
"replace_content": {
"new_str": "# Fresh Start\n\nThis replaces all previous content."
}
}'
```
```javascript JavaScript theme={null}
const response = await notion.pages.updateMarkdown({
page_id: "YOUR_PAGE_ID",
type: "replace_content",
replace_content: {
new_str: "# Fresh Start\n\nThis replaces all previous content.",
},
});
```
### Legacy commands
The `insert_content` and `replace_content_range` commands are still supported but are no longer recommended. They use an ellipsis-based selection format that is less precise than the search-and-replace approach of `update_content`. New connections should use `update_content` or `replace_content` instead.
Insert new markdown content at the start of a page, after a specific point in the page, or at the end.
```bash cURL (prepend to start) theme={null}
curl -X PATCH 'https://api.notion.com/v1/pages/YOUR_PAGE_ID/markdown' \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Content-Type: application/json" \
-H "Notion-Version: 2026-03-11" \
--data '{
"type": "insert_content",
"insert_content": {
"content": "## Latest update\n\nAdded at the top of the page.",
"position": { "type": "start" }
}
}'
```
```javascript JavaScript theme={null}
const response = await notion.pages.updateMarkdown({
page_id: "YOUR_PAGE_ID",
type: "insert_content",
insert_content: {
content: "## Latest update\n\nAdded at the top of the page.",
position: { type: "start" },
},
});
```
```bash cURL (insert after selection) theme={null}
curl -X PATCH 'https://api.notion.com/v1/pages/YOUR_PAGE_ID/markdown' \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Content-Type: application/json" \
-H "Notion-Version: 2026-03-11" \
--data '{
"type": "insert_content",
"insert_content": {
"content": "## New Section\n\nInserted content here.",
"after": "# Meeting Notes...Action items"
}
}'
```
```javascript JavaScript theme={null}
const response = await notion.pages.updateMarkdown({
page_id: "YOUR_PAGE_ID",
type: "insert_content",
insert_content: {
content: "## New Section\n\nInserted content here.",
after: "# Meeting Notes...Action items",
},
});
```
```bash cURL (append to end) theme={null}
curl -X PATCH 'https://api.notion.com/v1/pages/YOUR_PAGE_ID/markdown' \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Content-Type: application/json" \
-H "Notion-Version: 2026-03-11" \
--data '{
"type": "insert_content",
"insert_content": {
"content": "## Appendix\n\nAdded at the end of the page.",
"position": { "type": "end" }
}
}'
```
```javascript JavaScript theme={null}
const response = await notion.pages.updateMarkdown({
page_id: "YOUR_PAGE_ID",
type: "insert_content",
insert_content: {
content: "## Appendix\n\nAdded at the end of the page.",
position: { type: "end" },
},
});
```
The `position` parameter supports `{ "type": "start" }` and `{ "type": "end" }`. When both `position` and `after` are omitted, content is appended to the end of the page, preserving the existing behavior.
The `after` parameter uses an **ellipsis-based selection** format: `"start text...end text"`. This matches a range from the first occurrence of the start text to the end text. Do not provide `after` and `position` in the same request.
Replace a matched range of existing content with new markdown.
```bash cURL theme={null}
curl -X PATCH 'https://api.notion.com/v1/pages/YOUR_PAGE_ID/markdown' \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Content-Type: application/json" \
-H "Notion-Version: 2026-03-11" \
--data '{
"type": "replace_content_range",
"replace_content_range": {
"content": "## Updated Section\n\nNew content replaces the old.",
"content_range": "## Old Section...end of old content"
}
}'
```
```javascript JavaScript theme={null}
const response = await notion.pages.updateMarkdown({
page_id: "YOUR_PAGE_ID",
type: "replace_content_range",
replace_content_range: {
content: "## Updated Section\n\nNew content replaces the old.",
content_range: "## Old Section...end of old content",
},
});
```
The `content_range` parameter uses the same ellipsis-based selection as `after`.
### Safety: protecting child pages and databases
By default, the update endpoint refuses to delete child pages or databases. If an operation would delete them, a `validation_error` is returned listing the affected items.
To allow deletion, set `allow_deleting_content: true` in the command body. This option is supported by `replace_content_range`, `update_content`, and `replace_content`:
```json theme={null}
{
"type": "replace_content",
"replace_content": {
"new_str": "Replacement content.",
"allow_deleting_content": true
}
}
```
### Update response
All variants return the full page content as markdown after the update:
```json theme={null}
{
"object": "page_markdown",
"id": "page-uuid",
"markdown": "...full page content after update...",
"truncated": false,
"unknown_block_ids": []
}
```
**Key behaviors:**
* Available to all connection types (public, internal, and personal access tokens).
* Requires `update_content` capability.
* The `content_range` / `after` / `old_str` matching is case-sensitive.
### Error responses
| Error code | Condition |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `validation_error` | The `content_range` or `after` selection does not match any content in the page, or an `old_str` in `update_content` is not found. |
| `validation_error` | Both `insert_content.after` and `insert_content.position` are provided. Use only one insertion target. |
| `validation_error` | An `old_str` in `update_content` matches multiple locations and `replace_all_matches` is not `true`. |
| `validation_error` | The operation would delete child pages or databases and `allow_deleting_content` is not `true`. The error message lists the affected items. |
| `validation_error` | The provided ID is a database or non-page block (use the appropriate API for those record types). |
| `validation_error` | The target page is a synced page (`external_object_instance_page`). Synced pages cannot be updated. |
| `object_not_found` | The page does not exist or the connection does not have access to it. |
| `restricted_resource` | The connection lacks `update_content` capability. |
### Meeting note transcripts
The update endpoint always skips meeting note transcript content, matching the default behavior of the GET endpoint. If you retrieve a page with `include_transcript=true`, the transcript text will appear in the response but cannot be used in `content_range` or `after` selections — the update endpoint does not see transcript content during matching and will return a `validation_error` for selections that span transcript text.
## Access control summary
| Endpoint | Public connections | Internal connections | Personal access tokens | Required capability |
| ----------------------------- | ------------------ | -------------------- | ---------------------- | ------------------- |
| Create (`POST /v1/pages`) | Yes | Yes | Yes | `insert_content` |
| Read (`GET .../markdown`) | Yes | Yes | Yes | `read_content` |
| Update (`PATCH .../markdown`) | Yes | Yes | Yes | `update_content` |
# Working with page content
Source: https://developers.notion.com/guides/data-apis/working-with-page-content
Learn about page content and how to add or retrieve it with the Notion API.
## Overview
[Pages](https://www.notion.so/help/category/write-edit-and-customize) are where users write everything from quick notes, to shared documents, to curated landing pages in Notion. Connections can help users turn Notion into the single source of truth by syndicating content or help users gather, connect, and visualize content inside Notion.
In this guide, you'll learn about how the building blocks of page content are represented in the API and what you can do with them. By the end, you'll be able to create new pages with content, read content from other pages, and add blocks to existing pages.
### Page content versus properties
In general, **page properties** are best for capturing structured information such as a due date, a category, or a relationship to another page. **Page content** is best for looser structures or free form content. Page content is where users compose their thoughts or tell a story. Page properties are where users capture data and build systems. Your connection should aim to use each in the way users expect.
![]()
## Modeling content as blocks
A page's content is represented by a list of [block objects](/reference/block). These blocks are referred to as the page's children. Each block has a type, such as a paragraph, a heading, or an image. Some types of blocks, such as a toggle list, have children of their own.
Let's start with a simple example, a [paragraph block](/reference/block#paragraph):
```js JavaScript theme={null}
{
"object": "block",
"id": "380c78c0-e0f5-4565-bdbd-c4ccb079050d",
"type": "paragraph",
"created_time": "",
"last_edited_time": "",
"has_children": false,
"paragraph": {
"rich_text": [{
"type": "text",
"text": { "content": "Grocery List" }
}]
}
}
```
Paragraph blocks include common properties which every block includes: `object`, `type`, `created_time`, `last_edited_time`, and `has_children`. In addition, it contains type-specific information inside the `paragraph` property. Paragraph blocks have a `rich_text` property. Other block types have different type-specific properties.
Now let's look at an example where the block has child blocks: a paragraph followed by an indented [todo block](/reference/block#to-do):
```js JavaScript expandable theme={null}
{
"object": "block",
"id": "380c78c0-e0f5-4565-bdbd-c4ccb079050d",
"type": "paragraph",
"created_time": "",
"last_edited_time": "",
"has_children": true,
"paragraph": {
"rich_text": [{
"type": "text",
"text": { "content": "Grocery List" }
}],
"children": [
{
"object": "block",
"id": "6d5b2463-a1c1-4e22-9b3b-49b3fe7ad384",
"type": "to_do",
"created_time": "",
"last_edited_time": "",
"has_children": false,
"to_do": {
"rich_text": [{
"type": "text",
"text": { "content": "Buy kale" }
}],
"checked": false
}
}
]
}
}
```
Child blocks are represented as a list of blocks inside the type-specific property. When a block has children, the `has_children` property is `true`. Only some block types, like paragraph blocks, support children.
**Pages are also blocks**
Pages are a special kind of block, but they have children like many other block types. When [retrieving a list of child blocks](/reference/get-block-children), you can use the page ID as a block ID.
When a child page appears inside another page, it's represented as a `child_page` block, which does not have children. You should think of this as a reference to the page block.
**Unsupported block types**
The Notion API currently supports a subset of Notion [block](/reference/block#block-type-objects) types, with support for more coming soon. When an unsupported block type appears in a page, it will have the type `"unsupported"`.
### Rich text
In the previous block examples, the value of the `rich_text` property is a list of [rich text objects](/reference/rich-text). Rich text objects can describe more than a simple string - the object includes style information, links, mentions, and more.
Let's look at a simple example that just contains the words "Grocery List":
```js JavaScript theme={null}
{
"type": "text",
"text": {
"content": "Grocery List",
"link": null
},
"annotations": {
"bold": false,
"italic": false,
"strikethrough": false,
"underline": false,
"code": false,
"color": "default"
},
"plain_text": "Grocery List",
"href": null
}
```
Rich text objects follow a similar pattern for type-specific configuration. The rich text object above has a type of `"text"`, and it has additional configuration related to that type in the `text` property. Other information that does not depend on the type, such as `annotations`, `plain_text`, and `href`, are at the top level of the rich text object.
Rich text is used both in page content and inside [page property values](/reference/page-property-values).
## Creating a page with content
Pages can be created with child blocks using the [create a page](/reference/post-page) endpoint. This endpoint supports creating a page within another page, or creating a page within a database.
Let's try creating a page within another page with some sample content. We will use all three parameters for this endpoint. The parent parameter is a [page parent](/reference/page#page-parent). We can build this object using an existing page ID:
```js JavaScript theme={null}
{
"type": "page_id",
"page_id": "494c87d0-72c4-4cf6-960f-55f8427f7692"
}
```
**Permissions**
Before a connection can create a page within another page, it needs access to the page parent. To share a page with a connection, click the `•••` menu at the top right of a page, scroll to `Add connections`, and use the search bar to find and select the connection from the dropdown list.
**Where can I find my page's ID?**
Here's a quick procedure to find the page ID for a specific page in Notion:
Open the page in Notion.
Use the Share menu to Copy link.
Now paste the link in your text editor so you can take a closer look.
The URL ends in a page ID. It should be a 32 character long string. Format this value by inserting hyphens (-) in the following pattern:
1. 8-4-4-4-12 (each number is the length of characters between the hyphens).
2. Example: `1429989fe8ac4effbc8f57f56486db54` becomes `1429989f-e8ac-4eff-bc8f-57f56486db54`.
3. This value is your page ID.
While this procedure is helpful to try the API, **you shouldn't ask users to do this for your connection**. It's more common for a connection to determine a page ID by calling the [search API](/reference/post-search).
The `properties` parameter is an object which describes the page properties. Let's use a simple example with only the required `title` property:
```js JavaScript theme={null}
{
"Name": {
"type": "title",
"title": [{ "type": "text", "text": { "content": "A note from your pals at Notion" } }]
}
}
```
**Page properties within a database**
Pages within a database parent require properties to conform to the database's schema. Follow the [working with databases guide](/guides/data-apis/working-with-databases) for an in-depth discussion with examples.
The children parameter is a list of [block objects]() which describe the page content. Let's use some sample content:
```js JavaScript theme={null}
[
{
"object": "block",
"type": "paragraph",
"paragraph": {
"rich_text": [{ "type": "text", "text": { "content": "You made this page using the Notion API. Pretty cool, huh? We hope you enjoy building with us." } }]
}
}
]
```
**Size limits**
When creating new blocks, keep in mind that the Notion API has [size limits](/reference/errors#size-limits) for the content.
Using all three of the parameters, we create a page by sending a request to [the endpoint](/reference/post-page).
```bash cURL expandable theme={null}
curl -X POST https://api.notion.com/v1/pages \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Content-Type: application/json" \
-H "Notion-Version: 2026-03-11" \
--data '{
"parent": { "page_id": "494c87d0-72c4-4cf6-960f-55f8427f7692" },
"properties": {
"title": {
"title": [{ "type": "text", "text": { "content": "A note from your pals at Notion" } }]
}
},
"children": [
{
"object": "block",
"type": "paragraph",
"paragraph": {
"rich_text": [{ "type": "text", "text": { "content": "You made this page using the Notion API. Pretty cool, huh? We hope you enjoy building with us." } }]
}
}
]
}'
```
```javascript JavaScript expandable theme={null}
const { Client } = require('@notionhq/client');
const notion = new Client({ auth: process.env.NOTION_API_KEY });
(async () => {
const response = await notion.pages.create({
parent: {
page_id: '494c87d072c44cf6960f55f8427f7692',
},
properties: {
title: {
type: 'title',
title: [
{
type: 'text',
text: {
content: 'A note from your pals at Notion',
},
},
],
},
},
children: [
{
object: 'block',
type: 'paragraph',
paragraph: {
rich_text: [
{
type: 'text',
text: {
content: 'You made this page using the Notion API. Pretty cool, huh? We hope you enjoy building with us.',
},
},
],
},
},
],
});
console.log(response);
})();
```
Once the page is added, you'll receive a response containing the new [page object](/reference/page). Take a look inside Notion and view your new page.
## Reading blocks from a page
Page content can be read from a page using the [retrieve block children](/reference/get-block-children) endpoint. This endpoint returns a list of children for any block which supports children. While pages are a common starting point for reading block children, you can retrieve the block children of other kinds of blocks, too.
The `block_id` parameter is the ID of any existing block. If you're following from the example above, the response contained a page ID. Let's use that page ID to read the sample content from the page. We'll use `"16d8004e-5f6a-42a6-9811-51c22ddada12"` as the block ID.
Using this `block_id`, we retrieve the block children by sending a request to [the endpoint](/reference/get-block-children).
```curl cURL theme={null}
curl https://api.notion.com/v1/blocks/16d8004e-5f6a-42a6-9811-51c22ddada12/children?page_size=100 \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Notion-Version: 2026-03-11"
```
```javascript JavaScript theme={null}
const { Client } = require('@notionhq/client');
const notion = new Client({ auth: process.env.NOTION_API_KEY });
(async () => {
const blockId = '16d8004e5f6a42a6981151c22ddada12';
const response = await notion.blocks.children.list({
block_id: blockId,
});
console.log(response);
})();
```
You'll receive a response that contains a list of block objects.
```js JavaScript theme={null}
{
"object": "list",
"results": [
{
"object": "block",
/* details omitted */
}
],
"has_more": false,
"next_cursor": null
}
```
This is a paginated response. Paginated responses are used throughout the Notion API when returning a potentially large list of objects. The maximum number of results in one paginated response is 100. The [pagination reference](/reference/pagination) explains how to use the "start\_cursor" and "page\_size" parameters to get more than 100 results.
In this case, the individual child blocks we requested are in the "results" array.
### Reading nested blocks
What happens when the results contain a block that has its own children? In this case, the response will not contain those children, but the `has_children` property will be `true`. If your connection needs a complete representation of a page's (or any block's) content, it should search the results for blocks with `has_children` set to `true`, and recursively call the [retrieve block children](/reference/get-block-children) endpoint.
Reading large pages may take some time. We recommend using asynchronous operations in your architecture, such as a job queue. You will also need to be mindful of [rate limits](/reference/errors#rate-limits) to appropriately slow down making new requests after the limit is met.
## Appending blocks to a page
Connections can add more content to a page by using the [append block children](/reference/patch-block-children) endpoint. Let's try to add another block to the page we created in the example above. This endpoint requires two parameters: `block_id` and `children`.
The `block_id` parameter is the ID of any existing block. If you're following from the example above, let's use the same page ID as the block ID: `"16d8004e-5f6a-42a6-9811-51c22ddada12"`.
The `children` parameter is a list of [block objects](/reference/block) which describe the content we want to append. Let's use some more sample content:
```js JavaScript theme={null}
[
{
"object": "block",
"type": "paragraph",
"paragraph": {
"rich_text": [{ "type": "text", "text": { "content": "– Notion API Team", "link": { "type": "url", "url": "https://twitter.com/NotionAPI" } } }]
}
}
]
```
Using both parameters, we append blocks by sending a request to [the endpoint](/reference/patch-block-children).
```bash cURL theme={null}
curl -X PATCH https://api.notion.com/v1/blocks/16d8004e-5f6a-42a6-9811-51c22ddada12/children \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Content-Type: application/json" \
-H "Notion-Version: 2026-03-11" \
--data '{
"children": [
{
"object": "block",
"type": "paragraph",
"paragraph": {
"rich_text": [{ "type": "text", "text": { "content": "– Notion API Team", "link": { "type": "url", "url": "https://twitter.com/NotionAPI" } } }]
}
}
]
}'
```
```javascript JavaScript theme={null}
const { Client } = require('@notionhq/client');
const notion = new Client({ auth: process.env.NOTION_API_KEY });
(async () => {
const blockId = '16d8004e5f6a42a6981151c22ddada12';
const response = await notion.blocks.children.append({
block_id: blockId,
children: [
{
object: 'block',
type: 'paragraph',
paragraph: {
rich_text: [
{
type: 'text',
text: {
content: '– Notion API Team',
link: {
type: 'url',
url: 'https://twitter.com/NotionAPI',
},
},
},
],
},
},
],
});
console.log(response);
})();
```
You'll receive a response that contains the updated block. The response does not contain the child blocks, but it will show `has_children` set to `true`.
By default, new block children are appended at the end of the parent block. To place the block after a specific child block and not at the end, use the `position` body parameter. The `position` object supports three placement types: `after_block` (insert after a specific block), `start` (insert at the beginning), and `end` (the default when `position` is omitted). For example, if the parent `block_id` is for a block that contains a bulleted list, you can use `position` with `after_block` to insert the new block children after a specific list item.
```bash cURL theme={null}
curl -X PATCH https://api.notion.com/v1/blocks/16d8004e-5f6a-42a6-9811-51c22ddada12/children \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Content-Type: application/json" \
-H "Notion-Version: 2026-03-11" \
--data '{
"children": [
{
"object": "block",
"type": "paragraph",
"paragraph": {
"rich_text": [{ "type": "text", "text": { "content": "– Notion API Team", "link": { "type": "url", "url": "https://twitter.com/NotionAPI" } } }]
}
}
],
"position": {
"type": "after_block",
"after_block": { "id": "" }
}
}'
```
## Working with AI meeting notes
[AI meeting notes](https://www.notion.com/help/ai-meeting-notes) in Notion automatically generate a summary, action-item notes, and a full transcript for recorded meetings. The API exposes this content through the [`meeting_notes` block type](/reference/block#meeting-notes).
A meeting notes block is a metadata container that lives on the page as a child block. It includes the meeting title, lifecycle status, calendar event details, recording timestamps, and — most importantly — pointers to three child blocks that hold the actual generated content:
* **Summary** (`summary_block_id`) — an AI-generated overview of the meeting.
* **Notes** (`notes_block_id`) — structured action items and key points.
* **Transcript** (`transcript_block_id`) — the full word-for-word transcript.
### Retrieving AI meeting notes content
Meeting notes blocks are read-only. To access the generated content, fetch the page's children to find the meeting notes block, then follow the child block IDs to retrieve each section's content.
**Step 1 — List the page's children** to find the meeting notes block:
```bash cURL theme={null}
curl 'https://api.notion.com/v1/blocks/PAGE_ID/children' \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Notion-Version: 2026-03-11"
```
```javascript JavaScript theme={null}
const { Client, isFullBlock } = require("@notionhq/client");
const notion = new Client({ auth: process.env.NOTION_API_KEY });
const { results } = await notion.blocks.children.list({
block_id: "PAGE_ID",
});
const meetingNotesBlock = results.find(
(block) => isFullBlock(block) && block.type === "meeting_notes"
);
```
**Step 2 — Read the child block IDs** from the meeting notes block's `children` field:
```json Example meeting_notes block response theme={null}
{
"object": "block",
"type": "meeting_notes",
"meeting_notes": {
"title": [{ "plain_text": "Team Sync" }],
"status": "notes_ready",
"children": {
"summary_block_id": "a1b2c3d4-...",
"notes_block_id": "b2c3d4e5-...",
"transcript_block_id": "c3d4e5f6-..."
},
"calendar_event": {
"start_time": "2026-02-24T10:00:00.000Z",
"end_time": "2026-02-24T10:45:00.000Z"
},
"recording": {
"start_time": "2026-02-24T10:00:00.000Z",
"end_time": "2026-02-24T10:45:00.000Z"
}
}
}
```
**Step 3 — Fetch each section's content** using the child block IDs. Each child is a standard block whose own children are the content (paragraphs, lists, etc.):
```bash cURL theme={null}
# Fetch the summary content
curl 'https://api.notion.com/v1/blocks/SUMMARY_BLOCK_ID/children' \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Notion-Version: 2026-03-11"
```
```javascript JavaScript theme={null}
const { children } = meetingNotesBlock.meeting_notes;
// Fetch the summary content blocks
const summary = await notion.blocks.children.list({
block_id: children.summary_block_id,
});
// Fetch the notes content blocks
const notes = await notion.blocks.children.list({
block_id: children.notes_block_id,
});
// Fetch the transcript content blocks
const transcript = await notion.blocks.children.list({
block_id: children.transcript_block_id,
});
```
The `status` field indicates whether the meeting notes are fully processed. Wait for `"notes_ready"` before fetching content — earlier statuses mean the AI is still generating output and the child blocks may not yet be available.
You can also retrieve meeting note content as markdown using the [Retrieve page markdown](/reference/retrieve-page-markdown) endpoint with the `include_transcript` query parameter. See [Working with markdown content](/guides/data-apis/working-with-markdown-content) for details.
## Conclusion
Nearly everything users see inside Notion is represented as blocks. Now that you've understood how your connection can build pages with blocks, read blocks, and add blocks to pages - you've unlocked most of the surface area in Notion. You connection can engage users where they do everything from creative writing, to building documentation, and more.
### Next steps
* This guide explains working with page content. Take a look at [working with database properties](/guides/data-apis/working-with-databases#database-properties).
* Explore the [block object](/reference/block) to see other types of blocks you can create.
* Learn more about the various kinds of [rich text objects](/reference/rich-text).
* Learn more about [pagination](/reference/intro#pagination).
# Working with views
Source: https://developers.notion.com/guides/data-apis/working-with-views
Learn how to set up and manage database views using the Notion API.
The Views API requires API version `2025-09-03` or later. If your connection uses an older version, see the [upgrade guide](/guides/get-started/upgrade-guide-2025-09-03) for migration steps.
## Overview
[Database views](https://www.notion.so/help/views-filters-and-sorts) let users see the same data in different ways — for example, as a table, board, calendar, timeline, gallery, list, form, chart, map, or dashboard. Each view can have its own filters, sorts, and layout configuration, so a single database can serve many different workflows.
The Notion API exposes views as first-class resources. This means connections can programmatically manage the same view presets that users create in the UI, enabling use cases like workspace bootstrapping, migration tooling, and automated view setup.
In this guide, you'll learn:
## Structure
A **view** is scoped to a single [data source](/reference/data-source) within a [database](/reference/database). It defines how pages in that data source are filtered, sorted, and displayed.
The view object looks like this:
```json View object example expandable theme={null}
{
"object": "view",
"id": "a3f1b2c4-5678-4def-abcd-1234567890ab",
"parent": {
"type": "database_id",
"database_id": "248104cd-477e-80fd-b757-e945d38000bd"
},
"data_source_id": "248104cd-477e-80af-bc30-000bd28de8f9",
"name": "High priority items",
"type": "table",
"filter": {
"property": "Priority",
"select": {
"equals": "High"
}
},
"sorts": [
{
"property": "Last ordered",
"direction": "descending"
}
],
"quick_filters": {
"Status": {
"status": { "equals": "In progress" }
}
},
"configuration": {
"type": "table",
"properties": [
{ "property_id": "title", "visible": true, "width": 300 },
{ "property_id": "abc1", "visible": true, "width": 200 },
{ "property_id": "def2", "visible": false }
],
"group_by": {
"type": "status",
"property_id": "ghi3",
"group_by": "group",
"sort": { "type": "manual" }
},
"wrap_cells": false,
"frozen_column_index": 1,
"show_vertical_lines": true
},
"created_time": "2026-01-15T10:30:00.000Z",
"last_edited_time": "2026-01-20T14:22:00.000Z",
"created_by": {
"object": "user",
"id": "e7f3a4b2-1234-5678-9abc-def012345678"
},
"last_edited_by": {
"object": "user",
"id": "e7f3a4b2-1234-5678-9abc-def012345678"
},
"url": "https://www.notion.so/example/248104cd477e80fdb757e945d38000bd?v=a3f1b2c45678"
}
```
Key fields:
* **`type`** — The layout type. One of: `table`, `board`, `list`, `calendar`, `timeline`, `gallery`, `form`, `chart`, `map`, or `dashboard`.
* **`data_source_id`** — Which data source this view is "over". A database can have multiple data sources, and each view targets exactly one. For dashboard views this is `null` since dashboards contain multiple widget views, each with their own data source.
* **`filter`** and **`sorts`** — Use the same shapes as the [filter](/reference/filter-data-source-entries) and [sort](/reference/sort-data-source-entries) parameters in data source queries.
* **`quick_filters`** — A map of property-level filters that appear in the view's filter bar. Keys are property names or IDs, values are filter conditions (same shape as property filters, without the `property` field). See [Quick filters](#quick-filters).
* **`configuration`** — Type-specific presentation settings that vary by view type. This is a discriminated union keyed on `type` — see [View configuration](#view-configuration) for the full schema per view type. This field is `null` when no custom configuration has been set.
* **`parent`** — Always a database. Views are retrieved and managed through their parent database.
* **`dashboard_view_id`** — Only present on widget views that belong to a dashboard. References the parent dashboard view's ID.
## Default behavior
When you [create a database](/reference/create-database) through the API, Notion automatically provisions:
1. One **data source** under the database container
2. One **Table view** named "Default view" over that data source
This means every newly created database is immediately usable — it has a data source to hold pages and a view to display them.
```bash cURL theme={null}
curl -X POST https://api.notion.com/v1/databases \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Content-Type: application/json" \
-H "Notion-Version: 2026-03-11" \
--data '{
"parent": { "type": "page_id", "page_id": "YOUR_PAGE_ID" },
"title": [{ "type": "text", "text": { "content": "My Database" } }],
"is_inline": false
}'
```
```javascript JavaScript theme={null}
const { Client } = require("@notionhq/client");
const notion = new Client({ auth: process.env.NOTION_API_KEY });
const database = await notion.databases.create({
parent: { type: "page_id", page_id: "YOUR_PAGE_ID" },
title: [{ type: "text", text: { content: "My Database" } }],
is_inline: false,
});
// database.data_sources[0].id is the auto-created data source
```
After creating the database, you can [list the views](#listing-views) to discover the default view, then create additional views as needed.
## Listing views
Use the [list endpoint](/reference/list-views) to discover views. You can filter by the view's parent `database_id` or by the `data_source_id` that the view references.
### By database
Pass `database_id` to list the views belonging to a specific database block.
```bash cURL theme={null}
curl -X GET "https://api.notion.com/v1/views?database_id=DATABASE_ID" \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Notion-Version: 2026-03-11"
```
```javascript JavaScript theme={null}
const response = await notion.views.list({
database_id: "DATABASE_ID",
});
for (const view of response.results) {
console.log(view.id);
}
```
### By data source
Pass `data_source_id` to list all views that reference a given data source (collection), including linked views on other pages across the workspace.
```bash cURL theme={null}
curl -X GET "https://api.notion.com/v1/views?data_source_id=DATA_SOURCE_ID" \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Notion-Version: 2026-03-11"
```
```javascript JavaScript theme={null}
const response = await notion.views.list({
data_source_id: "DATA_SOURCE_ID",
});
for (const view of response.results) {
console.log(view.id);
}
```
Results are filtered by your connection's access permissions. Views on pages the connection cannot access are excluded.
Both variants return a paginated list of view references:
```json theme={null}
{
"object": "list",
"results": [
{ "object": "view", "id": "a3f1b2c4-5678-4def-abcd-1234567890ab" },
{ "object": "view", "id": "b4e2c3d5-6789-5ef0-bcde-2345678901bc" }
],
"next_cursor": null,
"has_more": false
}
```
The list endpoint returns minimal view references (just `object` and `id`). To get full view details including filters, sorts, and configuration, retrieve each view individually.
## Retrieving a view
[Retrieve a view](/reference/retrieve-a-view) by its ID to see its full configuration, including filters, sorts, and layout settings.
```bash cURL theme={null}
curl -X GET https://api.notion.com/v1/views/VIEW_ID \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Notion-Version: 2026-03-11"
```
```javascript JavaScript theme={null}
const view = await notion.views.retrieve({
view_id: "VIEW_ID",
});
console.log(view.name); // "High priority items"
console.log(view.type); // "table"
console.log(view.configuration); // { type: "table", properties: [...], ... }
```
The response is a full [view object](#structure).
## Creating a view
Create a new view by specifying the target data source, a name, and a view type. You must also provide one of `database_id` (to create a top-level view on a database), `view_id` (to add a widget view to an existing dashboard), or `create_database` (to create a linked database view on a page). You can optionally include filters, sorts, and a [configuration](#view-configuration) object. For the full parameter reference, see [Create a view](/reference/create-view).
`database_id` and `data_source_id` are different IDs. The `database_id` is the database container's ID (the same ID returned by the [Retrieve a database](/reference/retrieve-a-database) endpoint). The `data_source_id` is the ID of a specific data source within that database (found in the database's `data_sources` array). Most databases have a single data source, but both IDs are required.
```bash cURL expandable theme={null}
curl -X POST https://api.notion.com/v1/views \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Content-Type: application/json" \
-H "Notion-Version: 2026-03-11" \
--data '{
"database_id": "DATABASE_ID",
"data_source_id": "DATA_SOURCE_ID",
"name": "Recent orders",
"type": "table",
"filter": {
"property": "Last ordered",
"date": {
"past_week": {}
}
},
"sorts": [
{
"property": "Last ordered",
"direction": "descending"
}
],
"configuration": {
"type": "table",
"properties": [
{ "property_id": "title", "visible": true, "width": 300 },
{ "property_id": "abc1", "visible": true, "width": 200 }
],
"wrap_cells": true
}
}'
```
```javascript JavaScript expandable theme={null}
const view = await notion.views.create({
database_id: "DATABASE_ID",
data_source_id: "DATA_SOURCE_ID",
name: "Recent orders",
type: "table",
filter: {
property: "Last ordered",
date: {
past_week: {},
},
},
sorts: [
{
property: "Last ordered",
direction: "descending",
},
],
configuration: {
type: "table",
properties: [
{ property_id: "title", visible: true, width: 300 },
{ property_id: "abc1", visible: true, width: 200 },
],
wrap_cells: true,
},
});
console.log(view.id); // The new view's ID
console.log(view.url); // Deep link to the view in Notion
```
The response is the newly created [view object](#structure) with all fields populated.
Views in a database can be configured to show pages from a data source that's owned by another database. In Notion, this is called a [linked database](https://www.notion.com/help/data-sources-and-linked-databases) (or linked view), and it's useful for showing the same underlying data in multiple places—for example, putting filtered views of your Tasks, Projects, and Bugs on a single dashboard page.
In the API, the main requirement is that your connection has access to both the database that owns the data source, and the database you're creating the view in.
**Filtering by multiple select or status values**
Select, status, and multi\_select filter operators accept an array of strings to filter by multiple values at once. For example, to match Priority "Low" or "Medium":
```json theme={null}
{
"filter": {
"property": "Priority",
"select": { "equals": ["Low", "Medium"] }
}
}
```
You can also exclude multiple values:
```json theme={null}
{
"filter": {
"property": "Status",
"status": { "does_not_equal": ["Done", "Archive"] }
}
}
```
The API validates each value in the array against the property's configured options. For status properties, group names (e.g. "To-do", "In progress", "Complete") are also accepted. If any value doesn't match an existing option or group, the API returns a descriptive error listing the available values.
### Required parameters
| Parameter | Description |
| ---------------- | --------------------------------------------------------------------------------------------------------------------- |
| `data_source_id` | The ID of the data source this view is over. Retrieve this from the database object's `data_sources` array. |
| `name` | A display name for the view. |
| `type` | The view layout: `table`, `board`, `list`, `calendar`, `timeline`, `gallery`, `form`, `chart`, `map`, or `dashboard`. |
### Optional parameters
| Parameter | Description |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `database_id` | The ID of the database to create the view in. Mutually exclusive with `view_id` and `create_database`. |
| `view_id` | The ID of a dashboard view to add this view to as a widget. Mutually exclusive with `database_id` and `create_database`. |
| `create_database` | Creates a linked database view on a page referencing an existing data source. See [Creating a linked database view](#creating-a-linked-database-view). Mutually exclusive with `database_id` and `view_id`. |
| `filter` | A [filter object](/reference/filter-data-source-entries) to apply. Uses the same shape as data source queries. |
| `sorts` | An array of [sort objects](/reference/sort-data-source-entries). Uses the same shape as data source queries. |
| `quick_filters` | A map of [quick filters](#quick-filters) for the view's filter bar. Keys are property names or IDs, values are filter conditions. |
| `configuration` | A [view configuration](#view-configuration) object. The `type` field inside must match the view `type`. |
| `position` | Where to place the new view in the database's view tab bar. Only applicable when `database_id` is provided. See [View positioning](#view-positioning). Defaults to appending at the end. |
| `placement` | Where to place the new widget in a dashboard layout. Only applicable when `view_id` is provided. See [Widget placement](#widget-placement). Defaults to creating a new row at the end. |
You must provide exactly one of `database_id`, `view_id`, or `create_database`. Use `database_id` to create a top-level view on a database. Use `view_id` to add a widget view to an existing dashboard — see [Dashboard views](#dashboard-views) for details. Use `create_database` to create a linked database view on a page — see [Creating a linked database view](#creating-a-linked-database-view).
**Finding the data source ID**
If you already have a database ID, call the [Retrieve a database](/reference/retrieve-database) endpoint. The response includes a `data_sources` array with each data source's `id` and `name`.
### Creating different view types
Here's an example of creating a Board view with grouping, cover images, and property configuration:
```bash cURL expandable theme={null}
curl -X POST https://api.notion.com/v1/views \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Content-Type: application/json" \
-H "Notion-Version: 2026-03-11" \
--data '{
"database_id": "DATABASE_ID",
"data_source_id": "DATA_SOURCE_ID",
"name": "Task board",
"type": "board",
"configuration": {
"type": "board",
"group_by": {
"type": "status",
"property_id": "STATUS_PROPERTY_ID",
"group_by": "group",
"sort": { "type": "manual" }
},
"cover": {
"type": "page_cover"
},
"cover_size": "medium",
"card_layout": "compact"
}
}'
```
```javascript JavaScript expandable theme={null}
const boardView = await notion.views.create({
database_id: "DATABASE_ID",
data_source_id: "DATA_SOURCE_ID",
name: "Task board",
type: "board",
configuration: {
type: "board",
group_by: {
type: "status",
property_id: "STATUS_PROPERTY_ID",
group_by: "group",
sort: { type: "manual" },
},
cover: {
type: "page_cover",
},
cover_size: "medium",
card_layout: "compact",
},
});
```
### View positioning
When creating a top-level database view (using `database_id`), you can control where it appears in the view tab bar with the `position` parameter. This is a discriminated union on the `type` field:
| Variant | Fields | Description |
| ------------ | ----------------- | --------------------------------------------------------- |
| `start` | `type` | Places the new view as the first tab. |
| `end` | `type` | Places the new view as the last tab (default). |
| `after_view` | `type`, `view_id` | Places the new view immediately after the specified view. |
```json Place at start theme={null}
{
"position": { "type": "start" }
}
```
```json Place after a specific view theme={null}
{
"position": {
"type": "after_view",
"view_id": "EXISTING_VIEW_ID"
}
}
```
The `position` parameter is only valid when `database_id` is provided. It cannot be used with `view_id` (dashboard widget creation).
### Creating a linked database view
Use the `create_database` parameter to create a lightweight linked database view on a page that references an existing data source. This creates a new database container on the target page with a single view over the specified data source — similar to inserting a "linked view of database" in the Notion UI.
This differs from `POST /v1/databases`, which creates a full standalone database with its own schema, data source, and default view. With `create_database`, the view points to an existing data source owned by another database, so no new schema is created.
```javascript JavaScript expandable theme={null}
const view = await notion.views.create({
create_database: {
parent: {
type: "page_id",
page_id: "TARGET_PAGE_ID",
},
},
data_source_id: "EXISTING_DATA_SOURCE_ID",
name: "Tasks overview",
type: "table",
});
```
```bash cURL expandable theme={null}
curl -X POST https://api.notion.com/v1/views \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Content-Type: application/json" \
-H "Notion-Version: 2026-03-11" \
--data '{
"create_database": {
"parent": {
"type": "page_id",
"page_id": "TARGET_PAGE_ID"
}
},
"data_source_id": "EXISTING_DATA_SOURCE_ID",
"name": "Tasks overview",
"type": "table"
}'
```
The `create_database` object accepts the following fields:
| Field | Required | Description |
| ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parent` | Yes | The parent page for the linked database. Must be `{ "type": "page_id", "page_id": "..." }`. |
| `position` | No | Controls where the new database block appears within the parent page. Use `{ "type": "after_block", "block_id": "..." }` to place it after a specific block. The referenced block must be a direct child of the parent page. Defaults to appending at the end. |
All view types are supported with `create_database`, including `form` views with full form configuration and `dashboard` views. Dashboard views are created with an empty layout — add widgets to them via separate `POST /v1/views` calls with `view_id`.
Your connection must have access to both the target page (where the new database container is created) and the database that owns the data source being referenced.
## Updating a view
[Update a view](/reference/update-a-view) to change its name, filters, sorts, or configuration. All fields are optional — only include the fields you want to change.
```bash cURL expandable theme={null}
curl -X PATCH https://api.notion.com/v1/views/VIEW_ID \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Content-Type: application/json" \
-H "Notion-Version: 2026-03-11" \
--data '{
"name": "Completed this month",
"filter": {
"and": [
{
"property": "Status",
"status": { "equals": "Done" }
},
{
"property": "Completed date",
"date": { "this_month": {} }
}
]
},
"sorts": [
{
"property": "Completed date",
"direction": "descending"
}
],
"configuration": {
"type": "table",
"group_by": null,
"properties": [
{ "property_id": "title", "visible": true, "width": 400 },
{ "property_id": "abc1", "visible": true },
{ "property_id": "def2", "visible": false }
]
}
}'
```
```javascript JavaScript expandable theme={null}
const updated = await notion.views.update({
view_id: "VIEW_ID",
name: "Completed this month",
filter: {
and: [
{
property: "Status",
status: { equals: "Done" },
},
{
property: "Completed date",
date: { this_month: {} },
},
],
},
sorts: [
{
property: "Completed date",
direction: "descending",
},
],
configuration: {
type: "table",
group_by: null,
properties: [
{ property_id: "title", visible: true, width: 400 },
{ property_id: "abc1", visible: true },
{ property_id: "def2", visible: false },
],
},
});
```
To clear a view's filter, sorts, or specific configuration fields, set them to `null`. See [Clearing configuration with null](#clearing-configuration-with-null) for concrete examples.
## Deleting a view
[Delete a view](/reference/delete-view) by its ID. This permanently removes the view from the database's view list.
```bash cURL theme={null}
curl -X DELETE https://api.notion.com/v1/views/VIEW_ID \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Notion-Version: 2026-03-11"
```
```javascript JavaScript theme={null}
const deleted = await notion.views.delete({
view_id: "VIEW_ID",
});
// deleted.object === "view"
// deleted.id === "VIEW_ID"
```
The response is a partial view object containing only identity fields (`object`, `id`, `parent`, and `type`). Full view details like filters, sorts, and configuration are not included since the view has been deleted.
Deleting a view cannot be undone through the API. The view will no longer appear in the database's view list.
A database must always have at least one view. Attempting to delete the last remaining view returns a `validation_error`. To remove the database entirely, set [`in_trash`](/reference/update-database#body-in-trash) to `true` via the update database endpoint instead.
## View configuration
The `configuration` field on a view object controls type-specific presentation settings — things like column widths, grouping, cover images, subtasks, and more. It is a discriminated union keyed on the `type` field, which must match the view's top-level `type`.
You can pass `configuration` when [creating](#creating-a-view) or [updating](#updating-a-view) a view. Nullable fields accept `null` to clear the setting.
### Feature support by view type
| Feature | Table | Board | Calendar | Timeline | Gallery | List | Map | Form | Chart | Dashboard |
| ------------------------------------ | -------- | ------------ | ------------ | ------------ | -------- | ---- | -------- | -------- | ------------ | --------------- |
| `properties` | Yes | Yes | Yes | Yes | Yes | Yes | Optional | - | - | - |
| `group_by` | Optional | **Required** | - | - | - | - | - | - | - | - |
| `sub_group_by` | - | Optional | - | - | - | - | - | - | - | - |
| `subtasks` | Optional | - | - | - | - | - | - | - | - | - |
| `cover` | - | Optional | - | - | Optional | - | - | - | - | - |
| `cover_size` / `cover_aspect` | - | Optional | - | - | Optional | - | - | - | - | - |
| `card_layout` | - | Optional | - | - | Optional | - | - | - | - | - |
| `date_property_id` | - | - | **Required** | **Required** | - | - | - | - | - | - |
| `end_date_property_id` | - | - | - | Optional | - | - | - | - | - | - |
| `view_range` / `show_weekends` | - | - | Optional | - | - | - | - | - | - | - |
| `preference` / `arrows_by` | - | - | - | Optional | - | - | - | - | - | - |
| `show_table` / `table_properties` | - | - | - | Optional | - | - | - | - | - | - |
| `wrap_cells` / `frozen_column_index` | Optional | - | - | - | - | - | - | - | - | - |
| `show_vertical_lines` | Optional | - | - | - | - | - | - | - | - | - |
| `height` | - | - | - | - | - | - | Optional | - | Optional | - |
| `map_by` | - | - | - | - | - | - | Optional | - | - | - |
| `is_form_closed` | - | - | - | - | - | - | - | Optional | - | - |
| `anonymous_submissions` | - | - | - | - | - | - | - | Optional | - | - |
| `submission_permissions` | - | - | - | - | - | - | - | Optional | - | - |
| `chart_type` | - | - | - | - | - | - | - | - | **Required** | - |
| `x_axis` / `y_axis` | - | - | - | - | - | - | - | - | Optional | - |
| `value` | - | - | - | - | - | - | - | - | Optional | - |
| `rows` | - | - | - | - | - | - | - | - | - | Yes (read-only) |
### Table configuration
```json theme={null}
{
"type": "table",
"properties": [...],
"group_by": { ... } | null,
"subtasks": { ... } | null,
"wrap_cells": true,
"frozen_column_index": 1,
"show_vertical_lines": true
}
```
| Field | Type | Description |
| --------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `"table"` | **Required.** Must be `"table"`. |
| `properties` | array \| null | Property visibility and display settings. See [Property configuration](#property-configuration). |
| `group_by` | object \| null | Group rows by a property. See [Group-by configuration](#group-by-configuration). Pass `null` to remove. |
| `subtasks` | object \| null | Sub-item display settings. See [Subtask configuration](#subtask-configuration). Pass `null` to reset to defaults. Use `{ "display_mode": "disabled" }` to explicitly disable. |
| `wrap_cells` | boolean | Whether to wrap cell content. |
| `frozen_column_index` | integer (>= 0) | Number of columns frozen from the left. |
| `show_vertical_lines` | boolean | Whether to show vertical grid lines between columns. |
### Board configuration
```json theme={null}
{
"type": "board",
"group_by": { ... },
"sub_group_by": { ... } | null,
"properties": [...],
"cover": { "type": "page_cover" },
"cover_size": "medium",
"cover_aspect": "cover",
"card_layout": "compact"
}
```
| Field | Type | Description |
| -------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `type` | `"board"` | **Required.** Must be `"board"`. |
| `group_by` | object | **Required.** Group-by configuration for board columns. See [Group-by configuration](#group-by-configuration). |
| `sub_group_by` | object \| null | Secondary group-by for sub-grouping within columns. Pass `null` to remove. |
| `properties` | array \| null | Property visibility on cards. See [Property configuration](#property-configuration). |
| `cover` | object \| null | Cover image source. See [Cover configuration](#cover-configuration). |
| `cover_size` | `"small"` \| `"medium"` \| `"large"` \| null | Size of the cover image on cards. |
| `cover_aspect` | `"contain"` \| `"cover"` \| null | `"contain"` fits the image; `"cover"` fills the area. |
| `card_layout` | `"list"` \| `"compact"` \| null | `"list"` shows full cards; `"compact"` shows condensed cards. |
### Calendar configuration
```json theme={null}
{
"type": "calendar",
"date_property_id": "DATE_PROPERTY_ID",
"properties": [...],
"view_range": "month",
"show_weekends": true
}
```
| Field | Type | Description |
| ------------------ | ----------------------------- | --------------------------------------------------------------------------------------------- |
| `type` | `"calendar"` | **Required.** Must be `"calendar"`. |
| `date_property_id` | string | **Required.** Property ID of the date property used to position items on the calendar. |
| `properties` | array \| null | Property visibility on calendar cards. See [Property configuration](#property-configuration). |
| `view_range` | `"week"` \| `"month"` \| null | Default calendar range. |
| `show_weekends` | boolean \| null | Whether to show weekend days. |
### Timeline configuration
```json theme={null}
{
"type": "timeline",
"date_property_id": "START_DATE_PROPERTY_ID",
"end_date_property_id": "END_DATE_PROPERTY_ID",
"properties": [...],
"show_table": true,
"table_properties": [...],
"preference": {
"zoom_level": "month",
"center_timestamp": 1706745600000
},
"arrows_by": {
"property_id": "RELATION_PROPERTY_ID"
},
"color_by": true
}
```
| Field | Type | Description |
| ---------------------- | --------------- | --------------------------------------------------------------------------------------------- |
| `type` | `"timeline"` | **Required.** Must be `"timeline"`. |
| `date_property_id` | string | **Required.** Property ID for the start date of timeline items. |
| `end_date_property_id` | string \| null | Property ID for the end date. Pass `null` to clear. |
| `properties` | array \| null | Property visibility on timeline items. See [Property configuration](#property-configuration). |
| `show_table` | boolean \| null | Whether to show the table panel alongside the timeline. |
| `table_properties` | array \| null | Property configuration for the table panel (when `show_table` is true). |
| `preference` | object \| null | Timeline display preferences. See below. |
| `arrows_by` | object \| null | Dependency arrow configuration. See below. |
| `color_by` | boolean \| null | Whether to color timeline items by a property. |
**Timeline preference object:**
| Field | Type | Description |
| ------------------ | ------- | --------------------------------------------------------------------------------------------------------------- |
| `zoom_level` | enum | **Required.** One of: `"hours"`, `"day"`, `"week"`, `"bi_week"`, `"month"`, `"quarter"`, `"year"`, `"5_years"`. |
| `center_timestamp` | integer | Timestamp in milliseconds to center the timeline on. |
**Timeline arrows\_by object:**
| Field | Type | Description |
| ------------- | -------------- | ------------------------------------------------------------------------ |
| `property_id` | string \| null | Relation property ID for dependency arrows, or `null` to disable arrows. |
### Gallery configuration
```json theme={null}
{
"type": "gallery",
"properties": [...],
"cover": { "type": "page_content" },
"cover_size": "large",
"cover_aspect": "cover",
"card_layout": "list"
}
```
| Field | Type | Description |
| -------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `type` | `"gallery"` | **Required.** Must be `"gallery"`. |
| `properties` | array \| null | Property visibility on gallery cards. See [Property configuration](#property-configuration). |
| `cover` | object \| null | Cover image source. See [Cover configuration](#cover-configuration). |
| `cover_size` | `"small"` \| `"medium"` \| `"large"` \| null | Size of the cover image on cards. |
| `cover_aspect` | `"contain"` \| `"cover"` \| null | `"contain"` fits the image; `"cover"` fills the area. |
| `card_layout` | `"list"` \| `"compact"` \| null | `"list"` shows full cards; `"compact"` shows condensed cards. |
### List configuration
```json theme={null}
{
"type": "list",
"properties": [...]
}
```
| Field | Type | Description |
| ------------ | ------------- | ------------------------------------------------------------------------------------------------ |
| `type` | `"list"` | **Required.** Must be `"list"`. |
| `properties` | array \| null | Property visibility and display settings. See [Property configuration](#property-configuration). |
### Map configuration
```json theme={null}
{
"type": "map",
"height": "medium",
"map_by": "LOCATION_PROPERTY_ID",
"properties": [...]
}
```
| Field | Type | Description |
| ------------ | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `type` | `"map"` | **Required.** Must be `"map"`. |
| `height` | `"small"` \| `"medium"` \| `"large"` \| `"extra_large"` \| null | Map display height. Pass `null` to clear. |
| `map_by` | string \| null | Property ID of the location property used to position items on the map. Pass `null` to clear. |
| `properties` | array \| null | Property visibility on map pin cards. See [Property configuration](#property-configuration). |
In responses, an additional read-only field `map_by_property_name` may be present, containing the display name of the `map_by` property.
### Form configuration
```json theme={null}
{
"type": "form",
"is_form_closed": false,
"anonymous_submissions": true,
"submission_permissions": "comment_only"
}
```
| Field | Type | Description |
| ------------------------ | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `type` | `"form"` | **Required.** Must be `"form"`. |
| `is_form_closed` | boolean \| null | Whether the form is closed for submissions. Pass `null` to clear. |
| `anonymous_submissions` | boolean \| null | Whether anonymous (non-logged-in) submissions are allowed. Pass `null` to clear. |
| `submission_permissions` | `"none"` \| `"comment_only"` \| `"reader"` \| `"read_and_write"` \| `"editor"` \| null | Permission level granted to the submitter on the created page after form submission. Pass `null` to clear. |
### Chart configuration
Chart views display database data as visual charts. The configuration uses a flat object with `chart_type` as a required discriminator. Available fields vary by chart type.
```json theme={null}
{
"type": "chart",
"chart_type": "column",
"x_axis": {
"type": "select",
"property_id": "CATEGORY_PROP_ID",
"sort": { "type": "manual" }
},
"y_axis": {
"aggregator": "sum",
"property_id": "AMOUNT_PROP_ID"
},
"color_theme": "blue",
"color_by_value": true,
"show_data_labels": true,
"height": "medium"
}
```
When `color_by_value` is enabled on a bar or column chart, each bar is shaded along a gradient based on its numeric value — higher values appear in a darker shade and lower values in a lighter shade. This is useful for quickly spotting relative magnitude across categories. Combine with `color_theme` to control the gradient's base color.
**Required fields:**
| Field | Type | Description |
| ------------ | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `"chart"` | **Required.** Must be `"chart"`. |
| `chart_type` | `"column"` \| `"bar"` \| `"line"` \| `"donut"` \| `"number"` | **Required.** The chart type: `"column"` (vertical bars), `"bar"` (horizontal bars), `"line"`, `"donut"`, or `"number"` (single value display). |
**Data configuration fields:**
Charts support two data modes: **grouped data** (aggregate values by grouping on a property) and **results** (use raw property values directly).
| Field | Type | Description |
| -------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x_axis` | object \| null | X-axis grouping configuration for column/bar/line/donut charts using grouped data. Uses the same [group-by configuration](#group-by-configuration) shape. Null when using results mode. Pass `null` to clear. |
| `y_axis` | object \| null | Y-axis [aggregation](#chart-aggregation) for column/bar/line/donut charts using grouped data. Null when using results mode. Pass `null` to clear. |
| `x_axis_property_id` | string \| null | Property ID for x-axis name values when using results (raw property values) mode. Pass `null` to clear. |
| `y_axis_property_id` | string \| null | Property ID for y-axis numeric values when using results mode. Pass `null` to clear. |
| `value` | object \| null | [Aggregation](#chart-aggregation) configuration for number charts (single value display). Pass `null` to clear. |
| `stack_by` | object \| null | Stack-by grouping configuration for stacked/grouped charts (column/bar/line only). Uses the same [group-by configuration](#group-by-configuration) shape. Pass `null` to clear. |
**Format fields (all optional, all nullable):**
| Field | Type | Description |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sort` | `"manual"` \| `"x_ascending"` \| `"x_descending"` \| `"y_ascending"` \| `"y_descending"` | Sort order for chart data. |
| `color_theme` | `"gray"` \| `"blue"` \| `"yellow"` \| `"green"` \| `"purple"` \| `"teal"` \| `"orange"` \| `"pink"` \| `"red"` \| `"auto"` \| `"colorful"` | Color theme. |
| `height` | `"small"` \| `"medium"` \| `"large"` \| `"extra_large"` | Chart height. |
| `hide_empty_groups` | boolean | Whether to hide groups with no data on the x-axis. |
| `legend_position` | `"off"` \| `"bottom"` \| `"side"` | Legend display position. `"off"` hides the legend. |
| `show_data_labels` | boolean | Whether to show data value labels on chart elements. |
| `color_by_value` | boolean | Whether to apply gradient coloring to chart elements based on their numeric value. Higher values appear in a darker shade and lower values in a lighter shade. |
| `axis_labels` | `"none"` \| `"x_axis"` \| `"y_axis"` \| `"both"` | Which axis labels to display. |
| `grid_lines` | `"none"` \| `"horizontal"` \| `"vertical"` \| `"both"` | Which grid lines to display. |
| `y_axis_min` | number \| null | Custom minimum value for the y-axis. |
| `y_axis_max` | number \| null | Custom maximum value for the y-axis. |
| `reference_lines` | array \| null | [Reference lines](#chart-reference-lines) drawn on the chart. |
| `caption` | string \| null | Text caption displayed below the chart. |
**Line-specific fields:**
| Field | Type | Description |
| --------------------- | ------- | ----------------------------------------------- |
| `cumulative` | boolean | Whether to show cumulative values. |
| `smooth_line` | boolean | Whether to use smooth curves. |
| `hide_line_fill_area` | boolean | Whether to hide the shaded area under the line. |
**Bar/column-specific fields:**
| Field | Type | Description |
| ------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `group_style` | `"normal"` \| `"percent"` \| `"side_by_side"` | How grouped/stacked bars are displayed. `"normal"` stacks values, `"percent"` normalizes to 100%, `"side_by_side"` places bars next to each other. |
**Donut-specific fields:**
| Field | Type | Description |
| -------------- | ------------------------------------------------------- | -------------------------------------- |
| `donut_labels` | `"none"` \| `"value"` \| `"name"` \| `"name_and_value"` | What to display on donut chart slices. |
**Number-specific fields:**
| Field | Type | Description |
| ------------ | ------- | -------------------------------- |
| `hide_title` | boolean | Whether to hide the title label. |
#### Chart aggregation
The `y_axis` and `value` fields use an aggregation object:
```json theme={null}
{
"aggregator": "sum",
"property_id": "AMOUNT_PROP_ID"
}
```
| Field | Type | Description |
| ------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `aggregator` | enum | **Required.** The aggregation operator. `"count"` counts all rows and does not require a `property_id`. All other operators require a `property_id`. |
| `property_id` | string | The property to aggregate on. Required for all operators except `"count"`. |
**Supported aggregation operators:** `count`, `count_values`, `sum`, `average`, `median`, `min`, `max`, `range`, `unique`, `empty`, `not_empty`, `percent_empty`, `percent_not_empty`, `checked`, `unchecked`, `percent_checked`, `percent_unchecked`, `earliest_date`, `latest_date`, `date_range`.
#### Chart reference lines
Reference lines are horizontal lines drawn at specific y-axis values for visual comparison:
```json theme={null}
{
"id": "ref-line-1",
"value": 100,
"label": "Target",
"color": "red",
"dash_style": "dash"
}
```
| Field | Type | Description |
| ------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | string | Unique identifier for the reference line. Auto-generated if omitted when creating. |
| `value` | number | **Required.** The y-axis value where the reference line is drawn. |
| `label` | string | **Required.** Label displayed alongside the reference line. |
| `color` | enum | **Required.** Color of the reference line. One of: `"gray"`, `"lightgray"`, `"brown"`, `"yellow"`, `"orange"`, `"green"`, `"blue"`, `"purple"`, `"pink"`, `"red"`. |
| `dash_style` | `"solid"` \| `"dash"` | **Required.** Line style: `"solid"` for a continuous line, `"dash"` for a dashed line. |
### Dashboard configuration
```json theme={null}
{
"type": "dashboard",
"rows": [
{
"id": "row-id-1",
"widgets": [
{ "id": "widget-id-1", "view_id": "VIEW_ID_1", "width": 6, "row_index": 0 },
{ "id": "widget-id-2", "view_id": "VIEW_ID_2", "width": 6, "row_index": 0 }
],
"height": 400
}
]
}
```
| Field | Type | Description |
| ------ | ------------- | ------------------------------------------------------------------------------------------------------- |
| `type` | `"dashboard"` | **Required.** Must be `"dashboard"`. |
| `rows` | array | **Required.** The rows that make up the dashboard layout. Each row contains one or more widget modules. |
**Dashboard row object:**
| Field | Type | Description |
| --------- | ------- | ----------------------------------- |
| `id` | string | The ID of this row module. |
| `widgets` | array | The widget modules within this row. |
| `height` | integer | Fixed height of the row in pixels. |
**Dashboard widget object:**
| Field | Type | Description |
| ----------- | ------- | -------------------------------------------------------------------------------------------------------- |
| `id` | string | The ID of this widget module. |
| `view_id` | string | The ID of the collection view rendered by this widget. |
| `width` | integer | Width of the widget in a 12-column grid (1–12). `12` means full width. |
| `row_index` | integer | The 0-based index of the row this widget belongs to. Widgets in the same row share the same `row_index`. |
Dashboard configuration is **read-only** — it is returned when retrieving a dashboard view but cannot be set directly when creating or updating a view. The layout structure is managed by creating and deleting widget views via the `view_id` parameter on the create endpoint.
### Property configuration
The `properties` array controls which database properties are visible in the view and how they are displayed. Each entry targets a single property by its ID or name.
```json theme={null}
{
"property_id": "abc1",
"visible": true,
"width": 200,
"wrap": true,
"date_format": "relative",
"time_format": "12_hour"
}
```
| Field | Type | Description |
| -------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `property_id` | string | **Required.** The property ID or property name. When a name is provided, the API resolves it to the corresponding property ID. If the string matches both a property ID and a different property's name, the ID match takes priority. |
| `visible` | boolean | Whether the property is visible in this view. |
| `width` | integer (>= 0) | Column width in pixels (table views only). |
| `wrap` | boolean | Whether to wrap content in this property cell or card. |
| `status_show_as` | `"select"` \| `"checkbox"` | How to display status properties. |
| `card_property_width_mode` | `"full_line"` \| `"inline"` | Property width mode in compact card layouts (board/gallery). |
| `date_format` | enum | Display format for date properties. One of: `"full"`, `"short"`, `"month_day_year"`, `"day_month_year"`, `"year_month_day"`, `"relative"`. |
| `time_format` | enum | Time display format for date properties. One of: `"12_hour"`, `"24_hour"`, `"hidden"`. |
### Group-by configuration
Group-by lets you organize rows or cards into sections based on a property's values. The shape varies by property type, forming a discriminated union on the `type` field.
All group-by variants share these fields:
| Field | Type | Description |
| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------- |
| `type` | string | **Required.** The property type being grouped. Determines which additional fields are available. |
| `property_id` | string | **Required.** The property ID to group by. |
| `sort` | object | **Required.** Sort order for the groups. An object with `type`: `"manual"`, `"ascending"`, or `"descending"`. |
| `hide_empty_groups` | boolean | Whether to hide groups with no items. |
The following table shows which `type` values are supported and what extra fields each variant accepts:
| `type` value(s) | Extra required fields | Extra optional fields |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| `select`, `multi_select` | — | — |
| `status` | `group_by`: `"group"` (by status group: To Do/In Progress/Done) or `"option"` (by individual option) | — |
| `person`, `created_by`, `last_edited_by` | — | — |
| `relation` | — | — |
| `date`, `created_time`, `last_edited_time` | `group_by`: `"relative"` \| `"day"` \| `"week"` \| `"month"` \| `"year"` | `start_day_of_week`: `0` (Sunday) or `1` (Monday) |
| `text`, `title`, `url`, `email`, `phone_number` | `group_by`: `"exact"` or `"alphabet_prefix"` (first letter) | — |
| `number` | — | `range_start`, `range_end`, `range_size` (>= 1) for bucket grouping |
| `checkbox` | — | — |
| `formula` | `group_by`: a nested sub-group-by object (see below) | — |
**Formula group-by** uses a nested `group_by` object that describes how to group the formula's result type. The nested object does not include `property_id` (it inherits from the parent). Supported formula result types:
| Result type | Nested `group_by` fields |
| ----------- | ------------------------------------------------------------------------------------------------------------------------- |
| `date` | `type`, `group_by` (`"relative"` \| `"day"` \| `"week"` \| `"month"` \| `"year"`), `sort`, optionally `start_day_of_week` |
| `text` | `type`, `group_by` (`"exact"` \| `"alphabet_prefix"`), `sort` |
| `number` | `type`, `sort`, optionally `range_start`, `range_end`, `range_size` |
| `checkbox` | `type`, `sort` |
```json Group by select example theme={null}
{
"type": "select",
"property_id": "PRIORITY_PROPERTY_ID",
"sort": { "type": "manual" },
"hide_empty_groups": true
}
```
```json Group by status example theme={null}
{
"type": "status",
"property_id": "STATUS_PROPERTY_ID",
"group_by": "group",
"sort": { "type": "ascending" }
}
```
```json Group by date example theme={null}
{
"type": "date",
"property_id": "DUE_DATE_PROPERTY_ID",
"group_by": "week",
"sort": { "type": "ascending" },
"start_day_of_week": 1
}
```
```json Group by formula example theme={null}
{
"type": "formula",
"property_id": "FORMULA_PROPERTY_ID",
"group_by": {
"type": "number",
"sort": { "type": "ascending" },
"range_start": 0,
"range_end": 100,
"range_size": 10
}
}
```
### Subtask configuration
Subtask (sub-item) configuration controls how parent-child relationships are displayed in table views. This uses a self-referencing relation property to establish hierarchy.
```json theme={null}
{
"property_id": "RELATION_PROPERTY_ID",
"display_mode": "show",
"filter_scope": "parents_and_subitems",
"toggle_column_id": "title"
}
```
| Field | Type | Description |
| ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `property_id` | string | Relation property ID used for parent-child nesting. |
| `display_mode` | enum | How sub-items are displayed. One of: `"show"` (hierarchical with toggles), `"hidden"` (parents with a count), `"flattened"` (sub-items with a parent indicator), `"disabled"` (no sub-item rendering). |
| `filter_scope` | enum | Which items are included when filtering. One of: `"parents"` (parent items only), `"parents_and_subitems"` (both), `"subitems"` (sub-items only). |
| `toggle_column_id` | string | Property ID of the column showing the expand/collapse toggle. |
### Cover configuration
Cover configuration controls the image displayed at the top of each card in board and gallery views.
```json theme={null}
{
"type": "page_cover",
}
```
| Field | Type | Description |
| ------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | enum | **Required.** Source of the cover image. One of: `"page_cover"` (the page's cover image), `"page_content"` (first image in page content), `"property"` (an image from a file property). |
| `property_id` | string | Property ID to use as the cover image source. Only used when `type` is `"property"`. |
### Clearing configuration with null
When updating a view, you can pass `null` for any nullable configuration field to remove that setting. Only include the fields you want to change — omitted fields are left unchanged.
Here are common scenarios:
```javascript Remove grouping from a table expandable theme={null}
// A table view currently has group_by set.
// Pass null to remove grouping and return to a flat table.
const updated = await notion.views.update({
view_id: "VIEW_ID",
configuration: {
type: "table",
group_by: null,
},
});
```
```javascript Remove cover images from a board expandable theme={null}
// A board view currently shows cover images.
// Pass null for cover-related fields to remove them.
const updated = await notion.views.update({
view_id: "VIEW_ID",
configuration: {
type: "board",
group_by: {
type: "status",
property_id: "STATUS_PROP_ID",
group_by: "group",
sort: { type: "manual" },
},
cover: null,
cover_size: null,
cover_aspect: null,
},
});
```
```javascript Disable subtasks on a table expandable theme={null}
// Explicitly disable subtask rendering on a table view.
// Note: passing subtasks: null resets to defaults (which may
// still show subtasks). Use display_mode: "disabled" instead.
const updated = await notion.views.update({
view_id: "VIEW_ID",
configuration: {
type: "table",
subtasks: { display_mode: "disabled" },
},
});
```
```javascript Remove dependency arrows from a timeline expandable theme={null}
// A timeline view currently shows dependency arrows.
// Pass null for arrows_by to remove them.
const updated = await notion.views.update({
view_id: "VIEW_ID",
configuration: {
type: "timeline",
date_property_id: "START_DATE_PROP_ID",
arrows_by: null,
},
});
```
```javascript Clear a view's filter and sorts expandable theme={null}
// Clear the top-level filter and sorts (not inside configuration).
const updated = await notion.views.update({
view_id: "VIEW_ID",
filter: null,
sorts: null,
});
```
Configuration updates use **shallow merge** — only the fields you include are changed, and omitted optional fields are preserved. The `configuration` field itself is optional (omit it to leave config unchanged). When present, you must include `type` and any fields marked as required for that view type (e.g., board views always require `group_by`, calendar/timeline views always require `date_property_id`). See [Feature support by view type](#feature-support-by-view-type) for which fields are required vs optional per view type.
## Quick filters
Quick filters appear in the view's filter bar and let users quickly toggle property-level filters without opening the full filter panel. In the API, `quick_filters` is a map where keys are property names or IDs, and values are filter conditions using the same shape as [property filters](/reference/filter-data-source-entries) but without the `property` field.
People filters accept `"me"` as a value for `contains` and `does_not_contain` to match the current user, so you can create filters like "assigned to me" without hardcoding a user ID.
### Adding quick filters on create
```javascript JavaScript expandable theme={null}
const view = await notion.views.create({
database_id: "DATABASE_ID",
data_source_id: "DATA_SOURCE_ID",
name: "Active tasks",
type: "table",
quick_filters: {
"Status": {
status: { equals: "In progress" },
},
"Priority": {
select: { equals: "High" },
},
},
});
```
### Adding or updating a quick filter
To add a new quick filter or update an existing one, include the property key with the new filter condition. Other existing quick filters are preserved.
```javascript JavaScript expandable theme={null}
const view = await notion.views.update({
view_id: "VIEW_ID",
quick_filters: {
"Assignee": {
people: { contains: "me" },
},
},
});
```
### Removing a quick filter
Set a specific quick filter to `null` to remove it from the filter bar. Other quick filters are preserved.
```javascript JavaScript expandable theme={null}
const view = await notion.views.update({
view_id: "VIEW_ID",
quick_filters: {
"Status": null,
},
});
```
### Clearing all quick filters
Set the entire `quick_filters` field to `null` to remove all quick filters from the view.
```javascript JavaScript expandable theme={null}
const view = await notion.views.update({
view_id: "VIEW_ID",
quick_filters: null,
});
```
## Dashboard views
Dashboard views let you arrange multiple widget views in a grid layout on a single database. Each widget is itself a view (table, board, list, etc.) that can reference a different data source.
### Creating a dashboard
Create a dashboard view the same way as any other view — pass `type: "dashboard"` with a `database_id`:
```bash cURL expandable theme={null}
curl -X POST https://api.notion.com/v1/views \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Content-Type: application/json" \
-H "Notion-Version: 2025-09-03" \
--data '{
"database_id": "DATABASE_ID",
"data_source_id": "DATA_SOURCE_ID",
"name": "Project overview",
"type": "dashboard"
}'
```
```javascript JavaScript expandable theme={null}
const dashboard = await notion.views.create({
database_id: "DATABASE_ID",
data_source_id: "DATA_SOURCE_ID",
name: "Project overview",
type: "dashboard",
});
console.log(dashboard.id); // The dashboard view's ID
```
### Adding widget views
To add a widget to a dashboard, create a view with `view_id` set to the dashboard's ID instead of `database_id`. Each widget can use a different `data_source_id`. Dashboards support all view types as widgets except for other dashboards (no nested dashboards).
```bash cURL expandable theme={null}
curl -X POST https://api.notion.com/v1/views \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Content-Type: application/json" \
-H "Notion-Version: 2025-09-03" \
--data '{
"view_id": "DASHBOARD_VIEW_ID",
"data_source_id": "DATA_SOURCE_ID",
"name": "Tasks by status",
"type": "board",
"configuration": {
"type": "board",
"group_by": {
"type": "status",
"property_id": "STATUS_PROPERTY_ID",
"group_by": "group",
"sort": { "type": "manual" }
}
}
}'
```
```javascript JavaScript expandable theme={null}
const widget = await notion.views.create({
view_id: "DASHBOARD_VIEW_ID",
data_source_id: "DATA_SOURCE_ID",
name: "Tasks by status",
type: "board",
configuration: {
type: "board",
group_by: {
type: "status",
property_id: "STATUS_PROPERTY_ID",
group_by: "group",
sort: { type: "manual" },
},
},
});
console.log(widget.id); // The widget view's ID
console.log(widget.dashboard_view_id); // The parent dashboard's ID
```
### Widget placement
When adding a widget to a dashboard, you can control where it appears in the layout using the `placement` parameter. This is a discriminated union on the `type` field:
| Variant | Fields | Description |
| -------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `new_row` | `type`, optional `row_index` | Creates a new row containing the widget. If `row_index` is omitted, the new row is appended at the end. If provided, the new row is inserted at that 0-based position. |
| `existing_row` | `type`, `row_index` (required) | Adds the widget side-by-side to an existing row at the specified 0-based index. Column widths are automatically redistributed. |
```json Append a new row (default) theme={null}
{
"placement": { "type": "new_row" }
}
```
```json Insert a new row at the top theme={null}
{
"placement": { "type": "new_row", "row_index": 0 }
}
```
```json Add to an existing row theme={null}
{
"placement": { "type": "existing_row", "row_index": 2 }
}
```
The `placement` parameter is only valid when `view_id` is provided (dashboard widget creation). It cannot be used with `database_id`. Each dashboard row supports a maximum of 4 widgets.
### Retrieving a dashboard
When you retrieve a dashboard view, its `configuration` contains the full layout structure — rows of widgets with their positions and sizes:
```json theme={null}
{
"object": "view",
"id": "DASHBOARD_VIEW_ID",
"type": "dashboard",
"configuration": {
"type": "dashboard",
"rows": [
{
"id": "row-1",
"widgets": [
{ "id": "widget-1", "view_id": "VIEW_ID_1", "width": 6, "row_index": 0 },
{ "id": "widget-2", "view_id": "VIEW_ID_2", "width": 6, "row_index": 0 }
]
}
]
}
}
```
Widget views include a `dashboard_view_id` field that references their parent dashboard. Their `parent.database_id` always resolves to the underlying database, even though they are positioned inside a dashboard layout.
### Deleting widget views
Delete a widget view using the standard delete endpoint. This also removes the widget from the dashboard's layout structure.
Dashboard views cannot be nested — you cannot create a dashboard widget inside another dashboard.
## Querying a view
Use a view query to fetch pages using the view's saved filter and sort configuration. This lets connections reproduce what a user sees in the Notion UI for a particular view, without needing to manually reconstruct the filter/sort logic.
View queries use a three-step pattern:
1. **Create a query** — executes the view's filters/sorts and returns the first page of results along with a `query_id`.
2. **Paginate results** — use the `query_id` to fetch additional pages from the cached result set.
3. **Delete the query** (recommended) — free the cached result set when you're done paginating.
### Step 1: Create a view query
```bash cURL theme={null}
curl -X POST https://api.notion.com/v1/views/VIEW_ID/queries \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Content-Type: application/json" \
-H "Notion-Version: 2026-03-11" \
--data '{
"page_size": 50
}'
```
```javascript JavaScript theme={null}
const query = await notion.views.queries.create({
view_id: "VIEW_ID",
page_size: 50,
});
console.log(query.id); // Query ID for pagination
console.log(query.total_count); // Total matching pages
console.log(query.results); // First page of results
console.log(query.has_more); // Whether more pages exist
```
The response includes the first page of results inline:
```json theme={null}
{
"object": "view_query",
"id": "query-id-here",
"view_id": "VIEW_ID",
"expires_at": "2026-01-20T14:37:00.000Z",
"total_count": 128,
"results": [
{ "object": "page", "id": "..." }
],
"next_cursor": "cursor-string",
"has_more": true
}
```
### Step 2: Paginate results
```bash cURL theme={null}
curl -X GET "https://api.notion.com/v1/views/VIEW_ID/queries/QUERY_ID?start_cursor=CURSOR&page_size=50" \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Notion-Version: 2026-03-11"
```
```javascript JavaScript theme={null}
const nextPage = await notion.views.queries.results({
view_id: "VIEW_ID",
query_id: "QUERY_ID",
start_cursor: "CURSOR",
page_size: 50,
});
```
### Step 3: Delete the query (recommended)
Once you've finished paginating, delete the query to free the cached result set. This is optional — queries expire automatically after approximately 15 minutes — but recommended as good practice, especially if your connection runs queries frequently.
```bash cURL theme={null}
curl -X DELETE "https://api.notion.com/v1/views/VIEW_ID/queries/QUERY_ID" \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Notion-Version: 2026-03-11"
```
```javascript JavaScript theme={null}
await notion.views.queries.delete({
view_id: "VIEW_ID",
query_id: "QUERY_ID",
});
```
The response confirms deletion:
```json theme={null}
{
"object": "view_query",
"id": "QUERY_ID",
"deleted": true
}
```
This endpoint is idempotent — calling it on an already-deleted or expired query still returns success.
**Query expiration**
Cached query results expire after a short TTL (approximately 15 minutes). If a query expires, create a new one. This caching approach provides stable pagination — results won't shift between pages due to concurrent data changes.
View queries do not support stacking additional filters or sorts on top of the saved view definition. If you need different filter/sort criteria, create a new view (or update an existing one) and query that instead.
## Permissions
View endpoints reuse existing database [connection capabilities](/reference/capabilities):
| Operation | Required capability |
| --------------------------------------- | --------------------------------------------------------------------------- |
| List views | `read_content` or `read_property` |
| Retrieve a view | `read_content` or `read_property` |
| Create a view | `insert_content`, `insert_property`, `update_content`, or `update_property` |
| Update a view | `update_content` or `update_property` |
| Delete a view | `update_content` or `update_property` |
| Query a view (create, paginate, delete) | `read_content` or `read_property` |
The connection must also have access to the parent database. If it doesn't, the API returns a `404` rather than a `403`.
## Next steps
* Explore the [database object](/reference/database) and [data source object](/reference/data-source) reference docs for the parent resources that views live under.
* Learn about [filters](/reference/filter-data-source-entries) and [sorts](/reference/sort-data-source-entries) — these shapes are shared between data source queries and view configuration.
* Review [Working with databases](/guides/data-apis/working-with-databases) for a broader overview of database concepts.
* See [Preparing your connection for users](/guides/get-started/preparing-for-users) to learn how to set up databases, views, and pages automatically when users install your connection.
# Authorization
Source: https://developers.notion.com/guides/get-started/authorization
This guide describes the authorization flows for Notion connections and personal access tokens.
## What is authorization?
Authorization is the process of granting a connection or token access to Notion data. [Internal connections](/guides/get-started/internal-connections) use a static API token, [personal access tokens](/guides/get-started/personal-access-tokens) use a user-scoped static API token, and [public connections](/guides/get-started/public-connections) use the [OAuth 2.0](https://oauth.net/2/) protocol.
## Internal connection auth flow set-up
To use an internal connection, start by creating your connection in the Developer portal.
The internal connection will be associated with the workspace of your choice. You are required to be a workspace owner to create a connection.
![]()
Once the connection is created, you can update its settings as needed under the `Configuration` tab and retrieve the installation access token in this tab.
The installation access token will be used to authenticate REST API requests. The connection sends the same token in every API request.
![]()
### Connection permissions
Before a connection can interact with your Notion workspace page(s), the page must be manually shared with the connection. To share a page with a connection, visit the page in your Notion workspace, click the ••• menu at the top right of a page, scroll down to `Add connections`, and use the search bar to find and select the connection from the dropdown list.
Once the connection is shared, you can start making API requests. If the page is not shared, any API requests made will respond with an error.
**Never share your installation access token**
Your installation access token is a secret. To keep your connection secure, never store the token in your source code or commit it in version control. Instead, read the token from an environment variable. Use a secret manager or deployment system to set the token in the environment.
[Learn more: Best Practices for Handling API Keys](/guides/get-started/handling-api-keys)
### Making API requests with an internal connection
Any time your connection interacts with your workspace, include the installation access token in the `Authorization` header with every API request. However, if you are using Notion’s [SDK for JavaScript](https://github.com/makenotion/notion-sdk-js) to interact with the REST API, the token is set once when a client is initialized.
```http HTTP theme={null}
GET /v1/pages/b55c9c91-384d-452b-81db-d1ef79372b75 HTTP/1.1
Authorization: Bearer {INTEGRATION_TOKEN}
```
```javascript JavaScript theme={null}
const { Client } = require("@notionhq/client")
// Initializing a client
const notion = new Client({
auth: process.env.NOTION_TOKEN,
})
const getUsers = async () => {
const listUsersResponse = await notion.users.list({})
}
```
If you are not using the [Notion SDK for JavaScript](https://github.com/makenotion/notion-sdk-js), also set the [`Notion-Version`](/reference/versioning) and [`Content-type`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type) headers in all of your requests, like so:
```json JSON theme={null}
headers: {
Authorization: `Bearer ${process.env.NOTION_TOKEN}`,
"Notion-Version": "2026-03-11",
"Content-Type": "application/json",
},
```
If you receive an error response from the API, check if the connection has been properly [added to the page](https://www.notion.so/help/add-and-manage-connections-with-the-api#manage-connections-in-your-workspace). If this does not solve the problem, refer to our [Status codes](/reference/status-codes) page for more information.
## Personal access token auth flow set-up
Personal access tokens (PATs) are created directly by a Notion user in the Developer portal. There is no OAuth flow and no page picker. A PAT acts as the user who created it and uses that user's permissions in the selected workspace.
Use a PAT when a script, CLI workflow, Worker, or trusted tool should act as you. Use an internal connection for team-owned workspace automations, or a public connection when other Notion users need to install your app.
PATs use the same `Authorization` header as other Notion API tokens:
```http HTTP theme={null}
GET /v1/users/me HTTP/1.1
Authorization: Bearer {PERSONAL_ACCESS_TOKEN}
Notion-Version: 2026-03-11
```
See [Personal access tokens](/guides/get-started/personal-access-tokens) for creation steps, workspace admin controls, tier defaults, and security guidance.
## Public connection auth flow set-up
A public connection can be installed in any Notion workspace within its [installation scope](/guides/get-started/public-connections#installation-scope) — either any workspace, or a specific set chosen at creation time.
Since a public connection is not tied to a single workspace with a single installation access token, public connections instead follow the [OAuth 2.0 protocol](https://oauth.net/2/) to authorize a connection to interact with a workspace.
### How to make a public connection
Navigate to the Developer portal and create a new public connection.
Fill out the form with your connection details, including your redirect URI(s) under the OAuth configuration section and the connection's [installation scope](/guides/get-started/public-connections#installation-scope) — either **Any workspace** or **Selected workspaces only**. This can't be changed after creation.
The redirect URI is the URI your users will be redirected to after authorizing the public connection. To learn more, read [OAuth’s description of redirect URIs](https://www.oauth.com/oauth2-servers/redirect-uris/).
Marketplace listing details (such as descriptions, categories, and images) are managed separately through the **Listings** section. Refer to the [List on the Marketplace](/guides/get-started/marketplace-listing) guide to learn more.
### Public connection authorization overview
Once your connection has been made public, you can update your connection code to use the public auth flow.
As an overview, the authorization flow includes the following steps. Each step will be described in more detail below.
Navigate the user to the connection’s authorization URL. This URL is provided in the Developer portal.
After the user selects which workspace pages to share, Notion redirects the user to the connection’s redirect URI and includes a `code` query parameter. The redirect URI is the one you specified in your Developer portal.
Make a `POST` request to [create an access token](/reference/create-a-token), which exchanges the temporary `code` for an access token.
The Notion API responds with an access token and some additional information.
Store the access token for future API requests. View the [API reference docs](/reference/intro) to learn about available endpoints.
### Step 1 - Navigate the user to the connection’s authorization URL
After creating a public connection in the Developer portal, access the connection’s secrets in the **Configuration** tab. Similarly to the internal connections, these values should be protected and should never be included in source code or version control.
![]()
As an example, your `.env` file using these secrets could look like this:
```shell Shell theme={null}
#.env
OAUTH_CLIENT_ID=
OAUTH_CLIENT_SECRET=
NOTION_AUTH_URL=
```
To start the authorization flow for a public connection, direct the prospective user to the authorization URL. A common pattern is to include a hyperlink in the connection app that interacts with the Notion REST API. For example, an app that lets users create Notion pages in their workspaces should send users to the authorization URL first.
The following example shows an authorization URL made available through a hyperlink:
```html HTML theme={null}
Add to Notion
```
The URL begins with `https://api.notion.com/v1/oauth/authorize` and has the following parameters:
| Parameter | Description | Required |
| :-------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `client_id` | An identifier for your connection, found in the connection settings. | ✅ |
| `redirect_uri` | The URL where the user should return after granting access. | ✅ |
| `response_type` | Always use `code`. | ✅ |
| `owner` | Always use `user`. | ✅ |
| `state` | If the user was in the middle of an interaction or operation, then this parameter can be used to restore state after the user returns. It can also be used to prevent CSRF attacks. | |
Once the authorization URL is visited, the user will be shown a prompt that varies depending on whether or not the connection comes with a Notion template option.
#### Prompt for a standard connection with no template option (Default)
In the standard connection permissions flow, a prompt describes the connection [capabilities](/reference/capabilities), presented to the user as what the connection would like to be able to do in the workspace. A user can either select pages to grant the connection access to, or cancel the request.
![]()
If the user presses **Cancel**, they will be redirected to the redirect URI with and `error` query param added.
```
www.example.com/my-redirect-uri?error=access_denied&state=
```
You can use this `error`query parameter to conditionally update your app’s state as needed.
If the user opts to `Select pages`, then a page picker interface opens. A user can search for and select pages and databases to share with the connection from the page picker.
The page picker only displays pages or databases to which a user has [full access](https://www.notion.so/help/sharing-and-permissions), because a user needs full access to a resource in order to be able to share it with a connection.
![]()
Users can select which pages to give the connection access to, including both private and public pages available to them. Parent pages can be selected to quickly provide access to child pages, as giving access to a parent page will provide access to all available child pages. Users can return to this view at a later time to update access settings if circumstances change.
If the user clicks `Allow access`, they are then redirected to the `redirect_uri` with a temporary authorization `code`. If the user denies access, they are redirected to the `redirect_uri` with an `error` query parameter.
If the user clicks `Allow access` and the rest of the auth flow is not completed, the connection will *not* have access to the pages that were selected.
#### Prompt for a connection with a Notion template option
Public connections offer the option of providing a public Notion page to use as a template during the auth flow.
To add a template to your workspace, complete the following steps:
* Choose a public page in your workspace that you want users to be able to duplicate.
* Navigate to your connection in the Developer portal and open the **Configuration** tab, then scroll to the Basic information section.
* Scroll to the bottom of your distribution settings and add the URL of the Notion page you selected to the **Notion URL for optional template** input.
![]()
Once this URL is added, your auth flow prompt appearance will be updated.
Going back to your prompt view, if the connection offers a Notion template option, the first step in the permissions flow will describe the connection [capabilities](/reference/capabilities). This is presented to the user as what the connection would be able to do in the workspace, and it prompts the user to click `Next`.
![]()
In the next step, a user can either choose to duplicate the template that you provided or to select existing pages to share with the connection.
![]()
If the user chooses to duplicate the template, then the following happens automatically:
* The connection is added to the user’s workspace.
* The template is duplicated as a new page in the workspace.
* The new page is shared with the connection.
If the user chooses to select pages to share with the connection, then they continue to the page picker interface that’s part of the [prompt for a standard connection](#prompt-for-a-standard-connection-with-no-template-option-default).
After a user authorizes a public connection, only that user is able to interact or share pages and databases with the connection. Unlike internal connections, if multiple members in a workspace want to use a public connection, each prospective user needs to individually follow the auth flow for the connection.
**User authorization failures**
User authorization failures can happen. If a user chooses to `Cancel` the request, then a failure is triggered. Build your connection to handle these cases gracefully, as needed.
In some cases, Notion redirects the user to the `redirect_uri` that you set up when you created the public connection, along with an `error` query parameter. Notion uses the common [error codes in the OAuth specification](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1). Use the `error` code to create a helpful prompt for the user when they’re redirected here.
### Step 2 - Notion redirects the user to the connection’s redirect URI and includes a `code` parameter
When you first created the public connection, you specified a redirect URI. If the user follows the prompt to `Allow access` for the connection, then Notion generates a temporary `code` and sends a request to the redirect URI with the following information in the query string:
| Parameter | Description | Required |
| :-------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `code` | A temporary authorization code. | ✅ |
| `state` | The value provided by the connection when the user was [prompted for access](#prompt-for-a-standard-connection-with-no-template-option-default). | |
To complete the next step, retrieve the `code` query parameter provided in the redirect. The retrieval method varies depending on your app’s tech stack.
In a React component, for example, the query parameters are made available through the `useRouter()` hook:
```javascript JavaScript theme={null}
export default function AuthRedirectPage() {
const router = useRouter();
const { code } = router.query;
...
}
```
### Step 3 - Send the `code` in a `POST` request to the Notion API
The connection needs to exchange the temporary `code` for an `access_token`.
To set up this step, retrieve the `code` from the redirect URI.
Next, send the `code` as part of a `POST` request to Notion’s token endpoint: [https://api.notion.com/v1/oauth/token](https://api.notion.com/v1/oauth/token).
This endpoint is described in more detail in the API reference docs for [creating a token](/reference/create-a-token).
The request is authorized using HTTP Basic Authentication. The credential is a colon-delimited combination of the connection’s `CLIENT_ID` and `CLIENT_SECRET`, like so:
```bash theme={null}
CLIENT_ID:CLIENT_SECRET
```
Find both of these values in the Developer portal.
Note that in [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication), credentials are `base64` encoded before being added to the `Authorization` header.
The body of the request contains the following JSON-encoded fields:
| Field | Type | Description | Required |
| :--------------- | :------- | :----------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"grant_type"` | `string` | Always use `"authorization_code"`. | ✅ |
| `"code"` | `string` | The temporary authorization code received in the incoming request to the `"redirect_uri"`. | ✅ |
| `"redirect_uri"` | `string` | The `"redirect_uri"` that was provided in the Authorization step. | ✅/❌\*
\* If the redirect URI was supplied as a query param in the Authorization URL, this field is required. If there are more than one redirect URIs included in your connection settings, this field is required. Otherwise, it is not allowed. Learn more in the [Create a token page](/reference/create-a-token). |
The following is an example request to exchange the authorization code for an access token:
```http HTTP theme={null}
POST /v1/oauth/token HTTP/1.1
Authorization: Basic "$CLIENT_ID:$CLIENT_SECRET"
Content-Type: application/json
{"grant_type":"authorization_code","code":"e202e8c9-0990-40af-855f-ff8f872b1ec6", "redirect_uri":"https://example.com/auth/notion/callback"}
```
The Node-equivalent of this example would look something like this:
```javascript JavaScript theme={null}
...
const clientId = process.env.OAUTH_CLIENT_ID;
const clientSecret = process.env.OAUTH_CLIENT_SECRET;
const redirectUri = process.env.OAUTH_REDIRECT_URI;
// encode in base 64
const encoded = btoa(`${clientId}:${clientSecret}`);
const response = await fetch("https://api.notion.com/v1/oauth/token", {
method: "POST",
headers: {
Accept: "application/json",
"Content-Type": "application/json",
Authorization: `Basic ${encoded}`,
},
body: JSON.stringify({
grant_type: "authorization_code",
code: "your-temporary-code",
redirect_uri: redirectUri,
}),
});
...
```
### Step 4 - Notion responds with an `access_token` , `refresh_token`, and additional information
Notion responds to the request with an `access_token`, `refresh_token`, and additional information. The `access_token` will be used to authenticate subsequent Notion REST API requests. The `refresh_token` will be used to refresh the access token, which generates a new `access_token`.
The response contains the following JSON-encoded fields:
| Field | Type | Description | Not null |
| :------------------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `"access_token"` | `string` | An access token used to authorize requests to the Notion API. | ✅ |
| `"refresh_token"` | `string` | A refresh token used to generate a new access token | ✅ |
| `"bot_id"` | `string` | An identifier for this authorization. | ✅ |
| `"duplicated_template_id"` | `string` | The ID of the new page created in the user’s workspace. The new page is a duplicate of the template that the developer provided with the connection. If the developer didn’t provide a template for the connection, then the value is `null`. | |
| `"owner"` | `object` | An object containing information about who can view and share this connection. A [user object](/reference/user) is returned, representing the user who authorized the connection. | ✅ |
| `"workspace_icon"` | `string` | A URL to an image that can be used to display this authorization in the UI. | |
| `"workspace_id"` | `string` | The ID of the workspace where this authorization took place. | ✅ |
| `"workspace_name"` | `string` | A human-readable name that can be used to display this authorization in the UI. | |
**Token request failures**
If something goes wrong when the connection attempts to exchange the `code` for an `access_token`, then the response contains a JSON-encoded body with an `"error"` field. Notion uses the common [error codes from the OAuth specification](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2).
### Step 5 - The connection stores the `access_token` and `refresh_token` for future requests
Set up a way for your connection to store both the `access_token` and `refresh_token` that it receives. The `access_token` is used to make authorized requests to the Notion API, and the `refresh_token` is used to generate a new `access_token`.
**Tips for storing and using token access**
* Setting up a database is a typical solution for storing access tokens. If you’re using a database, then build relations between an `access_token`, `refresh_token`, and the corresponding Notion resources that your connection accesses with that token. For example, if you store a Notion database or page ID, relate those records with the correct `access_token` that you use to authorize requests to read or write to that database or page, and the `refresh_token` for ongoing token lifecycle support..
* Store all of the information that your connection receives with the `access_token` and `refresh_token`. You never know when your UI or product requirements might change and you’ll need this data. It's really hard (or impossible) to send users to repeat the authorization flow to generate the information again.
* The `bot_id` returned along with your tokens should act as your primary key when storing information.
### Step 6 - Refreshing an access token
Refreshing an access token will generate a new access token and a new refresh token.
Send the `refresh_token` provided from [Step 4](#step-4-notion-responds-with-an-access_token-refresh_token-and-additional-information) as part of a `POST` request to Notion’s token endpoint: [https://api.notion.com/v1/oauth/token](https://api.notion.com/v1/oauth/token).
This endpoint is described in more detail in the API reference docs for [refreshing a token](/reference/refresh-a-token).
The request is authorized using HTTP Basic Authentication. The credential is a colon-delimited combination of the connection’s `CLIENT_ID` and `CLIENT_SECRET`, like so:
```bash theme={null}
CLIENT_ID:CLIENT_SECRET
```
Find both of these values in the Developer portal.
Note that in [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication), credentials are `base64` encoded before being added to the `Authorization` header.
The body of the request contains the following JSON-encoded fields:
| Field | Type | Description | Required |
| :---------------- | :------- | :-------------------------------------------------------- | :------- |
| `"grant_type"` | `string` | Always use `"refresh_token"`. | ✅ |
| `"refresh_token"` | `string` | The `"refresh_token"` returned in the Authorization step. | ✅ |
The following is an example request to exchange the `refresh_token` for a new access token and new refresh token
```http HTTP theme={null}
POST /v1/oauth/token HTTP/1.1
Authorization: Basic "$CLIENT_ID:$CLIENT_SECRET"
Content-Type: application/json
{"grant_type":"refresh_token","refresh_token":"nrt_4991090011501Ejc6Xn4sHguI7jZIN449mKe9PRhpMfNK"}
```
The Node-equivalent of this example would look something like this:
```javascript JavaScript theme={null}
...
const clientId = process.env.OAUTH_CLIENT_ID;
const clientSecret = process.env.OAUTH_CLIENT_SECRET;
// encode in base 64
const encoded = btoa(`${clientId}:${clientSecret}`);
const response = await fetch("https://api.notion.com/v1/oauth/token", {
method: "POST",
headers: {
Accept: "application/json",
"Content-Type": "application/json",
Authorization: `Basic ${encoded}`,
},
body: JSON.stringify({
grant_type: "refresh_token",
refresh_token: "your-refresh-token",
}),
});
...
```
# Best practices for handling API keys
Source: https://developers.notion.com/guides/get-started/handling-api-keys
Learn how to manage and secure your Notion API tokens.
API keys are powerful credentials that provide access to Notion through our Public API. This guidance applies to internal connection tokens, OAuth access tokens, and [personal access tokens](/guides/get-started/personal-access-tokens). If these keys fall into the wrong hands, they can pose serious security risks to your connections, data, and workspace.
## Why leaked API keys are dangerous
When your Notion API key is exposed, malicious actors could potentially:
* **Access sensitive data**: Read all pages, databases, and content in your workspace
* **Modify or delete content**: Make unauthorized changes to your workspace data
* **Export your data**: Download and steal your intellectual property
* **Perform actions on your behalf**: Create, update, or delete pages and databases
* **Access user information**: View workspace members and their permissions
The scope of access depends on the permissions granted to the connection or token. For PATs, the token acts as the user who created it, so leaked PATs can expose anything that user can access with the token's capabilities.
## Best practices
### *NEVER* share your API keys
* Keep your API key private: Treat your API key like your personal password—don’t share it with anyone. If others need access, they should request their own key or create their own PAT.
* Never post your key publicly: Avoid sharing your API key in public spaces such as forums, emails, or support tickets, with the Notion support team.
* Be careful with third-party tools: Uploading your API key to external services will provide your key to those services. Only share your key with trusted services. Always store your API key as an encrypted secret when working with third-party platforms. Never put your key directly into code or configuration files - use environment variables!
### Use environment variables
Never hardcode API keys directly in your source code. Instead, use environment variables:
```bash theme={null}
# .env file (never commit this file)
NOTION_API_KEY=ntn_abc123def456ghi789jkl012mno345pqr
```
```typescript TypeScript theme={null}
// In your code
const notion = new Client({
auth: process.env.NOTION_API_KEY,
});
```
### Secure your environment files
* Add `.env` files to your `.gitignore` to prevent accidental commits
* Use different API keys for development, staging, and production environments
* Store production keys in secure secret management systems like AWS Secrets Manager, Azure Key Vault, or HashiCorp Vault
### Implement secret scanning
Use tools like [GitLeaks](https://github.com/gitleaks/gitleaks), [Detect Secrets](https://github.com/Yelp/detect-secrets), [Trufflehog](https://github.com/trufflesecurity/trufflehog), or [BitPatrol](https://bitpatrol.io/) to automatically detect and prevent the commitment of sensitive information like API keys to your repositories. These tools can:
* Scan your codebase for potential secrets before commits
* Integrate with CI/CD pipelines for continuous scanning
* Alert developers when secrets are accidentally committed
### Regular key rotation
* Rotate API keys on a schedule and set calendar reminders to do so. PATs expire one year after creation, so plan replacements before they expire.
* Immediately rotate keys when team members with access leave
* Keep an inventory of all API keys and their purposes
## What should I do if I suspect my API key has been compromised?
If you suspect that your API key may be compromised, we recommend taking action immediately:
### Step 1 - Revoke the compromised key
Log into your Notion account
Go to **Settings & members** → **Connections** → **Develop or manage connections**
Find the connection or personal access token with the compromised key
Click **Refresh** on your connection, or revoke the personal access token
### Step 2 - Generate a new API key
Rotate the compromised key by clicking **Refresh** in your connections page and update your applications with your new key. For a compromised PAT, revoke the old token and create a new PAT.
![]()
### Step 3 - review recent activity
Check your workspace for any suspicious activity
Review recent changes to pages and databases
Look for any unauthorized connections in **Settings & members** → **Connections**
### Step 4 - update your applications
* Replace the old API key in all your applications and environments
* Test that your connections are working with the new key
* Remove the old key from any configuration files or documentation
## Getting help
If you need assistance with API key security or suspect unauthorized access, contact [Notion support](https://www.notion.com/help) at [team@makenotion.com](mailto:team@makenotion.com)
# Internal connections
Source: https://developers.notion.com/guides/get-started/internal-connections
Learn how internal connections work, how permissions are managed, and how to create one.
## What is an internal connection?
An internal connection is scoped to a single Notion workspace. Only members of that workspace can use it. Internal connections are ideal for team-owned automations and workflows — things like syncing data from external tools, sending notifications when pages change, or powering internal dashboards.
Internal connections use a static API token for authentication. There's no OAuth flow to implement — you get a token immediately when you create the connection, and you use that same token for every API request.
If you want a token that acts as your own Notion user for a script, CLI workflow, Worker, or trusted tool, use a [personal access token](/guides/get-started/personal-access-tokens) instead. PATs use the creator's page permissions instead of a separate bot's page permissions.
In this guide, you'll learn:
* How internal connection permissions work (and how they differ from public connections)
* How to create an internal connection and share pages with it
* How to authenticate API requests using your installation access token
## How permissions work
An internal connection operates as its own **bot user**. It is not tied to any specific workspace member. This means:
* **Permissions belong to the connection, not to a person.** When a page is shared with the connection, the connection itself has access — regardless of which workspace member shared it.
* **Access is inherited.** Sharing a parent page with the connection grants access to all of its child pages as well.
* **Access persists independently of users.** If the user who shared a page leaves the workspace, the connection retains access to that page.
* **Any Workspace Owner can see the connection.** All internal connections are visible in the Developer portal to every Workspace Owner in the workspace, including connections created by others.
This is one of the biggest differences from [public connections](/guides/get-started/public-connections), where the connection acts on behalf of the individual user who authorized it, and [personal access tokens](/guides/get-started/personal-access-tokens), which act as the user who created the token.
## Creating an internal connection
You must be a [Workspace Owner](https://www.notion.so/help/add-members-admins-guests-and-groups) to create a connection.
Navigate to the Developer portal.
In the **Build** section of the sidebar, select **Internal connections**.
Click **Create a new connection**, enter a connection name, and choose the workspace where the connection can be installed.
![]()
After creation, visit the **Configuration** tab to retrieve your **Installation access token**.
![]()
You can also configure the connection's [capabilities](/reference/capabilities) — such as whether it can read content, update content, insert content, or read user information — from the **Configuration** tab.
## Granting page access
Before your connection can access any data, it must be explicitly granted access to pages or databases. There are two ways to do this.
### From the Developer portal
The connection owner can manage access directly from the **Content access** tab in the Developer portal. This is the quickest way to get started after creating a connection.
Open your connection in the Developer portal.
Click the **Content access** tab.
Click **Edit access**, then select the pages and databases you want the connection to access.
### From the Notion UI
Workspace members can also share individual pages with the connection from within Notion.
Open a Notion page you want the connection to access.
Click the **•••** menu in the top-right corner of the page.
Select **Connections**, then click **+ Add connection**.
Search for your connection and select it.
Confirm the connection can access the page and all of its child pages.
**Your connection needs page access to make API requests**
A newly created connection has no page access by default. If you skip this step, any API request will return an error. Use the **Content access** tab or **Add connections** menu to grant access before making requests.
## Authentication
Internal connections authenticate every API request using the API token retrieved from the **Configuration** tab. Include the token in the `Authorization` header:
```http HTTP theme={null}
GET /v1/pages/b55c9c91-384d-452b-81db-d1ef79372b75 HTTP/1.1
Authorization: Bearer {INTEGRATION_TOKEN}
```
If you're using the [Notion SDK for JavaScript](https://github.com/makenotion/notion-sdk-js), the token is set once when initializing the client:
```javascript JavaScript theme={null}
const { Client } = require("@notionhq/client")
const notion = new Client({
auth: process.env.NOTION_TOKEN,
})
```
**Keep your token secret.** Never store the token in source code or commit it to version control. Use environment variables or a secret manager instead. If your token is accidentally exposed, you can refresh it from the connection's **Configuration** tab.
[Learn more: Best practices for handling API keys](/guides/get-started/handling-api-keys)
For the full details on internal connection authentication, see the [Authorization guide](/guides/get-started/authorization#internal-connection-auth-flow-set-up).
## Next steps
Build your first connection with a hands-on tutorial.
Explore all available endpoints.
# List on the Marketplace
Source: https://developers.notion.com/guides/get-started/marketplace-listing
Learn how to list your public connection on the Notion Marketplace.
The [Notion Marketplace](https://www.notion.so/integrations/all) is how Notion users discover and connect public connections. Listing your connection there puts it in front of every Notion user — and it's a separate step from building the connection itself, so you can ship whenever you're ready.
This guide assumes you already have a public connection. If you haven't created one yet, see the [Public connections](/guides/get-started/public-connections) guide first.
This guide covers how to:
* Start a new Marketplace listing
* Submit your listing for review
* Understand the review process and timeline
Only public connections with an installation scope of **Any workspace** can be listed on the Marketplace. Internal connections and **Selected workspaces only** public connections are not eligible. Installation scope is set when the connection is created and can't be changed afterward — see [Installation scope](/guides/get-started/public-connections#installation-scope).
## Start a new listing
Navigate to the Marketplace listing dashboard.
In the **Listings** section of the sidebar, select **Connections**.
Under **Drafts**, click **Start a new connection listing**.
Fill in the listing details, including:
* Listing name and description
* Category and tags
* Listing images and logo
* The public connection to associate with this listing
Save your listing as a draft. You can return to edit it at any time before submitting.
## Submit for review
When your listing is ready, submit it for review from the **Connections** listing page.
From the **Listings > Connections** page, find your draft listing.
Review all listing details to ensure they are complete and accurate.
Submit your listing for review by the Notion team.
After submission, your listing moves to the **Submitted** section where you can track its review status.
## Review process
The Notion team reviews every listing submission. Track the status of your submission from the **Listings > Connections** page in the Marketplace listing dashboard. See the [FAQ](#frequently-asked-questions) below for review timelines.
If approved, the listing appears in the [Notion Marketplace](https://www.notion.so/integrations/all). If changes are required, the Notion team sends feedback and you can resubmit after making updates.
## Connection gallery best practices
For guidance on the review process and best practices to get your connection approved, check out the [Notion Connection Gallery Best Practices](https://www.notion.so/notiondevs/Notion-Integration-Gallery-Best-Practices-997825927fd6473e89617ce0c329145c?pvs=4) guide.
## Frequently asked questions
After submission, expect to hear back from our team within 5-10 business days via email. Check the status of your connection submission from the **Listings > Connections** page in the Marketplace listing dashboard.
The Notion team sends an email explaining why your listing was not approved. Check the status from the **Listings > Connections** page.
Connections are rejected for various reasons, from brand/trademark issues to quality concerns to situations where the baseline connection criteria isn't met. We encourage developers to review our feedback, make necessary changes, and resubmit. Our goal is to help you create high-quality and valuable tools for the Notion community.
No. Public connections work independently of Marketplace listings. Listing on the Marketplace is optional and helps your connection reach a wider audience, but your connection can be used via its OAuth flow without being listed.
# Overview
Source: https://developers.notion.com/guides/get-started/overview
Discover what Notion connections are, when to use each type, and what you can build.
## Using the Notion API
Notion connections let you connect your workspace to external tools and automate workflows through code. With the REST API, you can read, create, and update nearly everything in a workspace — pages, databases, users, comments, and more.
When you create a connection, you define what it can do: which API endpoints it can call, what content it can read or write, and how it authenticates. Each connection gets its own credentials and its own set of permissions.
## What is a Notion connection?
A Notion [connection](https://www.notion.so/help/add-and-manage-connections-with-the-api) — sometimes called an integration — connects your workspace to external apps and tools. That could be a SaaS product, an automation script, or a custom tool you've built.
Connections are added to Notion workspaces and require **explicit permission** from users to access Notion pages and databases.
![]()
Notion already has a [library](https://www.notion.so/integrations/all) of connections you can browse. For developers who want to build their own, Notion supports internal connections, public connections, and personal access tokens — all powered by the same REST API.
## Connection types
Notion supports three authentication models:
* **Internal connections** are scoped to a single workspace and use a static API token. They're ideal for custom automations and workflows — things like syncing data, sending notifications, or building internal dashboards.
* **Public connections** use OAuth 2.0 for authentication. At creation time, you choose their [installation scope](/guides/get-started/public-connections#installation-scope): **Any workspace** (any Notion user can install; Marketplace-eligible) or **Selected workspaces only** (restricted to workspaces you select; not Marketplace-eligible).
* **Personal access tokens (PATs)** are user-scoped tokens for scripts, CLI workflows, Workers, and tools that should act as one Notion user. A PAT uses the creator's workspace membership and page permissions. See [Personal access tokens](/guides/get-started/personal-access-tokens).
Public connections must undergo a Notion security review before being [listed on the Marketplace](/guides/get-started/marketplace-listing). You can create and use a public connection without listing it.
### Comparison
| Feature | Internal connections | Public connections | Personal access tokens |
| :----------------- | :----------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------- |
| Best for | Team-owned automations in one workspace. | Apps or services used by many Notion users or workspaces. | User-owned scripts, CLI workflows, Workers, and trusted tools. |
| Installation scope | Single workspace. | Any workspace, or a specific set of workspaces chosen at creation time. Scope can't change after creation. | One user in one workspace. |
| User access | Only members of the workspace where it's installed. | Any user in a workspace where the connection is allowed to install. | The member who created the token. |
| Content access | Granted directly to the connection, not tied to any specific user. | Users choose which pages to share during the OAuth flow or via the Add connections menu. | Uses the creator's Notion permissions; pages do not need to be shared with a bot. |
| Authentication | Static API token. | OAuth 2.0. | Static bearer token. |
**Looking for SCIM or SAML SSO?**
Enterprise identity management (user provisioning, group management, and Single Sign-On) is covered in Notion's Help Center, not in these API docs.
## Shared concepts
All connection and token types share a few core concepts.
### Capabilities
Every connection or token has a set of capabilities that control what it can do — read content, update content, insert content, read comments, and more. You configure capabilities when you create a connection or PAT. See the [Capabilities reference](/reference/capabilities) for the full list.
Create, update, and retrieve page content.
Manage database, properties, entries, and schemas.
Create and configure database views programmatically.
Manage data sources, properties, entries, and schemas.
Upload and attach files to pages and databases.
Handle page and inline comments.
Search through workspace content.
Access user profiles and permissions.
### Content access
Connections must have access to pages and databases before they can interact with them. The mechanism differs by type:
* **Internal connections** can be granted access in two ways: the connection owner can add pages directly from the **Content access** tab in the Developer portal, or workspace members can share pages via the **Add connections** menu in Notion.
* **Public connections** use the OAuth page picker, where users select which pages to grant access to during the authorization flow.
* **Personal access tokens** use the token creator's existing Notion permissions. If the creator can access a page in Notion, a PAT with the right capabilities can access it through the API.
See the [Internal connections](/guides/get-started/internal-connections), [Public connections](/guides/get-started/public-connections), and [Personal access tokens](/guides/get-started/personal-access-tokens) guides for specifics on how content access works for each type.
### Webhooks
Connections can subscribe to real-time events — like page updates, property changes, and new comments — via webhooks. This allows your connection to react to changes in Notion without polling the API. See the [Webhooks guide](/reference/webhooks) for details on setting up webhook subscriptions.
## Starting your connection journey
We recommend starting with an internal connection — it's the fastest way to begin building. You get an API token immediately and can focus entirely on using the API within your workspace, without worrying about OAuth or Marketplace listing. You can always create a public connection later if you need multi-workspace support.
Here's a guided path through the documentation:
[**Quickstart**](/guides/get-started/quick-start) — Build your first connection with a hands-on tutorial.
[**Personal access tokens**](/guides/get-started/personal-access-tokens) — Create a user-scoped token for scripts, CLI workflows, Workers, or trusted tools.
[**Internal connections**](/guides/get-started/internal-connections) — Understand how internal connections work, including the permissions model.
[**Public connections**](/guides/get-started/public-connections) — Learn how public connections work, including installation scope and the OAuth flow.
[**Authorization**](/guides/get-started/authorization) — Implement the OAuth 2.0 flow for public connections.
[**Handling API keys**](/guides/get-started/handling-api-keys) — Secure and manage your API tokens in production.
[**Preparing for users**](/guides/get-started/preparing-for-users) — Set up databases, pages, and views automatically when users install your connection.
[**List on the Marketplace**](/guides/get-started/marketplace-listing) — Make your public connection discoverable to all Notion users.
## Resources
Explore the links below to get started, and join the [Notion Devs Slack community](https://join.slack.com/t/notiondevs/shared_invite/zt-3u9oid9q8-HLUBmMVWYK~g9HFo4U4raA) to share your projects and connect with fellow developers.
# Personal access tokens
Source: https://developers.notion.com/guides/get-started/personal-access-tokens
Create and use personal access tokens for user-scoped API and Workers access.
Personal access tokens (PATs) are user-scoped bearer tokens. A PAT belongs to one Notion user in one workspace, and it uses that user's workspace membership and page permissions when it calls the Notion API.
PATs are useful when you want to authenticate as yourself without creating an [internal connection](/guides/get-started/internal-connections) or implementing the [OAuth flow for a public connection](/guides/get-started/public-connections).
## When to use a PAT
Use a PAT for personal or developer-owned workflows where one Notion user is the right security boundary:
* Local scripts, notebooks, and command-line tools that automate work in your own workspace.
* Development and testing against the Notion API before you create a shared connection.
* Third-party tools that ask you to paste a Notion token and should act with your Notion permissions.
* [Notion Workers](/workers/get-started/overview) development and deployment with the Notion CLI.
Do not use a PAT as the auth model for a product used by many Notion users. For that, create a [public connection](/guides/get-started/public-connections) so each user authorizes access with OAuth. If you need a stable workspace-level bot for a team-owned automation, use an [internal connection](/guides/get-started/internal-connections).
## How PATs work
A PAT is created in the Developer portal. When you create one, you choose:
* A token name.
* The workspace the token belongs to.
* Capabilities for the token.
PATs can have two capability bundles:
| Capability | What it allows |
| :------------- | :--------------------------------------------------------------------------------------------------------------------------------- |
| **Notion API** | Read, create, update, and search content; read and create comments; and read supported user information through Notion's REST API. |
| **Workers** | Deploy and manage [Notion Workers](/workers/get-started/overview) with the Notion CLI. |
The Notion API capability is controlled by the workspace's PAT creation policy. The Workers capability can be granted to workspace members, but Workers feature availability is still checked when you use Workers.
PATs authenticate requests the same way other Notion API tokens do:
```http HTTP theme={null}
GET /v1/users/me HTTP/1.1
Authorization: Bearer {PERSONAL_ACCESS_TOKEN}
Notion-Version: 2026-03-11
```
```javascript JavaScript theme={null}
const { Client } = require("@notionhq/client")
const notion = new Client({
auth: process.env.NOTION_PAT,
})
```
## Permissions and content access
A PAT acts as the user who created it:
* It can access pages, data sources, databases, comments, files, and other resources that the creator can access.
* It does not need pages to be shared with a bot through **Add connections**.
* If the creator loses access to a page or leaves the workspace, the PAT loses that access too.
* API behavior that depends on an authenticated user, such as `"me"` filters or workspace-level private page creation, uses the PAT creator.
PATs are intentionally different from internal connections. An internal connection operates as a separate bot user and only accesses pages explicitly shared with that connection. A PAT uses a real user's permissions, so it is best for user-owned workflows rather than team-owned automations.
[List all users](/reference/get-users) is not available to PATs. A PAT can use [Retrieve token's bot user](/reference/get-self) to retrieve the authorized user, and [Retrieve a user](/reference/get-user) can retrieve that same user.
## Workspace admin controls
Workspace admins can manage PATs from **Settings & members → Connections**:
* View all PATs created in the workspace, including active and revoked tokens.
* Search and filter tokens by name, creator, and status.
* See who created a token and, for revoked tokens, who revoked it.
* Revoke active PATs.
* Configure who can create PATs with Notion API access.
Admins cannot reveal or copy another member's token secret. Only the token creator can reveal or copy their own PAT.
If an admin changes the workspace policy so a member is no longer allowed to create PATs with Notion API access, that member's existing PATs stop working for Notion API requests. Those requests return an `unauthorized` error until the policy allows the member again or the member uses a different valid token.
### Who can create PATs
[Guests and restricted members](https://www.notion.com/help/whos-who-in-a-workspace) cannot create PATs or log in with the Notion CLI (`ntn login`). Only full workspace members can create tokens, subject to the workspace's PAT creation policy below. Workspace owners can always create PATs with Notion API access.
| Plan | Default PAT creation policy | Admin controls |
| :--------- | :------------------------------------ | :------------------------------------------------------------------------------------------------------------------- |
| Free | Workspace owners only. | Not configurable. |
| Plus | All workspace members. | Not configurable. |
| Business | Workspace owners only. | Admins can choose **Workspace owners only** or **All workspace members**. |
| Enterprise | Workspace owners and selected groups. | Admins can choose **Workspace owners only**, **Workspace owners and selected groups**, or **All workspace members**. |
On Enterprise, selected groups are managed from the PAT creators settings page. If no groups are selected, workspace owners are the only users who can create PATs with Notion API access.
## Create a PAT
Open the Developer portal.
Go to Personal access tokens.
Click **New personal access token**.
Enter a name, choose a workspace, and select the capabilities the token should have.
Click **Create token**, then copy the token value and store it securely.
PATs expire one year after creation. Create a new PAT and update your scripts or tools before the old token expires.
## Revoke a PAT
Revoke a PAT immediately if it is exposed, no longer needed, or associated with a tool you no longer trust.
* Token creators can revoke their own PATs from the Developer portal.
* Workspace admins can revoke any PAT in their workspace from **Settings & members → Connections → All personal access tokens**.
After revocation, the token immediately stops working for scripts, tools, Workers, and API requests that use it.
## Security best practices
Treat PATs like passwords:
* Store PATs in environment variables or a secret manager.
* Do not commit PATs to source control.
* Use a separate PAT per script, tool, or environment so you can revoke one token without breaking unrelated workflows.
* Grant only the capabilities the workflow needs.
* Revoke tokens you no longer use.
For more guidance, see [Best practices for handling API keys](/guides/get-started/handling-api-keys).
# Preparing your connection for users
Source: https://developers.notion.com/guides/get-started/preparing-for-users
Learn how to create databases, pages, and views in a user's workspace right after they install your public connection.
Most public connections need specific databases, pages, or views to work. Traditionally, that meant waiting for the user to [share pages](/guides/get-started/authorization) manually or [duplicate a static template](/guides/get-started/authorization#prompt-for-a-connection-with-a-notion-template-option) during OAuth — both add friction and delay how quickly your connection delivers value.
With the Notion API, public connections can skip those steps entirely. Right after a user authorizes your connection, you can create the exact databases, pages, and views your connection needs — no extra user action required.
In this guide, you'll learn how to:
* Create databases and pages directly in a user's workspace
* Configure views with filters, sorts, and layout types
* Populate pages using database templates
## How it works
The user goes through the standard [OAuth flow](/guides/get-started/authorization). You receive an `access_token` with the capabilities your connection requested. No template URL is needed.
Use the API to create [databases](/reference/create-database) and [pages](/reference/post-page) at the workspace level. These appear in the user's **Private** section in Notion.
Use the [views API](/guides/data-apis/working-with-views) to add views (table, board, calendar, etc.) to your newly created databases, with the filters and sorts your connection needs.
If your databases have [data source templates](/guides/data-apis/creating-pages-from-templates), you can create pages that start from those templates for a richer initial experience.
## Creating workspace-level content
Public connections and [personal access tokens](/guides/get-started/personal-access-tokens) can create pages and databases at the **workspace level** by omitting the `parent` parameter (or setting it to `{ "type": "workspace", "workspace": true }`). This places the content in the associated user's Private section.
This capability is only available to **public connections**. Internal connections cannot create workspace-level content because they aren't owned by a single user.
### Create a database
```bash cURL expandable theme={null}
curl -X POST https://api.notion.com/v1/databases \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Content-Type: application/json" \
-H "Notion-Version: 2026-03-11" \
--data '{
"title": [{ "type": "text", "text": { "content": "Project Tracker" } }],
"is_inline": false,
"initial_data_source": {
"properties": {
"Task": { "title": {} },
"Status": {
"status": {
"options": [
{ "name": "Not started", "color": "default" },
{ "name": "In progress", "color": "blue" },
{ "name": "Done", "color": "green" }
]
}
},
"Assignee": { "people": {} },
"Due date": { "date": {} }
}
}
}'
```
```javascript JavaScript expandable theme={null}
const { Client } = require("@notionhq/client");
const notion = new Client({ auth: process.env.NOTION_API_KEY });
const database = await notion.databases.create({
// Omitting "parent" creates a workspace-level database
title: [{ type: "text", text: { content: "Project Tracker" } }],
is_inline: false,
initial_data_source: {
properties: {
Task: { title: {} },
Status: {
status: {
options: [
{ name: "Not started", color: "default" },
{ name: "In progress", color: "blue" },
{ name: "Done", color: "green" },
],
},
},
Assignee: { people: {} },
"Due date": { date: {} },
},
},
});
const dataSourceId = database.data_sources[0].id;
```
The new database is created with one data source and one default Table view. Store the `database.id` and `database.data_sources[0].id` — you'll need them to create views and pages.
### Create a standalone page
```bash cURL expandable theme={null}
curl -X POST https://api.notion.com/v1/pages \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Content-Type: application/json" \
-H "Notion-Version: 2026-03-11" \
--data '{
"properties": {
"title": {
"title": [{ "type": "text", "text": { "content": "Getting Started" } }]
}
},
"children": [
{
"object": "block",
"type": "heading_2",
"heading_2": {
"rich_text": [{ "type": "text", "text": { "content": "Welcome!" } }]
}
},
{
"object": "block",
"type": "paragraph",
"paragraph": {
"rich_text": [
{ "type": "text", "text": { "content": "This page was created by your connection. You can move it anywhere in your workspace." } }
]
}
}
]
}'
```
```javascript JavaScript expandable theme={null}
const page = await notion.pages.create({
// Omitting "parent" creates a workspace-level page
properties: {
title: {
title: [{ type: "text", text: { content: "Getting Started" } }],
},
},
children: [
{
object: "block",
type: "heading_2",
heading_2: {
rich_text: [{ type: "text", text: { content: "Welcome!" } }],
},
},
{
object: "block",
type: "paragraph",
paragraph: {
rich_text: [
{
type: "text",
text: {
content:
"This page was created by your connection. You can move it anywhere in your workspace.",
},
},
],
},
},
],
});
```
## Adding views
After creating a database, you can add views that match your connection's use cases. Each database starts with a default Table view, but you'll likely want to create additional views with specific filters, sorts, and layout types.
For a project tracker, you might want a Board view grouped by status and a Calendar view for due dates:
```bash cURL expandable theme={null}
# Board view: tasks grouped by status
curl -X POST https://api.notion.com/v1/views \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Content-Type: application/json" \
-H "Notion-Version: 2026-03-11" \
--data '{
"database_id": "DATABASE_ID",
"data_source_id": "DATA_SOURCE_ID",
"name": "Task board",
"type": "board"
}'
# Calendar view: tasks by due date
curl -X POST https://api.notion.com/v1/views \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Content-Type: application/json" \
-H "Notion-Version: 2026-03-11" \
--data '{
"database_id": "DATABASE_ID",
"data_source_id": "DATA_SOURCE_ID",
"name": "Schedule",
"type": "calendar"
}'
# Filtered table: only active tasks
curl -X POST https://api.notion.com/v1/views \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Content-Type: application/json" \
-H "Notion-Version: 2026-03-11" \
--data '{
"database_id": "DATABASE_ID",
"data_source_id": "DATA_SOURCE_ID",
"name": "Active tasks",
"type": "table",
"filter": {
"property": "Status",
"status": {
"does_not_equal": "Done"
}
},
"sorts": [
{
"property": "Due date",
"direction": "ascending"
}
]
}'
```
```javascript JavaScript expandable theme={null}
// Board view: tasks grouped by status
const boardView = await notion.views.create({
database_id: database.id,
data_source_id: dataSourceId,
name: "Task board",
type: "board",
});
// Calendar view: tasks by due date
const calendarView = await notion.views.create({
database_id: database.id,
data_source_id: dataSourceId,
name: "Schedule",
type: "calendar",
});
// Filtered table: only active tasks
const activeView = await notion.views.create({
database_id: database.id,
data_source_id: dataSourceId,
name: "Active tasks",
type: "table",
filter: {
property: "Status",
status: {
does_not_equal: "Done",
},
},
sorts: [
{
property: "Due date",
direction: "ascending",
},
],
});
```
See the [Working with views](/guides/data-apis/working-with-views) guide for full details on creating, updating, and querying views.
## Applying templates
If your connection pre-configures [database templates](https://www.notion.com/help/database-templates) for the data source, you can create pages that start from those templates. This is useful for providing users with structured starting points — for example, a "Bug report" template with pre-filled sections.
```bash cURL expandable theme={null}
# List available templates for the data source
curl -X GET "https://api.notion.com/v1/data_sources/DATA_SOURCE_ID/templates" \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Notion-Version: 2026-03-11"
# Create a page using the default template
curl -X POST https://api.notion.com/v1/pages \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Content-Type: application/json" \
-H "Notion-Version: 2026-03-11" \
--data '{
"parent": {
"type": "data_source_id",
"data_source_id": "DATA_SOURCE_ID"
},
"properties": {
"Task": {
"title": [{ "type": "text", "text": { "content": "My first task" } }]
}
},
"template": {
"type": "default"
}
}'
```
```javascript JavaScript expandable theme={null}
// List available templates for the data source
const templates = await notion.dataSources.listTemplates({
data_source_id: dataSourceId,
});
// Create a page using the default template
const page = await notion.pages.create({
parent: {
type: "data_source_id",
data_source_id: dataSourceId,
},
properties: {
Task: {
title: [{ type: "text", text: { content: "My first task" } }],
},
},
template: {
type: "default",
},
});
```
Template content is applied asynchronously after the page is created. If your connection needs to take action once the template is fully applied, use [webhooks](/reference/webhooks) to listen for `page.content_updated` events. See the [Creating pages from templates](/guides/data-apis/creating-pages-from-templates) guide for the full workflow.
## Programmatic setup vs. template duplication
| | Template URL (OAuth) | Programmatic setup |
| :--------------------- | :------------------------------------------------- | :------------------------------------------------------ |
| **Customization** | Static — every user gets the same template | Dynamic — tailor content to each user |
| **Schema control** | Snapshot; changes require updating the source page | Full control over properties and views at creation time |
| **Multiple databases** | One template page per connection | Create as many databases and pages as needed |
| **View configuration** | Views duplicated as-is | Create views with specific filters, sorts, and types |
| **User interaction** | User must choose "Duplicate template" during OAuth | No extra steps — setup happens after authorization |
Template duplication still works well for simple connections where a single static page is enough. Use programmatic setup when you need multiple resources, per-user customization, or want to keep the workspace in sync with an external system.
**What's next**
Now that you know how to set up workspace content, explore the APIs used in this guide:
* [Working with databases](/guides/data-apis/working-with-databases) — schemas, querying, and page management
* [Working with views](/guides/data-apis/working-with-views) — creating, updating, and querying views
* [Creating pages from templates](/guides/data-apis/creating-pages-from-templates) — using data source templates
* [Authorization](/guides/get-started/authorization) — the OAuth flow for public connections
# Public connections
Source: https://developers.notion.com/guides/get-started/public-connections
Learn how public connections work, how users authorize them, and how to create one.
## What is a public connection?
A public connection is an OAuth connection that users install into their Notion workspaces. Unlike [internal connections](/guides/get-started/internal-connections), which are scoped to a single workspace with a static token, public connections follow the [OAuth 2.0](https://oauth.net/2/) protocol: each user who authorizes the connection receives their own access token, scoped to their workspace.
When you create a public connection, you also choose its [installation scope](#installation-scope) — either **Any workspace** (Marketplace-eligible) or **Selected workspaces only** (not Marketplace-eligible).
If you only need a token for your own scripts, CLI workflows, Workers, or trusted tools, use a [personal access token](/guides/get-started/personal-access-tokens). PATs also act as one Notion user, but they do not provide an OAuth install flow for other users.
This guide covers:
* How public connections differ from internal connections
* How installation scope controls who can install your connection
* How users authorize a public connection via OAuth
* How to create a public connection in the Developer portal
## How public connections differ from internal connections
The key differences come down to scope, identity, and how access is granted:
* **Scope:** Internal connections work in one workspace; public connections can install into many. [Installation scope](#installation-scope) controls which workspaces are eligible.
* **Identity:** Internal connections operate as their own bot user with permissions independent of any specific person. Public connections act on behalf of the individual user who authorized them — the access token is tied to that user. [Personal access tokens](/guides/get-started/personal-access-tokens) are also tied to one user, but they are created directly by that user instead of through OAuth.
* **Page access:** Internal connections require workspace members to manually share pages via the "Add connections" menu. Public connections use the OAuth page picker, where users choose which pages to grant access to during the authorization flow.
For a full comparison, see the [comparison table](/guides/get-started/overview#comparison) in the Overview.
## Installation scope
Every public connection has an **installation scope** that controls which workspaces can install it. You pick the scope when you create the connection.
| Scope | Who can install | Marketplace eligible |
| :----------------------- | :----------------------------------------------- | :------------------- |
| Any workspace | Any Notion user, in any workspace. | Yes |
| Selected workspaces only | Only the workspaces you select at creation time. | No |
Installation scope is set once, at creation time, and can't be changed afterward. If you pick **Selected workspaces only** and later want to list on the Marketplace, create a new connection.
## How users authorize a public connection
When a user wants to use your public connection, they go through an OAuth authorization flow:
The user visits the connection's authorization URL. Find this URL in the **Configuration** tab of your connection in the Developer portal.
Notion presents a prompt describing the connection's [capabilities](/reference/capabilities) — what it will be able to do in the user's workspace.
The user selects which pages to grant the connection access to using the page picker.
After the user approves, Notion redirects them to your redirect URI with a temporary authorization code.
Your connection exchanges the code for an access token, which is used for all subsequent API requests on behalf of that user.
Public connections can also offer a Notion template during the auth flow. If configured, users can choose to duplicate the template into their workspace instead of selecting existing pages. See the [Authorization guide](/guides/get-started/authorization#prompt-for-a-connection-with-a-notion-template-option) for details on configuring templates.
After a user authorizes a public connection, only that user can interact with the connection in their workspace. If multiple members in a workspace want to use the same public connection, each user needs to complete the authorization flow individually.
## Creating a public connection
Navigate to the Developer portal.
In the **Build** section of the sidebar, select **Public connections**.
Click **Create new connection** and fill in the required fields, including:
* Connection name and development workspace
* [Redirect URI(s)](https://www.oauth.com/oauth2-servers/redirect-uris/) for the OAuth flow
* [Installation scope](#installation-scope) — choose **Any workspace** or **Selected workspaces only** (if you pick the latter, select the workspaces from the list that appears)
* Connection [capabilities](/reference/capabilities) (read content, update content, insert content, etc.)
After creation, visit the **Configuration** tab to retrieve your **OAuth client ID** and **OAuth client secret**. The client ID identifies your connection to Notion during the OAuth flow, and the client secret proves your connection is who it claims to be. Both are required when your server exchanges the authorization code for an access token. See the [Authorization guide](/guides/get-started/authorization) for the full implementation.
Marketplace listing details (such as descriptions, categories, and images) are managed separately through the **Listings** section. See [List on the Marketplace](/guides/get-started/marketplace-listing) for details.
## Next steps
Implement the full OAuth 2.0 flow for your public connection.
Automate user onboarding after they install your connection.
# Developer quickstart
Source: https://developers.notion.com/guides/get-started/quick-start
Build your first Notion connection with a hands-on tutorial.
## Why start with an internal connection?
We recommend starting with an [internal connection](/guides/get-started/internal-connections). Internal connections let you focus on building with the API right away — you just need an API token to get started. There's no OAuth flow to implement and no listing process to worry about. Everything stays within your workspace.
If you later need your connection to work across multiple workspaces, you can always create a [public connection](/guides/get-started/public-connections) and re-wire your code to use OAuth.
If you only need a token for a user-owned script or CLI workflow, a [personal access token](/guides/get-started/personal-access-tokens) may be faster. This quickstart uses an internal connection because it demonstrates a team-owned automation with explicit page sharing.
In this guide, we're going to build an internal Notion connection that creates a new database in your workspace via a web form.
![]()
## What to know before you start
Before diving in, here are a few essential things to keep in mind when working with the Notion API:
* **Versioning:** Every request must include a `Notion-Version` header. See [Versioning](/reference/versioning) for the latest version.
* **Rate limits:** The API allows an average of 3 requests per second. If you exceed this, you'll receive a `429` response with a `Retry-After` header. See [Request limits](/reference/request-limits).
* **Error handling:** API errors return structured JSON with a `code` and `message`. See [Status codes](/reference/status-codes) for the full list.
* **Pagination:** List endpoints return paginated results. Use `start_cursor` and `has_more` to iterate through pages. See the [API introduction](/reference/intro) for details.
* **Token security:** Never store your API secret in source code or version control. Use environment variables or a secret manager. See [Best practices for handling API keys](/guides/get-started/handling-api-keys).
## What you will build
This guide will demonstrate how to build an HTML form that will [create a new Notion database](/reference/create-a-database) when submitted.
By the end of this guide, we'll have a functional app that looks like this:
![]()
The completed [sample code](https://github.com/makenotion/notion-cookbook/tree/main/examples/javascript/web-form-with-express) includes additional examples beyond what's covered in this guide, including forms to:
* [Add a new page](/reference/post-page) to the database
* [Add content](/reference/patch-block-children) to the new page
* [Add a comment](/reference/create-a-comment) to the page content
### Requirements
To follow along with this guide, you will need:
* A [Notion account](https://www.notion.so/signup).
* To be a [Workspace Owner](https://www.notion.so/help/add-members-admins-guests-and-groups) in the workspace you're using. You can create a new workspace for testing purposes otherwise.
* Knowledge of HTML and JavaScript. We'll use [Express.js](https://expressjs.com/) for a server, as well.
* [npm and Node.js](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) installed locally to use the [Notion SDK for JavaScript](https://github.com/makenotion/notion-sdk-js) and [Express.js](https://expressjs.com/)
**SDK usage is recommended, but not required**
The [sample code](https://github.com/makenotion/notion-cookbook/tree/main/examples/javascript/web-form-with-express) shown below uses the [Notion SDK for JavaScript](https://github.com/makenotion/notion-sdk-js) to make public API requests.
Using the Notion SDK for JavaScript is not required to build a Notion connection, but many JavaScript developers prefer it due to its ease of use.
## Create your connection in Notion
The first step is to create a new internal connection in Notion's Developer portal.
In the **Build** section of the sidebar, select **Internal connections**, then click **Create a new connection**.
Enter the connection name and select the workspace where the connection can be installed.
### Get your access token
API requests require an installation access token to be successfully authenticated. Visit the `Configuration` tab to get your connection's installation access token.
![]()
**Never share your installation access token!**
Any value used to authenticate API requests should always be kept private. Use environment variables and avoid committing sensitive data to your version control history.
If you do accidentally expose it, remember to refresh your installation access token.
[Learn more: Best practices for handling API keys](/guides/get-started/handling-api-keys)
### Give your connection page permissions
The database that we're about to create will be added to a parent Notion page in your workspace. For your connection to interact with the page, it needs explicit permission to read/write to that specific Notion page.
To give the connection permission, you will need to:
Pick (or create) a Notion page.
Click on the `...` More menu in the top-right corner of the page.
Scroll down to `+ Add Connections`.
Search for your connection and select it.
Confirm the connection can access the page and all of its child pages.
![]()
Your connection can now make API requests related to this Notion page and any of its children.
To learn more about how internal connection permissions work — including the bot identity model — see the [Internal connections](/guides/get-started/internal-connections) guide.
**Double-check your page access**
If your API requests are failing, confirm you have given the connection permission to the page you are trying to update. This is a common cause of API request errors.
## Setting up the demo locally
In this example, we'll have three key files:
* `index.html`, which will contain our client-side HTML.
* `client.js`, which will contain our client-side JavaScript code.
* `server.js`, which will contain our server-side JavaScript code. This file contains all the endpoints to make requests to Notion's public API, as well as to serve the `index.html` file. ([More on that below.](#step-3-importing-the-notion-sdk-serverjs))
All of the sample code is available in [GitHub](https://github.com/makenotion/notion-cookbook/tree/main/examples/javascript/web-form-with-express).
**Various examples are available**
This connection includes frontend code, but connections can be server-side only, as well. See more examples of different connection use cases in [GitHub](https://github.com/makenotion/notion-cookbook/tree/main/examples/javascript).
### Clone demo repo
To run this project locally, clone the repo and install its dependencies ([Express.js](https://expressjs.com/en/starter/installing.html), [dotenv](https://www.npmjs.com/package/dotenv), and [Notion's SDK for JavaScript](https://github.com/makenotion/notion-sdk-js)):
```bash Shell theme={null}
# Clone this repository locally
git clone https://github.com/makenotion/notion-cookbook.git
# Switch into this project
cd notion-cookbook/examples/javascript/web-form-with-express/
# Install the dependencies
npm install
```
### Environment variables
In your `.env` file, add the following variables:
```bash .env theme={null}
NOTION_KEY=
NOTION_PAGE_ID=
```
Add the access token you retrieved in the [Get your access token](#get-your-access-token) step to `NOTION_KEY`, as well as a page ID (`NOTION_PAGE_ID`) for the page that you gave the connection permission to update.
**How database IDs work**
When using the API to [create a database](/reference/create-a-database), the parent of a database must be a Notion page or a [wiki](https://www.notion.so/help/wikis-and-verified-pages) database. To get the ID of the page, locate the 32-character string at the end of the page's URL.
![The page ID is highlighted.]()
As a best practice, add `.env` to your `.gitignore` file to ensure you don't accidentally share these values.
### Running the project locally
To run this project locally, you will need to enter the following command in your terminal:
```bash Shell theme={null}
npm start
```
Once the server is running, open [http://localhost:8000](http://localhost:8000) in your browser. Next, let's look at how our database form works.
## Creating a new database
### Step 1 - Build the form
In our `index.html` file, we need a form for the user to create a new database and an area for the API response to be displayed. This is how the user will initiate a Notion API request.
![]()
![]()
The corresponding [HTML elements](https://github.com/makenotion/notion-cookbook/blob/main/examples/javascript/web-form-with-express/views/index.html#L40) related to creating a database are shown below:
```html HTML expandable theme={null}
...
...
...
1. Create a new database
...
...
```
In terms of what's rendered in the ``, notice the `
| ` |
| [Image](/reference/block#image) | `` |
| [File](/reference/block#file) | ` \* If the redirect URI was supplied as a query param in the Authorization URL, this field is required. If there are more than one redirect URIs included in your connection settings, this field is required. Otherwise, it is not allowed. Learn more in the [Create a token page](/reference/create-a-token). | The following is an example request to exchange the authorization code for an access token:
|