Notion

Retrieve a Notion block by its ID.

A block is any piece of content in Notion - paragraphs, headings, lists, etc. Pages and databases are also blocks.

Args:

• blockId: The block ID
• format: Response format ('json' or 'markdown')

Returns: The block object with its type-specific content.

{
  "type": "object",
  "required": [
    "blockId"
  ],
  "properties": {
    "format": {
      "enum": [
        "json",
        "markdown"
      ],
      "type": "string"
    },
    "blockId": {
      "type": "string",
      "description": "The block ID"
    }
  }
}

Get the children blocks of a block or page.

Use this to read the content of a page or the nested content of a block.

Args:

• blockId: The block ID (or page ID) to get children from
• startCursor: Pagination cursor from previous response
• pageSize: Number of blocks to return (1-100, default: 100)
• format: Response format ('json' or 'markdown')

Returns: Paginated list of child blocks.

{
  "type": "object",
  "required": [
    "blockId"
  ],
  "properties": {
    "format": {
      "enum": [
        "json",
        "markdown"
      ],
      "type": "string"
    },
    "blockId": {
      "type": "string",
      "description": "The block or page ID"
    },
    "pageSize": {
      "type": "integer",
      "default": 100,
      "maximum": 100,
      "minimum": 1,
      "description": "Number of blocks"
    },
    "startCursor": {
      "type": "string",
      "description": "Pagination cursor"
    }
  }
}

Append new blocks as children of an existing block or page.

Use this to add content to a page or nest content inside a block.

Args:

• blockId: The block or page ID to append children to
• children: Array of block objects to append. Common block types:
  • Paragraph: { "type": "paragraph", "paragraph": { "rich_text": [{ "type": "text", "text": { "content": "Hello" } }] } }
  • Heading 1: { "type": "heading_1", "heading_1": { "rich_text": [{ "type": "text", "text": { "content": "Title" } }] } }
  • Heading 2: { "type": "heading_2", "heading_2": { "rich_text": [...] } }
  • Heading 3: { "type": "heading_3", "heading_3": { "rich_text": [...] } }
  • Bulleted list: { "type": "bulleted_list_item", "bulleted_list_item": { "rich_text": [...] } }
  • Numbered list: { "type": "numbered_list_item", "numbered_list_item": { "rich_text": [...] } }
  • To-do: { "type": "to_do", "to_do": { "rich_text": [...], "checked": false } }
  • Toggle: { "type": "toggle", "toggle": { "rich_text": [...] } }
  • Quote: { "type": "quote", "quote": { "rich_text": [...] } }
  • Callout: { "type": "callout", "callout": { "rich_text": [...], "icon": { "emoji": "..." } } }
  • Code: { "type": "code", "code": { "rich_text": [...], "language": "javascript" } }
  • Divider: { "type": "divider", "divider": {} }
  • Image: { "type": "image", "image": { "type": "external", "external": { "url": "..." } } }
  • Bookmark: { "type": "bookmark", "bookmark": { "url": "..." } }

Returns: The appended blocks.

{
  "type": "object",
  "required": [
    "blockId",
    "children"
  ],
  "properties": {
    "blockId": {
      "type": "string",
      "description": "The block or page ID"
    },
    "children": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Array of block objects to append"
    }
  }
}

Update an existing block's content.

Args:

• blockId: The block ID to update
• content: The block content to update. Must include the block type. Example for paragraph: { "paragraph": { "rich_text": [{ "type": "text", "text": { "content": "New text" } }] } } To archive a block: { "archived": true }

Returns: The updated block object.

{
  "type": "object",
  "required": [
    "blockId",
    "content"
  ],
  "properties": {
    "blockId": {
      "type": "string",
      "description": "The block ID"
    },
    "content": {
      "type": "object",
      "description": "Block content to update"
    }
  }
}

Delete (trash) a block.

The block and all its children will be moved to trash.

Args:

• blockId: The block ID to delete

Returns: The deleted block object (with archived: true).

{
  "type": "object",
  "required": [
    "blockId"
  ],
  "properties": {
    "blockId": {
      "type": "string",
      "description": "The block ID to delete"
    }
  }
}

