What can you do with it?
The Notion API allows you to manage your entire Notion workspace programmatically. You can create and update pages, manage databases with properties and entries, add and modify content blocks, and search across your workspace to find specific information.
How to use it?
Basic Command Structure
/your-notion-connection [action] [required-parameters] [optional-parameters]
Parameters
Required:
action - The action to perform (create, update, retrieve, query, etc.)page_id or database_id - The target page or database IDcontent - Content data for creation/update operations
Optional:
properties - Page or database propertiesfilters - Query filters for database searchessorts - Sort criteria for database queriesblock_type - Type of block to create (paragraph, heading, to_do, etc.)
Create Page
Create a new page in a parent page or database.
Parameters:
parent_id (required) - Parent page or database IDtitle (required) - Page titleproperties (optional) - Page propertiescontent (optional) - Initial content blocks
Example:
/your-notion-connection
action: create_page
parent_id: 98ad959b-2b6a-4774-80ee-00246fb0ea9b
title: New Project Plan
content: This is the initial content for the new page
Response:
{
"object": "page",
"id": "b55c9c91-384d-452b-81db-d1ef79372b75",
"created_time": "2023-05-10T12:00:00.000Z",
"properties": {
"title": {
"type": "title",
"title": [
{
"text": {
"content": "New Project Plan"
}
}
]
}
},
"url": "https://www.notion.so/New-Project-Plan-b55c9c91384d452b81dbd1ef79372b75"
}
Update Page
Update the properties of an existing page.
Parameters:
page_id (required) - Page ID to updateproperties (required) - Properties to updatetitle (optional) - New page title
Example:
/your-notion-connection
action: update_page
page_id: b55c9c91-384d-452b-81db-d1ef79372b75
title: Updated Project Plan
Response:
{
"object": "page",
"id": "b55c9c91-384d-452b-81db-d1ef79372b75",
"last_edited_time": "2023-05-10T12:30:00.000Z",
"properties": {
"title": {
"type": "title",
"title": [
{
"text": {
"content": "Updated Project Plan"
}
}
]
}
}
}
Retrieve Page
Get information about a specific page.
Parameters:
page_id (required) - Page ID to retrieve
Example:
/your-notion-connection
action: retrieve_page
page_id: b55c9c91-384d-452b-81db-d1ef79372b75
Response:
{
"object": "page",
"id": "b55c9c91-384d-452b-81db-d1ef79372b75",
"created_time": "2023-05-10T12:00:00.000Z",
"last_edited_time": "2023-05-10T12:30:00.000Z",
"archived": false,
"properties": {
"title": {
"type": "title",
"title": [
{
"text": {
"content": "Updated Project Plan"
}
}
]
}
}
}
Get Page Content
Retrieve all blocks contained in a page.
Parameters:
page_id (required) - Page ID to get content from
Example:
/your-notion-connection
action: get_page_content
page_id: b55c9c91-384d-452b-81db-d1ef79372b75
Response:
{
"object": "list",
"results": [
{
"object": "block",
"id": "c8a53e3f-5163-4f95-a840-61b7ec1b93fb",
"type": "paragraph",
"paragraph": {
"rich_text": [
{
"type": "text",
"text": {
"content": "This is a new page with some content."
}
}
]
}
}
]
}
Create Database
Create a new database as a child of a page.
Parameters:
parent_page_id (required) - Parent page IDtitle (required) - Database titleproperties (required) - Database schema properties
Example:
/your-notion-connection
action: create_database
parent_page_id: 98ad959b-2b6a-4774-80ee-00246fb0ea9b
title: Task Database
properties: {"Name": {"title": {}}, "Status": {"select": {"options": [{"name": "Not Started", "color": "red"}, {"name": "In Progress", "color": "blue"}, {"name": "Completed", "color": "green"}]}}, "Due Date": {"date": {}}}
Response:
{
"object": "database",
"id": "d9824bdc-8445-4327-be8b-5b47500af6ce",
"created_time": "2023-05-10T13:00:00.000Z",
"title": [
{
"text": {
"content": "Task Database"
}
}
],
"properties": {
"Name": {
"type": "title",
"title": {}
},
"Status": {
"type": "select",
"select": {
"options": [
{
"name": "Not Started",
"color": "red"
},
{
"name": "In Progress",
"color": "blue"
},
{
"name": "Completed",
"color": "green"
}
]
}
}
}
}
Query Database
Query a database with optional filters, sorts, and pagination.
Parameters:
database_id (required) - Database ID to queryfilter (optional) - Filter criteriasorts (optional) - Sort criteriapage_size (optional) - Number of results per page
Example:
/your-notion-connection
action: query_database
database_id: d9824bdc-8445-4327-be8b-5b47500af6ce
filter: {"property": "Status", "select": {"equals": "In Progress"}}
sorts: [{"property": "Due Date", "direction": "ascending"}]
Response:
{
"object": "list",
"results": [
{
"object": "page",
"id": "7e5f1a5b-8a3c-4685-b9c4-3d4e89670124",
"properties": {
"Name": {
"type": "title",
"title": [
{
"text": {
"content": "Complete project proposal"
}
}
]
},
"Status": {
"type": "select",
"select": {
"name": "In Progress",
"color": "blue"
}
},
"Due Date": {
"type": "date",
"date": {
"start": "2023-05-15"
}
}
}
}
]
}
Add Content Blocks
Add new blocks as children to an existing page or block.
Parameters:
parent_id (required) - Parent page or block IDblocks (required) - Array of blocks to addblock_type (optional) - Type of blocks (paragraph, heading, to_do, etc.)
Example:
/your-notion-connection
action: add_blocks
parent_id: b55c9c91-384d-452b-81db-d1ef79372b75
blocks: [{"type": "heading_2", "content": "New Section"}, {"type": "paragraph", "content": "This is a new paragraph under the heading."}, {"type": "to_do", "content": "Task to complete", "checked": false}]
Response:
{
"object": "list",
"results": [
{
"object": "block",
"id": "d2d8e1f5-c9b7-4a6e-8d3f-2e1a4c5b6d9e",
"type": "heading_2",
"heading_2": {
"rich_text": [
{
"text": {
"content": "New Section"
}
}
]
}
},
{
"object": "block",
"id": "f3e2d1c0-b9a8-7c6d-5e4f-3g2h1i0j9k8l",
"type": "paragraph",
"paragraph": {
"rich_text": [
{
"text": {
"content": "This is a new paragraph under the heading."
}
}
]
}
}
]
}
Update Block
Update the content of a specific block.
Parameters:
block_id (required) - Block ID to updatecontent (required) - New block contentblock_type (optional) - Block type if changing
Example:
/your-notion-connection
action: update_block
block_id: c8a53e3f-5163-4f95-a840-61b7ec1b93fb
content: This is updated content for the paragraph
Response:
{
"object": "block",
"id": "c8a53e3f-5163-4f95-a840-61b7ec1b93fb",
"type": "paragraph",
"paragraph": {
"rich_text": [
{
"text": {
"content": "This is updated content for the paragraph."
}
}
]
},
"last_edited_time": "2023-05-10T15:00:00.000Z"
}
Search Workspace
Search for pages or databases matching query text.
Parameters:
query (required) - Search query textfilter (optional) - Filter by object type (page/database)sort (optional) - Sort criteria
Example:
/your-notion-connection
action: search
query: project proposal
filter: {"property": "object", "value": "page"}
sort: {"direction": "descending", "timestamp": "last_edited_time"}
Response:
{
"object": "list",
"results": [
{
"object": "page",
"id": "7e5f1a5b-8a3c-4685-b9c4-3d4e89670124",
"created_time": "2023-05-10T14:00:00.000Z",
"last_edited_time": "2023-05-10T14:00:00.000Z",
"properties": {
"Name": {
"type": "title",
"title": [
{
"text": {
"content": "Complete project proposal"
}
}
]
}
}
}
]
}
Notes
All requests must include the Notion-Version header set to “2022-06-28”. Supports rich text formatting, various block types (paragraphs, headings, to-do items, etc.), and complex database properties including select options, dates, and people assignments. Database queries support advanced filtering and sorting capabilities.
