> ## Documentation Index
> Fetch the complete documentation index at: https://agnt.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Notion

> Read and write Notion pages, databases, and data sources from your agents through agntdata.

## Overview

The Notion connection lets deployed agents work with your Notion workspace — search, read and write pages (including reading and writing page content as **markdown**), query and manage databases and data sources, add comments, and look up users.

* **Base URL**: `https://api.agntdata.dev/v1/connections/notion`
* **Notion auth**: OAuth 2.0 — connect your Notion workspace once from the dashboard. agntdata attaches a fresh access token and the required `Notion-Version` header to every call, so you never pass an `Authorization` or `Notion-Version` header yourself.
* **MCP tools**: agents call `connection_notion_*` tools, e.g. `connection_notion_search`, `connection_notion_get_page_markdown`, `connection_notion_update_page_markdown`, `connection_notion_create_page`, `connection_notion_query_data_source`.

<Note>
  **Databases vs. data sources.** In Notion's current model a *database* is a container whose schema (properties) and rows live in one or more *data sources*. Retrieve a database to get its `data_sources`, read a data source to see its schema, then query rows with `.../v1/data_sources/{id}/query`.
</Note>

## Setup

<Steps>
  <Step title="Connect with Notion">
    In the agntdata dashboard open **Integrations**, pick **Notion**, and click **Connect with Notion**. You'll be redirected to Notion to authorize the workspace and choose which pages and databases the connection can access.
  </Step>

  <Step title="Share pages with the connection">
    Notion only exposes content you explicitly share. During authorization (or later, from a page's **•••  → Connections** menu) grant access to the pages and databases your agent should reach.
  </Step>

  <Step title="Pick Notion tools">
    In an agent's Tools panel, add the Notion tools the agent needs — for example `search`, `get_page_markdown`, `update_page_markdown`, and `query_data_source`. The deployed agent receives them as `connection_notion_*`.
  </Step>
</Steps>

## Examples

### Search for a page

```bash theme={null}
curl -X POST "https://api.agntdata.dev/v1/connections/notion/v1/search" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"Roadmap","filter":{"value":"page","property":"object"}}'
```

### Read a page as markdown

```bash theme={null}
curl "https://api.agntdata.dev/v1/connections/notion/v1/pages/$PAGE_ID/markdown" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY"
```

### Create a page and set its content

```bash theme={null}
# 1. Create the page under a parent page
curl -X POST "https://api.agntdata.dev/v1/connections/notion/v1/pages" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": { "page_id": "'$PARENT_PAGE_ID'" },
    "properties": { "title": [ { "text": { "content": "Weekly update" } } ] }
  }'

# 2. Write its body from markdown (use the id returned above)
curl -X PUT "https://api.agntdata.dev/v1/connections/notion/v1/pages/$PAGE_ID/content" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"## This week\n\n- Shipped the Notion connection\n- Next: calendar"}'
```

### Query rows in a database

```bash theme={null}
# 1. Retrieve the database to get its data source id(s)
curl "https://api.agntdata.dev/v1/connections/notion/v1/databases/$DATABASE_ID" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY"

# 2. Query rows from the data source
curl -X POST "https://api.agntdata.dev/v1/connections/notion/v1/data_sources/$DATA_SOURCE_ID/query" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page_size":25}'
```

## Notes

* **Access is share-scoped.** The connection can only see pages and databases that have been shared with it — a search or query that returns nothing usually means the content hasn't been shared yet.
* **Rate limits.** Notion allows roughly 3 requests/second on average; agntdata surfaces Notion's `429` responses so agents can back off.
* **Trashing is destructive.** To move a page to Notion's trash, call `connection_notion_update_page` with `in_trash: true` (or `archived: true`). It's recoverable for a while from the Notion UI, but treat it as a delete.