Retrieve comments from a page or block.

Gets all comments associated with a page or specific block.

Args:

• blockId: The page ID or block ID to get comments from
• startCursor: Pagination cursor from previous response
• pageSize: Number of comments to return (1-100, default: 100)
• format: Response format ('json' or 'markdown')

Returns: Paginated list of comments with their text, author, and timestamps.

{
  "type": "object",
  "required": [
    "blockId"
  ],
  "properties": {
    "format": {
      "enum": [
        "json",
        "markdown"
      ],
      "type": "string"
    },
    "blockId": {
      "type": "string",
      "description": "The page or block ID"
    },
    "pageSize": {
      "type": "integer",
      "default": 100,
      "maximum": 100,
      "minimum": 1,
      "description": "Number of comments"
    },
    "startCursor": {
      "type": "string",
      "description": "Pagination cursor"
    }
  }
}

Create a new comment on a page or in a discussion.

Args:

• parentId: Either a page_id to start a new comment thread, or a discussion_id to reply in an existing thread
• parentType: Type of parent - 'page_id' for new threads, 'discussion_id' for replies
• richText: Comment text as rich text array. Example: [{ "type": "text", "text": { "content": "This is a comment" } }] Can include mentions: [{ "type": "mention", "mention": { "type": "user", "user": { "id": "user-id" } } }]

Returns: The created comment object.

{
  "type": "object",
  "required": [
    "parentId",
    "parentType",
    "richText"
  ],
  "properties": {
    "parentId": {
      "type": "string",
      "description": "Page ID or discussion ID"
    },
    "richText": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Comment text as rich text array"
    },
    "parentType": {
      "enum": [
        "page_id",
        "discussion_id"
      ],
      "type": "string",
      "description": "Type of parent"
    }
  }
}

Retrieve a specific comment by its ID.

Args:

• commentId: The comment ID
• format: Response format ('json' or 'markdown')

Returns: The comment object with its text, author, and timestamps.

{
  "type": "object",
  "required": [
    "commentId"
  ],
  "properties": {
    "format": {
      "enum": [
        "json",
        "markdown"
      ],
      "type": "string"
    },
    "commentId": {
      "type": "string",
      "description": "The comment ID"
    }
  }
}

Retrieve a Notion database by its ID.

Returns the database object with its schema (properties), title, and metadata.

Args:

• databaseId: The database ID
• format: Response format ('json' or 'markdown')

Returns: The database object with all properties and their configurations.

{
  "type": "object",
  "required": [
    "databaseId"
  ],
  "properties": {
    "format": {
      "enum": [
        "json",
        "markdown"
      ],
      "type": "string"
    },
    "databaseId": {
      "type": "string",
      "description": "The database ID"
    }
  }
}

Query a Notion database to retrieve pages that match filter criteria.

Args:

• databaseId: The database ID to query
• filter: Optional filter object using Notion's filter syntax. Example: { "property": "Status", "status": { "equals": "Done" } } Compound filters use "and" or "or" arrays.
• sorts: Optional array of sort objects. Example: [{ "property": "Created", "direction": "descending" }] Or use timestamp: [{ "timestamp": "last_edited_time", "direction": "descending" }]
• startCursor: Pagination cursor from previous response
• pageSize: Number of results to return (1-100, default: 100)
• format: Response format ('json' or 'markdown')

Returns: Paginated list of pages that match the query.

{
  "type": "object",
  "required": [
    "databaseId"
  ],
  "properties": {
    "sorts": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Array of sort objects"
    },
    "filter": {
      "type": "object",
      "description": "Filter object"
    },
    "format": {
      "enum": [
        "json",
        "markdown"
      ],
      "type": "string"
    },
    "pageSize": {
      "type": "integer",
      "default": 100,
      "maximum": 100,
      "minimum": 1,
      "description": "Number of results"
    },
    "databaseId": {
      "type": "string",
      "description": "The database ID"
    },
    "startCursor": {
      "type": "string",
      "description": "Pagination cursor"
    }
  }
}

