Skip to main content

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.

TL;DR
Securely link your Notion account to SmythOS using an Integration Secret. Then, use our suite of Notion components to empower your agents to automate a wide range of workspace tasks, from creating pages and databases to searching for content and adding comments.

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:

ComponentActionWhat it DoesInputsKey OutputsUse Case
List UsersReadRetrieves a list of all users in the workspace.required triggerusers, responseGet a list of team members to assign tasks.
Search by TitleSearchFinds pages or databases by their title.required queryresults, responseFind a specific project page before updating it.
Fetch PageReadRetrieves a complete Page object by its ID.required page_idpageId, pageUrl, responseGet the full content of a page for processing.
Retrieve DatabaseReadGets the structure and properties of a database.required database_iddatabaseId, responseCheck database schema before adding new entries.
Query DatabaseSearchFilters and sorts pages within a database.required database_id
optional body
results, responseFind all tasks assigned to a specific user.
Retrieve CommentsReadFetches unresolved comments from a page or block.required block_idresults, responseMonitor feedback or questions on a project brief.
Create PageWriteCreates a new page inside a parent page.required page_id, titlepageId, pageUrlAutomatically create a new meeting notes page.
Create DatabaseWriteCreates a new database as a sub-page.required page_id, title
optional body
databaseId, databaseUrlGenerate a new project tracker database from a template.
Create CommentWriteAdds a comment to a page or discussion thread.required page_id, textcommentId, discussionIdHave an agent post automated status updates.
Update DatabaseWriteModifies the title or properties of a database.required database_id
optional body
databaseId, databaseUrlRename a database or add a new property column.
INFO
Why Integrate Notion with Your Agent?

Notion is a uniquely flexible workspace. By connecting it to SmythOS, you transform it from a passive documentation tool into an active, automated hub for your operations.

  • Automate Content Creation: Agents can generate new pages for meeting notes, project briefs, or reports, pre-filled with relevant data from other systems.
  • Dynamic Database Management: Keep your Notion databases in sync with other tools. Log sales leads, track project tasks, or update inventory automatically.
  • Streamline Workflows: Use Notion as a trigger or a destination. An agent can watch for a new entry in a database and kick off a workflow, or it can conclude a process by summarizing the results on a Notion page.
  • Centralize Information: Agents can gather information from emails, Slack, and other apps, then organize and store it in a structured way within your Notion workspace.

Essentially, this integration allows your SmythOS agents to use Notion as their own memory and collaboration space, reducing manual data entry and keeping your entire team updated automatically.

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

  1. In your Notion workspace, go to Settings & Members > Integrations.

  2. Click Develop your own integrations.

  3. Click + New integration. Give it a name (e.g., "SmythOS Agent") and associate it with your workspace.

  4. 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.

    Finding the Notion Integration Secret

Step 2: Store Your Secret in SmythOS Vault

Treat your Integration Secret like a password. SmythOS provides a secure Vault for this.

  1. In your SmythOS dashboard, navigate to the Vault.
  2. Create a new secret and paste your Notion Integration Secret as the value. Give it a memorable name, like notion_secret.
  3. 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.

  1. Navigate to the Notion page or database you want your agent to access.

  2. Click the Share button in the top-right corner.

  3. Click the input field and find your integration by the name you gave it (e.g., "SmythOS Agent").

  4. Click Invite. The integration now has permission to edit (or view) that page and any child pages within it.

    Sharing a Notion page with an integration

Step 4: Configure a Notion Component

  1. In your SmythOS agent graph, drag and drop any Notion component.
  2. Click the component to open its settings.
  3. In the Integration Secret field, select the secret you saved in the Vault (e.g., notion_secret).
  4. Your connection is now configured for that component!
Important
You must add the Integration Secret from the Vault to each Notion component you use in your agent. This ensures maximum security and control.

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

FieldRequiredNotes
triggerrequiredAny value can be used to trigger the component's execution.

Outputs

FieldDescription
usersAn array containing the list of user objects from the workspace.
responseFull raw response returned by the Notion API for debugging.
headersHTTP headers from the API response.
Use Case

Fetch a list of all team members at the start of a workflow to dynamically assign tasks or send notifications later on.

Create Comment — Add a Comment

Creates a new comment on a page or within an existing discussion thread.

Inputs

FieldRequiredNotes
page_idrequiredThe ID of the page where the comment should be added.
textrequiredThe rich text content of the comment.

Outputs

