Notion

Authentication Type: API Key
Description: Integrate with Notion to create, retrieve, update pages, manage block content, and search.

Authentication

To authenticate, you'll need to create a Notion internal integration:

Follow the Notion integration guide to create an internal integration (you can name it anything)
Give the integration access to the databases you want it to access
Copy the API token from your integration settings

Users

The users of your workspace.

List All Users

Get a list of all the users for the workspace.

Operation Type: Query (Read)

Parameters:

None

Returns:

results array of objects: Array of workspace users
- id string: User ID
- object string: Always "user"
- name string (nullable): User display name
- avatar_url string (nullable): User avatar image URL
- person object (nullable): Person details
  - email string (nullable): User email address

Example Usage:

{}

Pages

Operations for managing Notion pages.

Create Page

Creates a new page in Notion with the specified title, content, and properties.

Operation Type: Mutation (Write)

Parameters:

parentDatabaseId string (required): The ID of the parent database to create the page in
title string (required): The title of the page
content string (nullable): The content/body of the page
properties array of objects (nullable): Additional properties for the page (key-value pairs)
- key string: Property name
- value string: Property value

Returns:

pageId string: The ID of the created page
url string: The URL of the created page
title string: The title of the created page

Example Usage:

{
  "parentDatabaseId": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Q1 2024 Marketing Campaign",
  "content": "This page outlines our marketing strategy for the first quarter of 2024, including target audiences, budget allocation, and key performance indicators.",
  "properties": [
    {
      "key": "Status",
      "value": "In Progress"
    },
    {
      "key": "Owner",
      "value": "Marketing Team"
    },
    {
      "key": "Priority",
      "value": "High"
    }
  ]
}

Retrieve Page

Retrieves a page from Notion by its ID, including content and properties.

Operation Type: Query (Read)

Parameters:

pageId string (required): The ID of the page to retrieve

Returns:

pageId string: The ID of the page
title string: The title of the page
content string (nullable): The content of the page
url string: The URL of the page
lastEditedTime string: When the page was last edited
properties array of objects (nullable): The properties of the page
- key string: Property name
- value string: Property value

Example Usage:

{
  "pageId": "550e8400-e29b-41d4-a716-446655440000"
}

Update Page

Updates an existing page in Notion with new title or properties.

Operation Type: Mutation (Write)

Parameters:

pageId string (required): The ID of the page to update
title string (nullable): The new title of the page
properties array of objects (nullable): Updated properties for the page
- key string: Property name
- value string: Property value

Returns:

pageId string: The ID of the updated page
url string: The URL of the updated page
title string (nullable): The title of the updated page
lastEditedTime string: When the page was last edited

Example Usage:

{
  "pageId": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Q1 2024 Marketing Campaign - Final",
  "properties": [
    {
      "key": "Status",
      "value": "Completed"
    },
    {
      "key": "Completion Date",
      "value": "2024-03-31"
    }
  ]
}

Blocks

Operations for managing Notion blocks and their children.

Append Block Children

Appends child blocks to a parent block in Notion. Supports positioning blocks after specific blocks.

Operation Type: Mutation (Write)

Parameters:

blockId string (required): The ID of the parent block to append children to
children array of objects (required): Array of simple block objects to append as children
- type string: The type of block (paragraph, heading_1, etc.)
- content string: The text content for the block
after string (nullable): ID of the block to append after (optional)

Returns:

results array of objects: The newly created block objects
- type string: The type of the block
- object string: Always "block"
- paragraph object (nullable): Paragraph block content
- heading_1 object (nullable): Heading 1 block content
- heading_2 object (nullable): Heading 2 block content
- heading_3 object (nullable): Heading 3 block content

Example Usage:

{
  "blockId": "550e8400-e29b-41d4-a716-446655440000",
  "children": [
    {
      "type": "heading_1",
      "content": "Executive Summary"
    },
    {
      "type": "paragraph",
      "content": "Our Q1 marketing campaign exceeded expectations with a 25% increase in lead generation and 15% improvement in conversion rates."
    },
    {
      "type": "heading_2",
      "content": "Key Metrics"
    },
    {
      "type": "paragraph",
      "content": "Total leads generated: 1,250\nConversion rate: 18.5%\nCost per acquisition: $45"
    }
  ],
  "after": null
}

Retrieve Block Children

Retrieves the child blocks of a parent block in Notion with pagination support.

Operation Type: Query (Read)

Parameters:

blockId string (required): The ID of the parent block to retrieve children from
startCursor string (nullable): Pagination cursor for starting position
pageSize number (nullable): Number of children to retrieve (max 100)

Returns:

results array of objects: The child block objects
hasMore boolean: Whether there are more results available
nextCursor string (nullable): Cursor for next page of results

Example Usage:

{
  "blockId": "550e8400-e29b-41d4-a716-446655440000",
  "startCursor": null,
  "pageSize": 50
}

Search

Search operations for finding pages and databases in Notion.

Search Content

Searches for pages and databases in Notion using the provided query. Supports filtering, sorting, and pagination.

Operation Type: Query (Read)

Parameters:

query string (required): The search query to find pages and databases
filter object (nullable): Filter criteria with property and value
- property string: Property to filter by
- value string: Filter value
sortBy string (nullable): Sort direction: ascending or descending
pageSize number (nullable): Number of results to return (max 100)
startCursor string (nullable): Pagination cursor for next page of results

Returns:

results array of objects: The search results
- id string: The ID of the result
- type string: The type of result (page or database)
- title string: The title of the result
- url string: The URL of the result
- lastEditedTime string: When the result was last edited
hasMore boolean: Whether there are more results available
nextCursor string (nullable): Cursor for next page of results

Example Usage:

{
  "query": "marketing campaign Q1 2024",
  "filter": {
    "property": "object",
    "value": "page"
  },
  "sortBy": "descending",
  "pageSize": 25,
  "startCursor": null
}

Common Use Cases

Knowledge Base Management:

Create structured documentation pages in databases with consistent properties
Update page titles and properties to reflect current project status
Search across all workspace content to find relevant documentation quickly

Content Organization:

Append new content blocks to existing pages for collaborative editing
Retrieve block children to analyze page structure and content hierarchy
Organize information with headings, paragraphs, and structured content blocks

Team Collaboration:

List workspace users to understand team composition and access levels
Create project pages with assigned owners and status tracking properties
Update page properties to reflect changing priorities and project milestones

Automated Workflows:

Search for pages matching specific criteria to trigger automated updates
Create standardized page templates with predefined properties and content structure
Retrieve and analyze page content for reporting and analytics purposes