Create a new Notion database as a child of a page.

Args:

• parentPageId: The ID of the parent page where the database will be created
• title: Database title as rich text array. Simple example: [{ "type": "text", "text": { "content": "My Database" } }]
• properties: Database schema defining the columns. Each property has a name and type config. Example: { "Name": { "title": {} }, "Status": { "select": { "options": [{ "name": "Todo" }, { "name": "Done" }] } }, "Date": { "date": {} } }
• icon: Optional icon object
• cover: Optional cover image object

Returns: The created database object.

{
  "type": "object",
  "required": [
    "parentPageId",
    "title",
    "properties"
  ],
  "properties": {
    "icon": {
      "description": "Icon object"
    },
    "cover": {
      "description": "Cover image object"
    },
    "title": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Title as rich text array"
    },
    "properties": {
      "type": "object",
      "description": "Database schema/properties"
    },
    "parentPageId": {
      "type": "string",
      "description": "Parent page ID"
    }
  }
}

Update a Notion database's title, description, or properties.

Args:

• databaseId: The database ID to update
• title: New title as rich text array
• description: New description as rich text array
• properties: Properties to add, update, or remove. To remove a property, set it to null. Example: { "New Column": { "checkbox": {} }, "Old Column": null }
• icon: New icon object, or null to remove
• cover: New cover object, or null to remove

Returns: The updated database object.

{
  "type": "object",
  "required": [
    "databaseId"
  ],
  "properties": {
    "icon": {
      "description": "New icon"
    },
    "cover": {
      "description": "New cover"
    },
    "title": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "New title as rich text"
    },
    "databaseId": {
      "type": "string",
      "description": "The database ID"
    },
    "properties": {
      "type": "object",
      "description": "Properties to update"
    },
    "description": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "New description"
    }
  }
}

Retrieve a Notion page by its ID.

Args:

• pageId: The page ID (can be with or without hyphens)
• format: Response format ('json' or 'markdown')

Returns: The page object with all properties, metadata, and parent information.

{
  "type": "object",
  "required": [
    "pageId"
  ],
  "properties": {
    "format": {
      "enum": [
        "json",
        "markdown"
      ],
      "type": "string"
    },
    "pageId": {
      "type": "string",
      "description": "The page ID"
    }
  }
}

Create a new Notion page.

The page can be created as a child of a database (with database_id) or as a child of another page (with page_id).

Args:

• parentId: The ID of the parent (database or page)
• parentType: Type of parent - 'database_id' for database pages, 'page_id' for child pages
• properties: Page properties object. For database pages, must include properties matching the database schema. For child pages, typically just { "title": { "title": [{ "text": { "content": "Page Title" } }] } }
• children: Optional array of block objects to add as page content
• icon: Optional icon object { "type": "emoji", "emoji": "..." } or { "type": "external", "external": { "url": "..." } }
• cover: Optional cover object { "type": "external", "external": { "url": "..." } }

Returns: The created page object.

{
  "type": "object",
  "required": [
    "parentId",
    "properties"
  ],
  "properties": {
    "icon": {
      "description": "Icon object"
    },
    "cover": {
      "description": "Cover image object"
    },
    "children": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Array of block objects for page content"
    },
    "parentId": {
      "type": "string",
      "description": "Parent database or page ID"
    },
    "properties": {
      "type": "object",
      "description": "Page properties object"
    }
  }
}

Update an existing Notion page's properties.

Args:

• pageId: The page ID to update
• properties: Properties to update (only include properties you want to change)
• archived: Set to true to archive the page, false to unarchive
• icon: New icon object, or null to remove
• cover: New cover object, or null to remove

Returns: The updated page object.

{
  "type": "object",
  "required": [
    "pageId"
  ],
  "properties": {
    "icon": {
      "description": "New icon object"
    },
    "cover": {
      "description": "New cover object"
    },
    "pageId": {
      "type": "string",
      "description": "The page ID to update"
    },
    "archived": {
      "type": "boolean",
      "description": "Archive or unarchive the page"
    },
    "properties": {
      "type": "object",
      "description": "Properties to update"
    }
  }
}

