search
Perform a search over:
- "internal": Perform a semantic search over your entire Notion workspace and connected
sources (Slack, Google Drive, Github, Jira, Microsoft Teams, Sharepoint, OneDrive, or
Linear).
- "users": Perform a search over the Notion users in the current workspace.
You can use search when you need to find information which is not already available via
other tools, and you don't know where it's located.
If the user doesn't have access to Notion AI features, the search will automatically fall
back to a workspace search that doesn't use AI or include connected sources. This will be
indicated by the "type" field in the response being "workspace_search" instead of
"ai_search".
Do NOT use search to get information about a Database's integrations, views, or other
components.
If initial results do not contain all the information you need, you can try more specific
queries.
After obtaining internal search results, if the user asks for the full contents of a page or
database, use the "fetch" tool. This tool only shows some details like a highlight and the
URL and title of each search result.
To find pages under a Notion database, use this tool and supply the database's URL as the
data_source_url parameter. These look like "collection://f336d0bc-b841-465b-8045-024475c079dd".
You can get this URL by using the "fetch" tool to view the database and copying the URL from
the <data-source url="..."> block. Keep in mind that Notion-flavored Markdown has this
concept of a hierarchy of <database> blocks that contain <data-source> blocks, but users
aren't familiar with the Notion "Data Source" terminology or product. Prefer to refer to
both of them as "databases" in your response to humans to avoid confusion.
Examples of searches:
1. Search for information across the workspace:
{
"query": "quarterly revenue report",
"query_type": "internal"
}
2. Search within a specific page and its children:
{
"query": "meeting notes action items",
"query_type": "internal",
"page_url": "https://www.notion.so/workspace/Team-Hub-1234567890abcdef"
}
3. Search within a database's pages:
{
"query": "design review feedback",
"query_type": "internal",
"data_source_url": "collection://f336d0bc-b841-465b-8045-024475c079dd"
}
4. Search within a specific teamspace:
{
"query": "project updates",
"query_type": "internal",
"teamspace_id": "f336d0bc-b841-465b-8045-024475c079dd"
}
5. Search for users:
{
"query": "
[email protected]",
"query_type": "user"
}
6. Find users by partial name:
{
"query": "sarah",
"query_type": "user"
}
Common use cases:
- "What does the sales team require from the product team in the next quarter?"
- "Find all meeting notes that mention the new pricing strategy"
- "Which pages discuss the API migration project?"
- "Find all team members with email addresses ending in @design.company.com"
- "What are the latest updates on the mobile app redesign?"
fetch
Retrieves details about a Notion entity by its URL or ID.
You can fetch the following types of entities:
- Page, i.e. from a <page> block or a <mention-page> mention
- Database, i.e. from a <database> block or a <mention-database> mention
Use the "fetch" tool when you need to see the details of a Notion entity you already know
exists and have its URL or ID.
Provide the Notion entity's URL or ID in the `id` parameter. You must make multiple calls
to the "fetch" tool if you want to fetch multiple entities.
Content for pages that are returned use the enhanced Markdown format, which is a superset of
the standard Markdown syntax. See the full spec in the description of the "create-pages"
tool.
Databases can have multiple data sources, which are collections of pages with the same schema.
When fetching a database, the tool will return information about all its data sources.
Examples of fetching entities:
1. Fetch a page by URL:
{
"id": "https://www.notion.so/workspace/Product-Requirements-1234567890abcdef"
}
2. Fetch a page by ID (UUIDv4 with dashes):
{
"id": "12345678-90ab-cdef-1234-567890abcdef"
}
3. Fetch a page by ID (UUIDv4 without dashes):
{
"id": "1234567890abcdef1234567890abcdef"
}
4. Fetch a database:
{
"id": "https://www.notion.so/workspace/Projects-Database-abcdef1234567890"
}
Common use cases:
- "What are the product requirements still need to be implemented from this ticket
https://notion.so/page-url?"
- "Show me the details of the project database at this URL"
- "Get the content of page 12345678-90ab-cdef-1234-567890abcdef"
notion-create-pages
Creates one or more Notion pages with specified properties and content.
Use "create-pages" when you need to create one or more new pages that don't exist yet.
Always include a title property under `properties` in each entry of the `pages` array.
Otherwise, the page title will appear blank even if the page content is populated. Don't
duplicate the page title at the top of the page's `content`.
When creating pages under a Notion database, the property names must match the database's
schema. Use the "fetch" tool with a Notion database URL to get the database schema. Or, look
for existing pages under the database using the "search" tool then use the "fetch" tool to see
the names of the property keys. One exception is the "title" property, which all pages have,
but can be named differently in the schema of a database. For convenience, you can use the
generic property name "title" in the "properties" object, and it will automatically be
re-mapped to the actual name of the title property in the database schema when creating the
page.
All pages created with a single call to this tool will have the same parent.
The parent can be a Notion page or database. If the parent is omitted, the pages will be
created as standalone, workspace-level private pages and the person that created them
can organize them as they see fit later.
IMPORTANT: When specifying a parent database, use the appropriate ID format:
- Use "data_source_id" when you have a collection:// URL from the fetch tool (this is the most common case)
- Use "database_id" when you have a page URL for a database view (less common)
- Use "page_id" when the parent is a regular page
Examples of creating pages:
1. Create a standalone page with a title and content:
{
"pages": [
{
"properties": {"title":"Page title"},
"content": "# Section 1
Section 1 content
# Section 2
Section 2 content"
}
]
}
2. Create a page under a database's data source (collection), e.g. using an ID from a collection:// URL provided by the fetch tool:
{
"parent": {"data_source_id": "f336d0bc-b841-465b-8045-024475c079dd"},
"pages": [
{
"properties": {
"Task Name": "Task 123",
"Status": "In Progress",
},
},
],
}
3. Create a page with an existing page as a parent:
{
"parent": {"page_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"},
"pages": [
{
"properties": {"title": "Page title"},
"content": "# Section 1
Section 1 content
# Section 2
Section 2 content"
}
]
}
The enhanced Markdown format used for page content is a superset of the standard Markdown
syntax. Here is the full spec, but please note that Notion does not yet use the Data Source
terminology, and only supports Databases. Ignore anything related to "data sources" and assume
databases can only define one schema for now.
### Notion-flavored Markdown
Notion-flavored Markdown is a variant of standard Markdown with additional features to support all Block and Rich text types.
Use tabs for indentation.
Use backslashes to escape characters. For example, * will render as * and not as a bold delimiter.
Block types:
Markdown blocks use a {color="Color"} attribute list to set a block color.
Text:
Rich text {color="Color"}
Children
Headings:
# Rich text {color="Color"}
## Rich text {color="Color"}
### Rich text {color="Color"}
(Headings 4, 5, and 6 are not supported in Notion and will be converted to heading 3.)
Bulleted list:
- Rich text {color="Color"}
Children
Numbered list:
1. Rich text {color="Color"}
Children
Rich text types:
Bold:
**Rich text**
Italic:
*Rich text*
Strikethrough:
~~Rich text~~
Underline:
<span underline="true">Rich text</span>
Inline code:
`Code`
Link:
[Link text](URL)
Citation:
[^URL]
To create a citation, you can either reference a compressed URL like [^{{1}}], or a full URL like [^https://example.com].
Colors:
<span color?="Color">Rich text</span>
Inline math:
$Equation$ or $`Equation`$ if you want to use markdown delimiters within the equation.
There must be whitespace before the starting $ symbol and after the ending $ symbol. There must not be whitespace right after the starting $ symbol or before the ending $ symbol.
Inline line breaks within rich text:
<br>
Mentions:
User:
<mention-user url="{{URL}}">User name</mention-user>
The URL must always be provided, and refer to an existing User.
But Providing the user name is optional. In the UI, the name will always be displayed.
So an alternative self-closing format is also supported: <mention-user url="{{URL}}"/>
Page:
<mention-page url="{{URL}}">Page title</mention-page>
The URL must always be provided, and refer to an existing Page.
Providing the page title is optional. In the UI, the title will always be displayed.
Mentioned pages can be viewed using the "view" tool.
Database:
<mention-database url="{{URL}}">Database name</mention-database>
The URL must always be provided, and refer to an existing Database.
Providing the database name is optional. In the UI, the name will always be displayed.
Mentioned databases can be viewed using the "view" tool.
Date:
<mention-date start="YYYY-MM-DD" end="YYYY-MM-DD"/>
Datetime:
<mention-date start="YYYY-MM-DDThh:mm:ssZ" end="YYYY-MM-DDThh:mm:ssZ"/>
Custom emoji:
:emoji_name:
Custom emoji are rendered as the emoji name surrounded by colons.
Colors:
Text colors (colored text with transparent background):
gray, brown, orange, yellow, green, blue, purple, pink, red
Background colors (colored background with contrasting text):
gray_bg, brown_bg, orange_bg, yellow_bg, green_bg, blue_bg, purple_bg, pink_bg, red_bg
Usage:
- Block colors: Add color="Color" to the first line of any block
- Rich text colors (text colors and background colors are both supported): Use <span color="Color">Rich text</span>
#### Advanced Block types for Page content
The following block types may only be used in page content.
<advanced-blocks>
Quote:
> Rich text {color="Color"}
Children
To-do:
- [ ] Rich text {color="Color"}
Children
- [x] Rich text {color="Color"}
Children
Toggle:
▶ Rich text {color="Color"}
Children
Toggle heading 1:
▶# Rich text {color="Color"}
Children
Toggle heading 2:
▶## Rich text {color="Color"}
Children
Toggle heading 3:
▶### Rich text {color="Color"}
Children
For toggles and toggle headings, the children must be indented in order for them to be toggleable. If you do not indent the children, they will not be contained within the toggle or toggle heading.
Divider:
---
Table:
<table fit-page-width?="true|false" header-row?="true|false" header-column?="true|false">
<colgroup>
<col color?="Color">
<col color?="Color">
</colgroup>
<tr color?="Color">
<td>Data cell</td>
<td color?="Color">Data cell</td>
</tr>
<tr>
<td>Data cell</td>
<td>Data cell</td>
</tr>
</table>
Note: All table attributes are optional. If omitted, they default to false.
Table structure:
- <table>: Root element with optional attributes:
- fit-page-width: Whether the table should fill the page width
- header-row: Whether the first row is a header
- header-column: Whether the first column is a header
- <colgroup>: Optional element defining column-wide styles
- <col>: Column definition with optional attributes:
- color: The color of the column
- width: The width of the column. Leave empty to auto-size.
- <tr>: Table row with optional color attribute
- <td>: Data cell with optional color attribute
Color precedence (highest to lowest):
1. Cell color (<td color="red">)
2. Row color (<tr color="blue_bg">)
3. Column color (<col color="gray">)
Equation:
$$
Equation
$$
Code:
```language
Code
```
XML blocks use the "color" attribute to set a block color.
Callout:
<callout icon?="emoji" color?="Color">
Children
</callout>
Columns:
<columns>
<column>
Children
</column>
<column>
Children
</column>
</columns>
Page:
<page url="{{URL}}" color?="Color">Title</page>
Sub-pages can be viewed using the "view" tool.
To create a new sub-page, omit the URL. You can then update the page content and properties with the "update-page" tool. Example: <page>New Page</page>
Database:
<database url="{{URL}}" inline?="{true|false}" color?="Color">Title</database>
To create a new database, omit the URL. You can then update the database properties and content with the "update-database" tool. Example: <database>New Database</database>
The "inline" toggles how the database is displayed in the UI. If it is true, the database is fully visible and interactive on the page. If false, the database is displayed as a sub-page.
There is no "Data Source" block type. Data Sources are always inside a Database, and only Databases can be inserted into a Page.
Audio:
<audio source="{{URL}}" color?="Color">Caption</audio>
File:
File content can be viewed using the "view" tool.
<file source="{{URL}}" color?="Color">Caption</file>
Image:
Image content can be viewed using the "view" tool.
<image source="{{URL}}" color?="Color">Caption</image>
PDF:
PDF content can be viewed using the "view" tool.
<pdf source="{{URL}}" color?="Color">Caption</pdf>
Video:
<video source="{{URL}}" color?="Color">Caption</video>
Table of contents:
<table_of_contents color?="Color"/>
Synced block:
The original source for a synced block.
When creating a new synced block, do not provide the URL. After inserting the synced block into a page, the URL will be provided.
<synced_block url?="{{URL}}">
Children
</synced_block>
Note: When creating new synced blocks, omit the url attribute - it will be auto-generated. When reading existing synced blocks, the url attribute will be present.
Synced block reference:
A reference to a synced block.
The synced block must already exist and url must be provided.
You can directly update the children of the synced block reference and it will update both the original synced block and the synced block reference.
<synced_block_reference url="{{URL}}">
Children
</synced_block_reference>
Meeting notes:
<meeting-notes>
Rich text (meeting title)
<summary>
AI-generated summary of the notes + transcript
</summary>
<notes>
User notes
</notes>
<transcript>
Transcript of the audio (cannot be edited)
</transcript>
</meeting-notes>
Note: The <transcript> tag contains a raw transcript and cannot be edited.
Unknown (a block type that is not supported in the API yet):
<unknown url="{{URL}}" alt="Alt"/>
</advanced-blocks>
notion-update-page
Update a Notion page's properties or content.
Notion page properties are a JSON map of property names to SQLite values.
For pages in a database, use the SQLite schema definition shown in <database>.
For pages outside of a database, the only allowed property is "title", which is the title of the page in inline markdown format.
Notion page content is a string in Notion-flavored Markdown format. See the "create-pages" tool description for the full enhanced Markdown spec.
Before updating a page's content with this tool, use the "fetch" tool first to get the existing content to find out the Markdown snippets to use in the "replace_content_range" or "insert_content_after" commands.
IMPORTANT: Some property types require expanded formats:
- Date properties: Split into "date:{property}:start", "date:{property}:end" (optional), and "date:{property}:is_datetime" (0 or 1)
- Place properties: Split into "place:{property}:name", "place:{property}:address", "place:{property}:latitude", "place:{property}:longitude", and "place:{property}:google_place_id" (optional)
Number properties accept JavaScript numbers (not strings). Use null to remove a property's value. Boolean values like "__YES__" are supported for checkbox properties.
Examples:
(1) Update page properties:
{
"page_id": "f336d0bc-b841-465b-8045-024475c079dd",
"command": "update_properties",
"properties": {
"title": "New Page Title",
"status": "In Progress",
"priority": 5,
"checkbox": "__YES__",
"date:deadline:start": "2024-12-25",
"date:deadline:is_datetime": 0,
"place:office:name": "HQ",
"place:office:latitude": 37.7749,
"place:office:longitude": -122.4194
}
}
(2) Replace the entire content of a page:
{
"page_id": "f336d0bc-b841-465b-8045-024475c079dd",
"command": "replace_content",
"new_str": "# New Section
Updated content goes here"
}
(3) Replace specific content in a page:
{
"page_id": "f336d0bc-b841-465b-8045-024475c079dd",
"command": "replace_content_range",
"selection_with_ellipsis": "# Old Section...end of section",
"new_str": "# New Section
Updated content goes here"
}
(4) Insert content after specific text:
{
"page_id": "f336d0bc-b841-465b-8045-024475c079dd",
"command": "insert_content_after",
"selection_with_ellipsis": "## Previous section...",
"new_str": "
## New Section
Content to insert goes here"
}
Note: For selection_with_ellipsis, provide only the first ~10 characters, an ellipsis, and the last ~10 characters. Ensure the selection is unique; use longer snippets if needed to avoid ambiguity.