Notion Integration
Want your Notion workspace to do the work for you? Connect Notion to SmythOS and let your agents create pages, update databases, and manage content in real time.
List of Notion Components
Quickly compare Notion components by what they do, how to use them, and their key I/O. Click any component name to jump directly to its detailed guide. Here’s what's available:
Component | Action | What it Does | Inputs | Key Outputs | Use Case |
---|---|---|---|---|---|
List Users | Read | Retrieves a list of all users in the workspace. | required trigger | users , response | Get a list of team members to assign tasks. |
Search by Title | Search | Finds pages or databases by their title. | required query | results , response | Find a specific project page before updating it. |
Fetch Page | Read | Retrieves a complete Page object by its ID. | required page_id | pageId , pageUrl , response | Get the full content of a page for processing. |
Retrieve Database | Read | Gets the structure and properties of a database. | required database_id | databaseId , response | Check database schema before adding new entries. |
Query Database | Search | Filters and sorts pages within a database. | required database_id optional body | results , response | Find all tasks assigned to a specific user. |
Retrieve Comments | Read | Fetches unresolved comments from a page or block. | required block_id | results , response | Monitor feedback or questions on a project brief. |
Create Page | Write | Creates a new page inside a parent page. | required page_id , title | pageId , pageUrl | Automatically create a new meeting notes page. |
Create Database | Write | Creates a new database as a sub-page. | required page_id , title optional body | databaseId , databaseUrl | Generate a new project tracker database from a template. |
Create Comment | Write | Adds a comment to a page or discussion thread. | required page_id , text | commentId , discussionId | Have an agent post automated status updates. |
Update Database | Write | Modifies the title or properties of a database. | required database_id optional body | databaseId , databaseUrl | Rename a database or add a new property column. |
Prerequisites
Before you begin the integration, please ensure you have the following:
- An active SmythOS account. (If you're new to SmythOS, you can sign up here.)
- A Notion Account with permission to create integrations.
- The Notion pages or databases you want to automate must be shared with your integration.
Getting Started With Notion
The connection between SmythOS and Notion is configured using a secure token.
Step 1: Create a Notion Integration & Get Your Secret
-
In your Notion workspace, go to Settings & Members > Integrations.
-
Click Develop your own integrations.
-
Click + New integration. Give it a name (e.g., "SmythOS Agent") and associate it with your workspace.
-
On the next screen, you will see your Internal Integration Secret. Click Show and then Copy this token. This is the key you'll use in SmythOS.
Step 2: Store Your Secret in SmythOS Vault
Treat your Integration Secret like a password. SmythOS provides a secure Vault
for this.
- In your SmythOS dashboard, navigate to the Vault.
- Create a new secret and paste your Notion Integration Secret as the value. Give it a memorable name, like
notion_secret
. - For more details, see the Vault Documentation.
Step 3: Share Your Pages/Databases with the Integration
For SmythOS to access a page or database, you must share it with the integration you created.
-
Navigate to the Notion page or database you want your agent to access.
-
Click the Share button in the top-right corner.
-
Click the input field and find your integration by the name you gave it (e.g., "SmythOS Agent").
-
Click Invite. The integration now has permission to edit (or view) that page and any child pages within it.
Step 4: Configure a Notion Component
- In your SmythOS agent graph, drag and drop any Notion component.
- Click the component to open its settings.
- In the
Integration Secret
field, select the secret you saved in the Vault (e.g.,notion_secret
). - Your connection is now configured for that component!
Component Details
This section provides detailed information for each Notion component.
List Users — Read Workspace Users
Retrieves a paginated list of all users associated with the Notion workspace.
Inputs
Field | Required | Notes |
---|---|---|
trigger | required | Any value can be used to trigger the component's execution. |
Outputs
Field | Description |
---|---|
users | An array containing the list of user objects from the workspace. |
response | Full raw response returned by the Notion API for debugging. |
headers | HTTP headers from the API response. |
Create Comment — Add a Comment
Creates a new comment on a page or within an existing discussion thread.
Inputs
Field | Required | Notes |
---|---|---|
page_id | required | The ID of the page where the comment should be added. |
text | required | The rich text content of the comment. |
Outputs
Field | Description |
---|---|
commentId | The unique ID of the newly created comment. |
discussionId | The ID of the discussion thread the comment belongs to. |
response | Raw API payload for debugging. |
headers | HTTP headers from the API response. |
Create Page — Add a New Page
Creates a new page as a child of a specified parent page.
Inputs
Field | Required | Notes |
---|---|---|
page_id | required | The ID of the parent page under which the new page will be created. |
title | required | The title of the new page to be created. |
Outputs
Field | Description |
---|---|
pageId | The unique ID of the newly created page. Essential for future steps. |
pageUrl | A direct URL to the newly created Notion page. |
response | Raw API payload for debugging. |
headers | HTTP headers from the API response. |
Fetch Page — Read a Page
Retrieves a full Page object, including its properties and content, using its unique ID.
Inputs
Field | Required | Notes |
---|---|---|
page_id | required | The unique identifier of the page you want to retrieve. |
Outputs
Field | Description |
---|---|
pageId | The ID of the retrieved page. |
pageUrl | The direct URL to the retrieved page. |
response | Full raw Page object from the Notion API. |
headers | HTTP headers from the API response. |
Retrieve Database — Get Database Schema
Retrieves the structure of a database, including its properties (columns), title, and description.
Inputs
Field | Required | Notes |
---|---|---|
database_id | required | The unique identifier of the database you want to retrieve. |
Outputs
Field | Description |
---|---|
databaseId | The ID of the retrieved database. |
response | The full raw Database object from the Notion API, detailing its schema. |
headers | HTTP headers from the API response. |
Create Database — Add a New Database
Creates a new database as a subpage within a specified parent page.
Inputs
Field | Required | Notes |
---|---|---|
page_id | required | The ID of the parent page for the new database. |
title | required | The title of the new database. |
body | optional | JSON object defining the properties (columns) of the new database. |
Outputs
Field | Description |
---|---|
databaseId | The unique ID of the newly created database. |
databaseUrl | A direct URL to the new database. |
response | Raw API payload for debugging. |
headers | HTTP headers from the API response. |
Retrieve Comments — Get Unresolved Comments
Retrieves a list of all unresolved comment threads from a specific page or block.
Inputs
Field | Required | Notes |
---|---|---|
block_id | required | The ID of the page or block from which to retrieve comments. |
Outputs
Field | Description |
---|---|
results | An array of unresolved comment objects. |
response | Raw API payload for debugging. |
headers | HTTP headers from the API response. |
Query Database — Search a Database
Retrieves a list of pages from a database, with optional filters and sorting criteria.
Inputs
Field | Required | Notes |
---|---|---|
database_id | required | The ID of the database to query. |
body | optional | A JSON object containing filter and/or sorts conditions. |
Outputs
Field | Description |
---|---|
results | An array of page objects that match the query criteria. |
response | Raw API payload for debugging. |
headers | HTTP headers from the API response. |
Update Database — Modify a Database
Modifies the attributes of an existing database, such as its title, description, or properties.
Inputs
Field | Required | Notes |
---|---|---|
database_id | required | The unique ID of the database you wish to update. |
body | optional | Payload containing new database details (e.g., title , description ). |
Outputs
Field | Description |
---|---|
databaseId | The ID of the updated database. |
databaseUrl | The URL to the updated database. |
response | Raw API payload for debugging. |
headers | HTTP headers from the API response. |
Search by Title — Find Pages or Databases
Searches all pages and databases that have been shared with the integration to find matches for a query string.
Inputs
Field | Required | Notes |
---|---|---|
query | required | The text to compare against page and database titles. |
Outputs
Field | Description |
---|---|
results | An array of page or database objects that match the title query. |
response | Raw API payload for debugging. |
headers | HTTP headers from the API response. |
Best Practices & Advanced Tips
- Secure Your Integration Secret: Always use the SmythOS
Vault
to store your Notion Integration Secret. Never hardcode it directly in your components. - Manage Permissions Carefully: In Notion, only share the specific pages and databases that your agent needs to access. This follows the principle of least privilege and enhances security.
- Use Dynamic IDs: Instead of hardcoding
page_id
ordatabase_id
, use outputs from previous steps. For example, use thepageId
from a "Create Page" component as the input for a "Create Comment" component. - Master Database Queries: The "Query Database" component is extremely powerful. Invest time in learning the Notion filter syntax to build highly specific and efficient automations.
- Handle Errors Gracefully: Check component outputs for errors. The
response
object often contains detailed error messages from the Notion API that are crucial for debugging. - Understand the Notion Data Model: Familiarize yourself with how Notion structures data (pages, blocks, databases, properties). This knowledge will help you construct the correct JSON
body
for components like "Create Database" and "Query Database".
What's Next?
Congratulations! You've successfully set up the SmythOS Notion integration. You're now ready to build intelligent agents that can manage your workspace, automate content, and streamline your workflows.
Consider these next steps:
- Build an Agent That...
- Monitors a Slack channel for requests and creates corresponding tasks in a Notion database.
- Receives an email with an attachment, summarizes its content using an AI component, and creates a new page in Notion with the summary and a link to the attachment.
- Reads a list of new blog post ideas from a Google Sheet, then creates a draft page for each one in your Notion content calendar.
- Explore Other Integrations: Combine the power of Notion with other SmythOS connectors like Google Calendar, Slack, or Gmail to create end-to-end automation solutions.