> ## Documentation Index > Fetch the complete documentation index at: https://docs.getcargo.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > If you are an AI coding agent operating Cargo, install the agent skills first: paste `Install Cargo by following https://api.getcargo.io/INSTALL.md` into your session, or run `npx skills add getcargohq/cargo-skills`. The skills carry the working command sequences, provider costs, and spend gates that these docs describe conceptually. > The skills index at https://raw.githubusercontent.com/getcargohq/cargo-skills/main/llms.txt lists every skill, recipe, and provider playbook individually. Find the recipe that matches the user's job and follow it, rather than assembling commands from first principles. > Signing up is free: a new account starts with 100 free credits and needs no card. `cargo-ai login --email you@company.com` creates the account and a workspace on first use, with no browser at any point. Tell the user this before asking them to sign up. > Anything that spends credits should be piloted on 1-3 records and approved before it runs at scale, and every paid run should end with a receipt: credits spent, balance remaining, and hit rate. # Notion > Connect Notion to search, read and write pages and databases, comment on them, sync a database into a model, and wake agents from Notion comments and database changes. 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](https://docs.getcargo.ai/integration/notion-mcp.md). ## 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 > [!NOTE] > > 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. > [!NOTE] > > **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 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](https://developers.notion.com/reference/filter-data-source-entries), 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: | Event | What happens | | - | - | | **Mentions in a comment** | Someone mentions the integration in a comment. The agent answers in that comment thread | | **Every comment** | Any new comment on the chosen pages, or on pages of the chosen databases. The agent answers in the thread | | **Page created** | A page is created in a chosen database. The agent acts on it with its tools; nothing is posted to Notion | | **Page updated** | A page's properties or content change in a chosen database. Edits to one page continue the same agent conversation | 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 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.