> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/notion.md).

# Notion

Notion is a workspace that helps you organize and share information.

* Knowledge base source
* MCP connection

### Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

| Connector    | Authentication |
| ------------ | -------------- |
| Notion       | OAuth sign-in  |
| Notion (MCP) | MCP with OAuth |
| Notion       | API Key        |

#### Notion

Connect to Notion to access and manage your pages, databases, and content. Supports reading and writing to Notion workspaces and documents.

**Set up in Notion**

1. Sign in to Notion and choose the workspace to authorize.
2. Select the pages and databases you want to grant access to, then approve.

**Set up in StackAI**

1. Open **Settings → Connections**, add a connection, and select **Notion**.
2. Select **Connect**, sign in to the provider account, and review the requested access. Complete authorization to return to StackAI.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

StackAI obtains the OAuth credentials during sign-in. You do not need to paste an access token or refresh token.

**Provider documentation:** [Setup reference](https://developers.notion.com/docs/authorization).

#### Notion (MCP)

Connect to Notion's MCP server for AI-powered access to your Notion workspace. Uses Notion's native MCP authentication.

**Set up in Notion**

1. Complete Notion's one-click MCP OAuth flow (Notion MCP requires user-based OAuth; it does not accept a static token).

**Set up in StackAI**

1. Open **Settings → Connections**, add a connection, and select **Notion (MCP)**.
2. Select **Connect**, sign in to the provider account, and review the requested access. Complete authorization to return to StackAI.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field          | Required                 | What to enter                                                                                                                                                                                                         |
| ---------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Client Secret          | Optional / as applicable | The OAuth client secret (e.g., 1234567890). You may not need to set this, the OAuth flow will try to set it with Dynamic Client Registration, but some MCP Servers don't support it, so they require a Client Secret. |
| Custom Headers         | Optional / as applicable | Enter the custom headers issued for the account or service you are connecting.                                                                                                                                        |
| MCP Server URL         | Yes                      | The MCP server URL (e.g., <https://mcp.example.com>).                                                                                                                                                                 |
| Client ID              | Optional / as applicable | The OAuth client ID (e.g., 1234567890). You may not need to set this, the OAuth flow will try to set it with Dynamic Client Registration, but some MCP Servers don't support it, so they require a Client ID.         |
| Authorization Endpoint | Optional / as applicable | The OAuth endpoint URL (e.g., <https://mcp.example.com/oauth2/authorize>). You probably don't have to set this, the OAuth flow will try to discover it on its own.                                                    |
| Description            | Optional / as applicable | Optional description for this MCP server connection.                                                                                                                                                                  |

**Provider documentation:** [Setup reference](https://developers.notion.com/guides/mcp/get-started-with-mcp).

#### Notion

Connect to Notion to access and manage your pages, databases, and content. Supports reading and writing to Notion workspaces and documents.

**Set up in Notion**

1. Go to <https://www.notion.so/my-integrations> and create a new internal integration in the workspace you want to connect.
2. Open the integration and, under **Internal Integration Secret**, click **Show** and copy the token (it starts with `ntn_`).

**Set up in StackAI**

1. Open **Settings → Connections**, add a connection, and select **Notion**.
2. Enter the credentials and connection details in the fields below.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field | Required | What to enter                                                                                                                                                                                                                                                                                                                                                                            |
| ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| API Key       | Yes      | Your Notion Integration Token (Internal Integration). You can create one at <https://www.notion.so/profile/integrations>. Note: Internal integrations can only access pages and databases that have been explicitly shared with the integration. To access private pages, you must share them with the integration. [Provider instructions](https://www.notion.so/profile/integrations). |

**Provider documentation:** [Setup reference](https://developers.notion.com/guides/get-started/internal-connections).

#### Verify the connection

Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

### Use an action

1. Add the required **Notion** action to the workflow.
2. Select a connection when the action requests one.
3. Complete the required fields. Use the reference picker when a value comes from another workflow step.
4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

### Actions

#### Create Page

Create a new Notion page as a child of an existing page

**Inputs**

| Field       | Type            | Required | Description                                                                                           |
| ----------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| Parent Page | select (string) | Yes      | Select the parent page under which to create the new page. Options load from the selected connection. |
| Title       | string          | Yes      | The title of the new page.                                                                            |
| Content     | textarea        | Yes      | The content to write to the new page.                                                                 |

**Outputs**

| Field    | Type   | Description                         |
| -------- | ------ | ----------------------------------- |
| Page ID  | string | The ID of the created Notion page.  |
| Page URL | string | The URL of the Notion page.         |
| Message  | string | Status message about the operation. |

#### Write to Page

Add content to an existing Notion page

**Inputs**

| Field   | Type            | Required | Description                                                                   |
| ------- | --------------- | -------- | ----------------------------------------------------------------------------- |
| Page    | select (string) | Yes      | Select the page to add content to. Options load from the selected connection. |
| Content | textarea        | Yes      | The content to append to the page.                                            |

**Outputs**

| Field    | Type   | Description                         |
| -------- | ------ | ----------------------------------- |
| Page ID  | string | The ID of the updated Notion page.  |
| Page URL | string | The URL of the Notion page.         |
| Message  | string | Status message about the operation. |

#### Get Database

Retrieve rows from a Notion database. Accepts a database URL or ID, optional filter (JSON), and returns all matching rows or just the first page.

**Inputs**

| Field                | Type    | Required | Description                                                                                                                                                                                                                                      |
| -------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Database URL or ID   | string  | Yes      | The Notion database URL or ID. You can paste the URL from your browser or enter the database ID directly.                                                                                                                                        |
| Retrieve Full Table  | boolean | No       | When enabled, retrieves all rows from the database (up to a safety limit). When disabled, only the first page of results is returned. Default: true.                                                                                             |
| Filter (JSON)        | string  | No       | Optional Notion filter as JSON. Limits which rows are returned. Use property name or id plus a type-specific condition (e.g. checkbox.equals, status.equals, rich\_text.contains). Combine with "and" / "or" for multiple conditions. Default: . |
| Columns (JSON array) | string  | No       | Optional JSON array of property names or IDs to return. Only these columns appear in each row. Use Get Database Properties to see available names/ids. Omit or leave empty for all columns. Default: .                                           |
| Max Rows             | string  | No       | Optional maximum number of rows when retrieving the full table. Leave empty to use the default safety limit; otherwise enter a positive integer (e.g. 100). Default: .                                                                           |

**Outputs**

| Field     | Type    | Description                                                     |
| --------- | ------- | --------------------------------------------------------------- |
| Content   | string  | Human-readable JSON of database rows (column names and values). |
| Row Count | integer | The number of rows returned.                                    |

#### Get Database Properties

Get the list of properties (column names and types) for a Notion database. Accepts a database URL or ID.

**Inputs**

| Field              | Type   | Required | Description                                                                                               |
| ------------------ | ------ | -------- | --------------------------------------------------------------------------------------------------------- |
| Database URL or ID | string | Yes      | The Notion database URL or ID. You can paste the URL from your browser or enter the database ID directly. |

**Outputs**

| Field          | Type    | Description                                                                 |
| -------------- | ------- | --------------------------------------------------------------------------- |
| Content        | string  | Human-readable JSON list of property names (and id, type) for the database. |
| Property Count | integer | The number of properties (columns) in the database.                         |

#### Get Page

Get a Notion page's title, content, and properties. Accepts a page URL or ID.

**Inputs**

| Field                      | Type            | Required | Description                                                                                                                           |
| -------------------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Page (select or paste URL) | select (string) | Yes      | Select a page from the dropdown, or switch to text input to paste a Notion page URL or ID. Options load from the selected connection. |
| Include Content            | boolean         | No       | When enabled, fetches the full page content as markdown. Disable for faster metadata-only requests. Default: false.                   |

**Outputs**

| Field             | Type    | Description                                                            |
| ----------------- | ------- | ---------------------------------------------------------------------- |
| Title             | string  | The title of the Notion page.                                          |
| Content           | string  | The text content of the page in markdown format.                       |
| Page URL          | string  | The URL of the Notion page.                                            |
| Page ID           | string  | The unique identifier of the Notion page.                              |
| Properties        | dict    | Page properties with human-readable values (e.g. status, tags, dates). |
| Content Truncated | boolean | Whether the page content was truncated due to size limits.             |

#### Search Workspace

Search for pages and databases in your Notion workspace.

**Inputs**

| Field        | Type            | Required | Description                                                                                                        |
| ------------ | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| Search Query | string          | No       | Text to search for across page titles and content. Leave empty to list recent items. Default: .                    |
| Filter       | select (string) | No       | Filter results by type: pages, databases, or all. Available values: All, Pages only, Databases only. Default: all. |
| Max Results  | integer         | No       | Maximum number of results to return (default 20). Minimum: 1. Maximum: 100. Default: 20.                           |

**Outputs**

| Field        | Type        | Description                                                     |
| ------------ | ----------- | --------------------------------------------------------------- |
| Results      | dict\_array | List of matching pages and databases with title, URL, and type. |
| Result Count | integer     | Number of results returned.                                     |

#### Write to Database

Add or update rows in an existing Notion database. Provide the database URL or ID and a JSON array of rows mapping column names to values. Optionally set a match column to update existing rows instead of always creating new ones.

**Inputs**

| Field                                       | Type     | Required | Description                                                                                                                                                                                                                                                                                                                                                       |
| ------------------------------------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Database URL or ID                          | string   | Yes      | The Notion database to write rows into. Paste the database URL from your browser or enter the database ID directly. The database must be shared with your Notion integration.                                                                                                                                                                                     |
| Rows (JSON array)                           | textarea | Yes      | The rows to add or update, as a JSON array of objects. Each object maps column names to plain values (text, numbers, true/false, dates, or lists for multi-select). Column names must match the database's existing columns. Example: \[{"Name": "Acme Corp", "Status": "Active", "Deal Size": 50000}, {"Name": "Globex", "Status": "Lead", "Deal Size": 12000}]. |
| Match Column (for updates)                  | string   | No       | Optional key column used to detect existing rows. When set, a row whose value for this column matches an existing row updates that row; otherwise a new row is created. Leave empty to always create new rows.                                                                                                                                                    |
| Data Source ID (for multi-source databases) | string   | No       | Optional data source to write to. Only needed when the database has more than one data source (table). Leave empty for single-source databases; if the database has multiple data sources, the action lists the available IDs so you can pick one.                                                                                                                |

**Outputs**

| Field         | Type    | Description                                     |
| ------------- | ------- | ----------------------------------------------- |
| Created Count | integer | The number of new rows created.                 |
| Updated Count | integer | The number of existing rows updated.            |
| Page IDs      | array   | The IDs of the created or updated rows (pages). |
| Message       | string  | Status message about the operation.             |

### Important behavior

If an operation is denied, check the connection’s granted permissions and the account’s access in the provider. Reauthorize the connection when it needs additional permissions.

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/notion.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
