Skip to main content
The Notion integration acts in your Notion workspace through Notion’s API. Plays, tools and agents can find pages and databases, read a page as markdown, create and update database pages, add content, and comment. A database can sync into a Cargo model, and an agent can answer comments in Notion and act on pages as they are created or edited. To let agents call Notion’s own MCP tools instead, see Notion MCP.

​
How to set up Notion

​
Authentication

Notion uses OAuth authorization:
  1. Create a Notion connector in Cargo
  2. Click Authorize Notion
  3. Sign in to Notion in the popup, choose the workspace, and pick the pages the integration can access
  4. Cargo stores the grant and refreshes it automatically
Notion only shows the integration the pages you shared with it, and the pages under them. To reach more pages later, open a page in Notion, click •••, then Connections, and add Cargo.
Code slugs: integration slug notion. Actions: search, getPage, queryDataSource, createPage, updatePage, appendContent, createComment, listComments. Extractor: fetchDataSource.

​
After connecting

Once the connector is set up, choose Notion from the node catalog within a Play, Tool, or Agent.

​
Notion actions

Every action that takes a page or a database accepts its ID or its Notion URL. Search the pages and databases shared with the integration by title. Optional fields:
  • Query: text to search titles for. Leave empty to list what the integration can see
  • Object: only pages, or only databases
  • Limit: up to 100 results (default 20)
Returns: the ID, kind, title and URL of each result.

​
Get page

Read a page’s properties as plain values and its content as markdown. Required fields:
  • Page
Optional fields:
  • With content: set it to false to skip the page body
Returns: id, url, title, dataSourceId, parentPageId, createdTime, lastEditedTime, inTrash, properties, content (markdown) and isContentTruncated.

​
Query database

List the pages of a database, optionally filtered and sorted. Required fields:
  • Database
Optional fields:
  • Filter: a Notion filter object, for example { "property": "Status", "status": { "equals": "Done" } }
  • Sorts: Notion sort objects, for example [{ "property": "Due", "direction": "ascending" }]
  • Limit: up to 1,000 pages (default 100)
Returns: each page with its properties as plain values.

​
Create page

Create a page in a database with its properties, or under a parent page. Required fields: one of
  • Database
  • Parent page
Optional fields:
  • Title
  • Properties: database properties to set, by name. Only for a page in a database
  • Content: the page body, as markdown
Values are plain: text, a number, a date in ISO 8601, an option name, or a comma-separated list of names or IDs. An empty value clears the property. To write a value as Notion shapes it, pass the Notion property object.

​
Update page

Set a page’s title and database properties, or move it to the trash and back. Required fields:
  • Page
Optional fields:
  • Database: only used to pick properties in the form. Read from the page when empty
  • Title
  • Properties
  • In trash

​
Append content

Add markdown at the end of a page. Required fields:
  • Page
  • Content

​
Create comment

Comment on a page, or reply in an existing discussion thread. Required fields:
  • Text: the comment as markdown. Notion only renders inline formatting and mentions in comments
  • One of Page or Discussion ID

​
List comments

List the open comments on a page or block, oldest first. Required fields:
  • Page or block
Optional fields:
  • Discussion ID: only the comments of that thread
  • Limit: up to 500 comments (default 100)

​
Sync a database into a model

The Fetch database extractor syncs a Notion database into a Cargo model, one record per page.
  • Each property becomes a column, named from the property in snake case. The id, url, created_time and last_edited_time columns are always present
  • Each run after the first only reads the pages edited since the last one
  • Pages moved to the trash are not removed from the model

​
Wake agents from Notion

An agent can be triggered by the Notion connector. Pick the events that wake it: Leave Pages and Databases empty to watch everything the integration can see. A comment thread or a page is one agent conversation, so a follow-up comment continues it. The agent never answers its own comments or wakes from its own edits. Notion delivers events within a minute or two, and groups rapid edits to a page into one.

​
Best practices

  • Share only the pages and databases your plays and agents need with the integration
  • Give the agent the Notion actions it needs, such as Get page and Update page, so it can act on what woke it
  • Use Every comment on a few chosen pages rather than across the workspace, so the agent is not woken by every discussion