> For the complete documentation index, see [llms.txt](https://docs.planetcrust.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.planetcrust.com/human-connections/notion/notion.md).
# Notion
Try @Human Buy @Human Subscription Join @Human Community
Put Notion to Work with @Human Automations and @Human Agents
The Notion Connection documents all Triggers, Actions and Query Operations available for creating automations via the Notion API.
{% embed url="" %}
#### What can you do with the Notion Connection?
* Connect to the Notion API in a few clicks
* Use the related Notion Operations (see below) in @Human Automations or @Human Agents
### Related Operations
#### Trigger Operations
**Database Created**
Triggers on: databases/database.created
Triggered when a new database is created in Notion.
**Database Updated**
Triggers on: databases/database.updated
Triggered when an existing database is updated in Notion.
**Page Created**
Triggers on: pages/page.created
Triggered when a new page is created in Notion.
**Page Updated**
Triggers on: pages/page.updated
Triggered when an existing page is updated in Notion.
**Block Updated**
Triggers on: blocks/block.updated
Triggered when a block is updated in Notion.
**User Updated**
Triggers on: users/user.updated
Triggered when a user's information is updated in Notion.
**Comment Created**
Triggers on: comments/comment.created
Triggered when a new comment is created in Notion.
#### Action Operations
[Action: Create a Database](/human-connections/notion/notion/action-create-a-database.md)
[Action: Update a Database](/human-connections/notion/notion/action-update-a-database.md)
[Action: Create a Page](/human-connections/notion/notion/action-create-a-page.md)
[Action: Update a Page](/human-connections/notion/notion/action-update-a-page.md)
#### Query Operations
[Query: Retrieve a Database](/human-connections/notion/notion/query-retrieve-a-database.md)
[Query: Retrieve a Page](/human-connections/notion/notion/query-retrieve-a-page.md)
### Related Automations
Example link
### Obtaining Access Credentials
To obtain a **Personal Access Token (PAT)** for **Notion's system-to-system integration**, follow these steps:
#### **Prerequisites**
* A **Notion account** (free or paid).
* Access to the **Notion workspace** where the integration will be used.
#### **Steps to Generate a Notion PAT**
1. **Log in** to your Notion account at [notion.so](https://www.notion.so/).
2. Click on your **profile icon** (top-right) → **Settings**.
3. Navigate to **Connections.**
4. Click on **Develop or manage integrations**.
* If prompted, confirm you want to create a new integration.
5. **Create a New Integration**
6. Enter a **name** (e.g., "API Access").
7. Select the **workspace** where the integration will operate.
8. Click **Create**.
9. Click on **Configure Integration Settings**.
10. After creation, you’ll see a **secret token** under *Internal Integration Secret.*
11. **Copy this token** (treat it like a password—store securely).
* This is your **PAT** for system-to-system access.
### Configuring Webhooks
1. **Log in** to your Notion account at [notion.so](https://www.notion.so/).
2. Click on your **profile icon** (top-right) → **Settings**.
3. Navigate to **Connections**.
4. Click on **Develop or manage integrations**.
5. Select the **integration** you wish to configure.
6. Click on the **Webhooks** tab in the sidebar.
7. Click **+ Create a subscription**.
8. Enter your **Webhook URL** (must be a public HTTPS endpoint).
9. Select the **event types** you want to subscribe to (e.g., page updates, database changes).
10. Click **Create subscription**.
11. **Copy the Signature Secret** provided to verify incoming webhook payloads.
### Code (Apache v2.0): Service Connectivity and Metadata
```
{
"handle": "notion-api-v1",
"status": "active",
"meta": {
"short": "Notion API",
"description": "Connect to Notion's API to manage databases, pages, and more.",
"icon": "notion",
"tags": ["productivity", "database", "collaboration"]
},
"service": {
"baseURL": {
"value": "https://api.notion.com/v1"
},
"protocol": "https",
"contentType": "application/json",
"headers": {
"Notion-Version": {
"value": "2022-06-28"
}
},
"auth": {
"method": "api_token",
"params": {
"apiToken": {
"token": {
"value": "{{apiToken}}",
"placeholders": [
{
"name": "apiToken",
"type": "String",
"description": "Notion API token for authentication.",
"required": true
}
]
},
"headerName": {
"value": "Authorization"
}
}
}
}
}
}
```
### Code (Apache v2.0): List of External Resources and Internal Mapping
```
[
{
"handle": "databases",
"meta": {
"short": "Databases",
"description": "Manage and query Notion databases"
},
"endpoint": {
"value": "v1/databases"
},
"fields": [
{
"name": "id",
"type": "String",
"selector": [
"id"
],
"meta": {
"description": "Unique identifier for the database"
}
},
{
"name": "title",
"type": "String",
"selector": [
"title",
0,
"plain_text"
],
"meta": {
"description": "Title of the database"
},
"multivalue": true
},
{
"name": "created_time",
"type": "String",
"selector": [
"created_time"
],
"meta": {
"description": "ISO 8601 timestamp when the database was created."
}
},
{
"name": "last_edited_time",
"type": "String",
"selector": [
"last_edited_time"
],
"meta": {
"description": "ISO 8601 timestamp when the database was last edited."
}
},
{
"name": "url",
"type": "String",
"selector": [
"url"
],
"meta": {
"description": "The URL of the database in Notion."
}
}
],
"operations": {
"list": {
"method": "GET",
"path": {
"value": ""
},
"headers": {
"Notion-Version": "2022-06-28",
"Authorization": "Bearer {{apiKey}}"
}
},
"read": {
"method": "GET",
"path": {
"value": "{{databaseId}}"
},
"headers": {
"Notion-Version": "2022-06-28",
"Authorization": "Bearer {{apiKey}}"
}
},
"create": {
"method": "POST",
"path": {
"value": ""
},
"headers": {
"Notion-Version": "2022-06-28",
"Authorization": "Bearer {{apiKey}}",
"Content-Type": "application/json"
},
"bodyTemplate": {
"value": "{\"parent\": {\"type\": \"{{parentType}}\", \"{{parentType}}\": \"{{parentId}}\"},\"title\": [{\"type\": \"text\", \"text\": {\"content\": \"{{title}}\"}}],\"properties\": {{properties}}}"
}
},
"update": {
"method": "PATCH",
"path": {
"value": "{{databaseId}}"
},
"headers": {
"Notion-Version": "2022-06-28",
"Authorization": "Bearer {{apiKey}}",
"Content-Type": "application/json"
},
"bodyTemplate": {
"value": "{\"title\": [{\"type\": \"text\", \"text\": {\"content\": \"{{title}}\"}}],\"properties\": {{properties}}}"
}
}
},
"webhooks": [
{
"event": "database.created",
"path": "/webhooks/notion/database.created",
"payload": [
{ "name": "id", "type": "String", "selector": ["id"], "meta": { "description": "The unique identifier for the database." } },
{ "name": "title", "type": "String", "selector": ["title", 0, "plain_text"], "meta": { "description": "The title of the database." } }
]
},
{
"event": "database.updated",
"path": "/webhooks/notion/database.updated",
"payload": [
{ "name": "id", "type": "String", "selector": ["id"], "meta": { "description": "The unique identifier for the database." } },
{ "name": "title", "type": "String", "selector": ["title", 0, "plain_text"], "meta": { "description": "The title of the database." } }
]
}
]
},
{
"handle": "pages",
"meta": {
"short": "Pages",
"description": "Manage Notion pages"
},
"endpoint": {
"value": "v1/pages"
},
"fields": [
{
"name": "id",
"type": "String",
"selector": [
"id"
],
"meta": {
"description": "Unique identifier for the page"
}
},
{
"name": "title",
"type": "String",
"selector": [
"properties",
"title",
"title",
0,
"plain_text"
],
"meta": {
"description": "Title of the page"
},
"multivalue": true
},
{
"name": "content",
"type": "String",
"selector": [
"properties",
"content",
"rich_text",
0,
"plain_text"
],
"meta": {
"description": "Content of the page"
},
"multivalue": true
}
],
"operations": {
"read": {
"method": "GET",
"path": {
"value": "{{pageId}}"
},
"headers": {
"Notion-Version": "2022-06-28",
"Authorization": "Bearer {{apiKey}}"
}
},
"create": {
"method": "POST",
"path": {
"value": ""
},
"headers": {
"Notion-Version": "2022-06-28",
"Authorization": "Bearer {{apiKey}}",
"Content-Type": "application/json"
},
"bodyTemplate": {
"value": "{\"parent\": {\"type\": \"{{parentType}}\", \"{{parentType}}\": \"{{parentId}}\"},\"properties\": {\"title\": {\"title\": [{\"type\": \"text\", \"text\": {\"content\": \"{{title}}\"}}]}}}"
}
},
"update": {
"method": "PATCH",
"path": {
"value": "{{pageId}}"
},
"headers": {
"Notion-Version": "2022-06-28",
"Authorization": "Bearer {{apiKey}}",
"Content-Type": "application/json"
},
"bodyTemplate": {
"value": "{\"properties\": {\"title\": {\"title\": [{\"type\": \"text\", \"text\": {\"content\": \"{{title}}\"}}]}}}"
}
}
},
"webhooks": [
{
"event": "page.created",
"path": "/webhooks/notion/page.created",
"payload": [
{ "name": "id", "type": "String", "selector": ["id"], "meta": { "description": "The unique identifier for the page." } },
{ "name": "title", "type": "String", "selector": ["properties", "title", "title", 0, "plain_text"], "meta": { "description": "The title of the page." } }
]
},
{
"event": "page.updated",
"path": "/webhooks/notion/page.updated",
"payload": [
{ "name": "id", "type": "String", "selector": ["id"], "meta": { "description": "The unique identifier for the page." } },
{ "name": "title", "type": "String", "selector": ["properties", "title", "title", 0, "plain_text"], "meta": { "description": "The title of the page." } }
]
}
]
},
{
"handle": "blocks",
"meta": {
"short": "Blocks",
"description": "Manage Notion blocks"
},
"endpoint": {
"value": "v1/blocks"
},
"fields": [
{
"name": "id",
"type": "String",
"selector": [
"id"
],
"meta": {
"description": "Unique identifier for the block"
}
},
{
"name": "type",
"type": "String",
"selector": [
"type"
],
"meta": {
"description": "Type of the block"
}
},
{
"name": "content",
"type": "String",
"selector": [
"{{type}}",
"rich_text",
0,
"plain_text"
],
"meta": {
"description": "Content of the block"
},
"multivalue": true
}
],
"operations": {
"read": {
"method": "GET",
"path": {
"value": "{{blockId}}"
},
"headers": {
"Notion-Version": "2022-06-28",
"Authorization": "Bearer {{apiKey}}"
}
},
"list": {
"method": "GET",
"path": {
"value": "{{blockId}}/children"
},
"headers": {
"Notion-Version": "2022-06-28",
"Authorization": "Bearer {{apiKey}}"
}
},
"update": {
"method": "PATCH",
"path": {
"value": "{{blockId}}"
},
"headers": {
"Notion-Version": "2022-06-28",
"Authorization": "Bearer {{apiKey}}",
"Content-Type": "application/json"
},
"bodyTemplate": {
"value": "{\"{{type}}\": {\"rich_text\": [{\"type\": \"text\", \"text\": {\"content\": \"{{content}}\"}}]}}"
}
},
"delete": {
"method": "DELETE",
"path": {
"value": "{{blockId}}"
},
"headers": {
"Notion-Version": "2022-06-28",
"Authorization": "Bearer {{apiKey}}"
}
}
},
"webhooks": [
{
"event": "block.updated",
"path": "/webhooks/notion/block.updated",
"payload": [
{ "name": "id", "type": "String", "selector": ["id"], "meta": { "description": "The unique identifier for the block." } },
{ "name": "type", "type": "String", "selector": ["type"], "meta": { "description": "The type of the block." } }
]
}
]
},
{
"handle": "search",
"meta": {
"short": "Search",
"description": "Search across Notion pages and databases"
},
"endpoint": {
"value": "v1/search"
},
"fields": [
{
"name": "results_0_id",
"type": "String",
"selector": [
"results",
0,
"id"
],
"meta": {
"description": "ID of the first search result."
},
"multivalue": true
},
{
"name": "results_0_object",
"type": "String",
"selector": [
"results",
0,
"object"
],
"meta": {
"description": "Object type of the first result (page or database)."
},
"multivalue": true
},
{
"name": "results_0_url",
"type": "String",
"selector": [
"results",
0,
"url"
],
"meta": {
"description": "URL of the first search result."
},
"multivalue": true
}
],
"operations": {
"list": {
"method": "POST",
"path": {
"value": ""
},
"headers": {
"Notion-Version": "2022-06-28",
"Authorization": "Bearer {{apiKey}}",
"Content-Type": "application/json"
},
"bodyTemplate": {
"value": "{\"query\": \"{{query}}\", \"filter\": {\"value\": \"{{filterType}}\", \"property\": \"{{filterProperty}}\"}}"
}
}
},
"webhooks": []
},
{
"handle": "users",
"meta": {
"short": "Users",
"description": "Manage Notion users"
},
"endpoint": {
"value": "v1/users"
},
"fields": [
{
"name": "id",
"type": "String",
"selector": [
"id"
],
"meta": {
"description": "Unique identifier for the user"
}
},
{
"name": "name",
"type": "String",
"selector": [
"name"
],
"meta": {
"description": "User's name"
}
},
{
"name": "type",
"type": "String",
"selector": [
"type"
],
"meta": {
"description": "Type of user, e.g., 'person' or 'bot'"
}
},
{
"name": "avatar_url",
"type": "String",
"selector": [
"avatar_url"
],
"meta": {
"description": "URL of the user's avatar"
}
},
{
"name": "email",
"type": "String",
"selector": [
"person",
"email"
],
"meta": {
"description": "Email address of the person"
}
}
],
"operations": {
"list": {
"method": "GET",
"path": {
"value": ""
},
"headers": {
"Notion-Version": "2022-06-28",
"Authorization": "Bearer {{apiKey}}"
}
},
"read": {
"method": "GET",
"path": {
"value": "{{userId}}"
},
"headers": {
"Notion-Version": "2022-06-28",
"Authorization": "Bearer {{apiKey}}"
}
}
},
"webhooks": [
{
"event": "user.updated",
"path": "/webhooks/notion/user.updated",
"payload": [
{ "name": "id", "type": "String", "selector": ["id"], "meta": { "description": "The unique identifier for the user." } },
{ "name": "name", "type": "String", "selector": ["name"], "meta": { "description": "The name of the user." } }
]
}
]
},
{
"handle": "comments",
"meta": {
"short": "Comments",
"description": "Manage Notion comments"
},
"endpoint": {
"value": "v1/comments"
},
"fields": [
{
"name": "id",
"type": "String",
"selector": [
"id"
],
"meta": {
"description": "Unique identifier for the comment"
}
},
{
"name": "discussion_id",
"type": "String",
"selector": [
"discussion_id"
],
"meta": {
"description": "ID of the discussion the comment belongs to"
}
},
{
"name": "rich_text",
"type": "String",
"selector": [
"rich_text",
0,
"plain_text"
],
"meta": {
"description": "Plain text content of the comment"
},
"multivalue": true
},
{
"name": "created_time",
"type": "String",
"selector": [
"created_time"
],
"meta": {
"description": "Creation time of the comment"
}
},
{
"name": "created_by_id",
"type": "String",
"selector": [
"created_by",
"id"
],
"meta": {
"description": "ID of the user who created the comment"
}
}
],
"operations": {
"list": {
"method": "GET",
"path": {
"value": "?block_id={{blockId}}"
},
"headers": {
"Notion-Version": "2022-06-28",
"Authorization": "Bearer {{apiKey}}"
}
},
"create": {
"method": "POST",
"path": {
"value": ""
},
"headers": {
"Notion-Version": "2022-06-28",
"Authorization": "Bearer {{apiKey}}",
"Content-Type": "application/json"
},
"bodyTemplate": {
"value": "{\"parent\": {\"{{parentType}}\": \"{{parentId}}\"}, \"rich_text\": [{\"text\": {\"content\": \"{{content}}\"}}]}"
}
}
},
"webhooks": [
{
"event": "comment.created",
"path": "/webhooks/notion/comment.created",
"payload": [
{ "name": "id", "type": "String", "selector": ["id"], "meta": { "description": "The unique identifier for the comment." } },
{ "name": "discussion_id", "type": "String", "selector": ["discussion_id"], "meta": { "description": "The ID of the discussion the comment belongs to." } },
{ "name": "rich_text", "type": "String", "selector": ["rich_text", 0, "plain_text"], "meta": { "description": "The plain text content of the comment." } }
]
}
]
}
]
```
Try @Human Buy @Human Subscription Join @Human Community
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.planetcrust.com/human-connections/notion/notion.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.