FieldDescription
commentIdThe unique ID of the newly created comment.
discussionIdThe ID of the discussion thread the comment belongs to.
responseRaw API payload for debugging.
headersHTTP headers from the API response.
Use Case

An agent completes a task and automatically posts a comment on the relevant project page: "Data analysis complete. Report is ready for review."

Create Page — Add a New Page

Creates a new page as a child of a specified parent page.

Inputs

FieldRequiredNotes
page_idrequiredThe ID of the parent page under which the new page will be created.
titlerequiredThe title of the new page to be created.

Outputs

FieldDescription
pageIdThe unique ID of the newly created page. Essential for future steps.
pageUrlA direct URL to the newly created Notion page.
responseRaw API payload for debugging.
headersHTTP headers from the API response.
Use Case

When a new calendar event is detected, an agent can automatically create a new meeting notes page under a "Meetings" parent page.

Fetch Page — Read a Page

Retrieves a full Page object, including its properties and content, using its unique ID.

Inputs

FieldRequiredNotes
page_idrequiredThe unique identifier of the page you want to retrieve.

Outputs

FieldDescription
pageIdThe ID of the retrieved page.
pageUrlThe direct URL to the retrieved page.
responseFull raw Page object from the Notion API.
headersHTTP headers from the API response.
Use Case

Before updating a project brief, an agent can first fetch the page to check its current content or properties.

Retrieve Database — Get Database Schema

Retrieves the structure of a database, including its properties (columns), title, and description.

Inputs

FieldRequiredNotes
database_idrequiredThe unique identifier of the database you want to retrieve.

Outputs

FieldDescription
databaseIdThe ID of the retrieved database.
responseThe full raw Database object from the Notion API, detailing its schema.
headersHTTP headers from the API response.
Use Case

An agent needs to add an entry to a tasks database. It first retrieves the database to understand its properties (like "Status", "Assignee", "Due Date") before creating a new page.

Create Database — Add a New Database

Creates a new database as a subpage within a specified parent page.

Inputs

FieldRequiredNotes
page_idrequiredThe ID of the parent page for the new database.
titlerequiredThe title of the new database.
bodyoptionalJSON object defining the properties (columns) of the new database.

Outputs

FieldDescription
databaseIdThe unique ID of the newly created database.
databaseUrlA direct URL to the new database.
responseRaw API payload for debugging.
headersHTTP headers from the API response.
Use Case

At the start of a new quarter, an agent creates a fresh "Q3 OKR Tracker" database with predefined columns for objectives, key results, and status.

Retrieve Comments — Get Unresolved Comments

Retrieves a list of all unresolved comment threads from a specific page or block.

Inputs

FieldRequiredNotes
block_idrequiredThe ID of the page or block from which to retrieve comments.

Outputs

FieldDescription
resultsAn array of unresolved comment objects.
responseRaw API payload for debugging.
headersHTTP headers from the API response.
Use Case

An agent runs daily to check a "Project Proposal" page for any new, unresolved comments and sends a summary notification to the project manager.

Query Database — Search a Database

Retrieves a list of pages from a database, with optional filters and sorting criteria.

Inputs

FieldRequiredNotes
database_idrequiredThe ID of the database to query.
bodyoptionalA JSON object containing filter and/or sorts conditions.

Outputs

FieldDescription
resultsAn array of page objects that match the query criteria.
responseRaw API payload for debugging.
headersHTTP headers from the API response.
Use Case

Query a "Tasks" database to find all pages where the "Status" property is "To Do" and the "Assignee" is a specific user.

Update Database — Modify a Database

Modifies the attributes of an existing database, such as its title, description, or properties.

Inputs

FieldRequiredNotes
database_idrequiredThe unique ID of the database you wish to update.
bodyoptionalPayload containing new database details (e.g., title, description).

Outputs

FieldDescription
databaseIdThe ID of the updated database.
databaseUrlThe URL to the updated database.
responseRaw API payload for debugging.
headersHTTP headers from the API response.
Use Case

An agent archives a project by renaming the project's database from "Active Project X" to "Archived - Project X".

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

FieldRequiredNotes
queryrequiredThe text to compare against page and database titles.

Outputs

FieldDescription
resultsAn array of page or database objects that match the title query.
responseRaw API payload for debugging.
headersHTTP headers from the API response.
Use Case

A user asks an agent to find the "Q3 Marketing Plan". The agent uses this component to search for the page and return a direct link.

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 or database_id, use outputs from previous steps. For example, use the pageId 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.