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

# Notion

> Interact with Notion databases and pages

## Overview

Notion tool allows you to search, create, and update pages and databases in Notion.

The user asks to read or update a page; the agent calls Notion and returns the outcome.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "NotionTool Flow"
        User[👤 User] --> Agent[🤖 Agent]
        Agent --> Tool[🔧 NotionTool]
        Tool --> Result[✅ Result]
        Result --> Agent
    end

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class User,Agent agent
    class Tool tool
    class Result output
```

## Installation

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install "praisonai[tools]"
```

## Environment Variables

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export NOTION_API_KEY=your_integration_token
```

Get your token from [Notion Integrations](https://www.notion.so/my-integrations).

## Quick Start

<Steps>
  <Step title="Simple Usage">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonai_tools import NotionTool

    # Initialize
    notion = NotionTool()

    # Search
    results = notion.search("meeting notes")
    print(results)
    ```
  </Step>

  <Step title="With Configuration">
    Use the same tool with an agent — see **Usage with Agent** below, or pass env vars and options from the sections above.
  </Step>
</Steps>

## Usage with Agent

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonai_tools import NotionTool

agent = Agent(
    name="NotionAssistant",
    instructions="You help manage Notion pages and databases.",
    tools=[NotionTool()]
)

response = agent.chat("Create a new page titled 'Project Plan'")
print(response)
```

## Available Methods

### search(query)

Search Notion pages and databases.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai_tools import NotionTool

notion = NotionTool()
results = notion.search("project")
```

### create\_page(parent\_id, title, content)

Create a new page.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
notion.create_page(
    parent_id="database_id",
    title="New Page",
    content="Page content here"
)
```

### get\_page(page\_id)

Get page content.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
page = notion.get_page("page_id")
```

## Common Errors

| Error                           | Cause         | Solution                    |
| ------------------------------- | ------------- | --------------------------- |
| `NOTION_API_KEY not configured` | Missing token | Set environment variable    |
| `object_not_found`              | Invalid ID    | Check page/database ID      |
| `unauthorized`                  | No access     | Share page with integration |

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Tool as Tool
    participant Svc as Notion API

    User->>Agent: Request
    Agent->>Tool: Call tool
    Tool->>Svc: Query
    Svc-->>Tool: Data
    Tool-->>Agent: Result
    Agent-->>User: Response
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Store the integration token securely">
    Read the Notion token from the environment, never hard-code it.
  </Accordion>

  <Accordion title="Share pages with the integration">
    Notion integrations only see pages explicitly shared with them — grant access first.
  </Accordion>

  <Accordion title="Handle rate limits">
    Notion throttles bursts. Retry with backoff so the agent stays responsive.
  </Accordion>
</AccordionGroup>

***

## Related Tools

<CardGroup cols={2}>
  <Card title="Confluence" icon="book" href="/docs/tools/external/confluence">
    Atlassian wiki
  </Card>

  <Card title="Google Docs" icon="book" href="/docs/tools/external/google-drive">
    Google Docs
  </Card>

  <Card title="Trello" icon="book" href="/docs/tools/external/trello">
    Task management
  </Card>
</CardGroup>