Move a Notion page to trash.

This is equivalent to deleting the page. The page can be restored from trash within Notion.

Args:

• pageId: The page ID to trash

Returns: The trashed page object.

{
  "type": "object",
  "required": [
    "pageId"
  ],
  "properties": {
    "pageId": {
      "type": "string",
      "description": "The page ID to trash"
    }
  }
}

Retrieve a specific property value from a page.

This is useful for paginated properties like title, rich_text, relation, and people, where the full value may not be returned in the page object.

Args:

• pageId: The page ID
• propertyId: The property ID (from the page's properties object)
• startCursor: Pagination cursor for paginated properties
• pageSize: Number of items to return (for paginated properties)

Returns: The property value or paginated list of property items.

{
  "type": "object",
  "required": [
    "pageId",
    "propertyId"
  ],
  "properties": {
    "pageId": {
      "type": "string",
      "description": "The page ID"
    },
    "pageSize": {
      "type": "integer",
      "maximum": 100,
      "minimum": 1,
      "description": "Page size"
    },
    "propertyId": {
      "type": "string",
      "description": "The property ID"
    },
    "startCursor": {
      "type": "string",
      "description": "Pagination cursor"
    }
  }
}

Search for pages and databases in Notion by title.

Searches across all pages and databases that have been shared with the integration.

Args:

• query: Optional search query string. Searches by title match. If empty, returns all accessible pages/databases.
• filter: Optional filter to search only pages or only databases. Example: { "value": "page", "property": "object" } Or: { "value": "database", "property": "object" }
• sort: Optional sort configuration. Example: { "direction": "ascending", "timestamp": "last_edited_time" } Or: { "direction": "descending", "timestamp": "last_edited_time" }
• startCursor: Pagination cursor from previous response
• pageSize: Number of results to return (1-100, default: 100)
• format: Response format ('json' or 'markdown')

Returns: Paginated list of matching pages and/or databases.

{
  "type": "object",
  "properties": {
    "sort": {
      "type": "object",
      "description": "Sort configuration"
    },
    "query": {
      "type": "string",
      "description": "Search query string"
    },
    "filter": {
      "type": "object",
      "description": "Filter for pages or databases only"
    },
    "format": {
      "enum": [
        "json",
        "markdown"
      ],
      "type": "string"
    },
    "pageSize": {
      "type": "integer",
      "default": 100,
      "maximum": 100,
      "minimum": 1,
      "description": "Number of results"
    },
    "startCursor": {
      "type": "string",
      "description": "Pagination cursor"
    }
  }
}

List all users in the Notion workspace.

Returns a paginated list of all users (people and bots) that have access to the workspace.

Args:

• startCursor: Pagination cursor from previous response
• pageSize: Number of users to return (1-100, default: 100)
• format: Response format ('json' or 'markdown')

Returns: List of users with their IDs, names, types, and email addresses.

{
  "type": "object",
  "properties": {
    "format": {
      "enum": [
        "json",
        "markdown"
      ],
      "type": "string",
      "default": "json",
      "description": "Response format"
    },
    "pageSize": {
      "type": "integer",
      "default": 100,
      "maximum": 100,
      "minimum": 1,
      "description": "Number of users to return"
    },
    "startCursor": {
      "type": "string",
      "description": "Pagination cursor from previous response"
    }
  }
}

Get a single user by their ID.

Args:

• userId: The user's Notion ID
• format: Response format ('json' or 'markdown')

Returns: The user object with all available details.

{
  "type": "object",
  "required": [
    "userId"
  ],
  "properties": {
    "format": {
      "enum": [
        "json",
        "markdown"
      ],
      "type": "string"
    },
    "userId": {
      "type": "string",
      "description": "The user ID"
    }
  }
}

Get the current bot user (the integration making the API call).

This is useful to verify the connection and see which bot/integration is being used.

Args:

• format: Response format ('json' or 'markdown')

Returns: The bot user object for the current integration.

{
  "type": "object",
  "properties": {
    "format": {
      "enum": [
        "json",
        "markdown"
      ],
      "type": "string"
    }
  }
}