Skip to main content

​
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 ID
  • content - Content data for creation/update operations
Optional:
  • properties - Page or database properties
  • filters - Query filters for database searches
  • sorts - Sort criteria for database queries
  • block_type - Type of block to create (paragraph, heading, to_do, etc.)

​
Tools

​
Create Page

Create a new page in a parent page or database. Parameters:
  • parent_id (required) - Parent page or database ID
  • title (required) - Page title
  • properties (optional) - Page properties
  • content (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 update
  • properties (required) - Properties to update
  • title (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 ID
  • title (required) - Database title
  • properties (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 query
  • filter (optional) - Filter criteria
  • sorts (optional) - Sort criteria
  • page_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 ID
  • blocks (required) - Array of blocks to add
  • block_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 update
  • content (required) - New block content
  • block_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 text
  • filter (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.
⌘I