Notion

Learn how to use Notion with Composio

Overview

SLUG: NOTION

Description

Notion centralizes notes, docs, wikis, and tasks in a unified workspace, letting teams build custom workflows for collaboration and knowledge management

Authentication Details

client_id
stringRequired
client_secret
stringRequired
oauth_redirect_uri
stringDefaults to https://backend.composio.dev/api/v1/auth-apps/add
scopes
string
bearer_token
string
generic_api_key
stringRequired

Connecting to Notion

Create an auth config

Use the dashboard to create an auth config for the Notion toolkit. This allows you to connect multiple Notion accounts to Composio for agents to use.

1

Select App

Navigate to Notion.

2

Configure Auth Config Settings

Select among the supported auth schemes of and configure them here.

3

Create and Get auth config ID

Click “Create Notion Auth Config”. After creation, copy the displayed ID starting with ac_. This is your auth config ID. This is not a sensitive ID — you can save it in environment variables or a database. This ID will be used to create connections to the toolkit for a given user.

Connect Your Account

Using OAuth2

1from composio import Composio
2
3# Replace these with your actual values
4notion_auth_config_id = "ac_YOUR_NOTION_CONFIG_ID" # Auth config ID created above
5user_id = "0000-0000-0000" # UUID from database/application
6
7composio = Composio()
8
9
10def authenticate_toolkit(user_id: str, auth_config_id: str):
11 connection_request = composio.connected_accounts.initiate(
12 user_id=user_id,
13 auth_config_id=auth_config_id,
14 )
15
16 print(
17 f"Visit this URL to authenticate Notion: {connection_request.redirect_url}"
18 )
19
20 # This will wait for the auth flow to be completed
21 connection_request.wait_for_connection(timeout=15)
22 return connection_request.id
23
24
25connection_id = authenticate_toolkit(user_id, notion_auth_config_id)
26
27# You can also verify the connection status using:
28connected_account = composio.connected_accounts.get(connection_id)
29print(f"Connected account: {connected_account}")

Using API Key

1from composio import Composio
2
3# Replace these with your actual values
4notion_auth_config_id = "ac_YOUR_NOTION_CONFIG_ID" # Auth config ID created above
5user_id = "0000-0000-0000" # UUID from database/app
6
7composio = Composio()
8
9def authenticate_toolkit(user_id: str, auth_config_id: str):
10 # Replace this with a method to retrieve an API key from the user.
11 # Or supply your own.
12 user_api_key = input("[!] Enter API key")
13
14 connection_request = composio.connected_accounts.initiate(
15 user_id=user_id,
16 auth_config_id=auth_config_id,
17 config={"auth_scheme": "API_KEY", "val": {"generic_api_key": user_api_key}}
18 )
19
20 # API Key authentication is immediate - no redirect needed
21 print(f"Successfully connected Notion for user {user_id}")
22 print(f"Connection status: {connection_request.status}")
23
24 return connection_request.id
25
26
27connection_id = authenticate_toolkit(user_id, notion_auth_config_id)
28
29# You can verify the connection using:
30connected_account = composio.connected_accounts.get(connection_id)
31print(f"Connected account: {connected_account}")

Tools

Executing tools

To prototype you can execute some tools to see the responses and working on the Notion toolkit’s playground

Python
1from composio import Composio
2from openai import OpenAI
3import json
4
5openai = OpenAI()
6composio = Composio()
7
8# User ID must be a valid UUID format
9user_id = "0000-0000-0000" # Replace with actual user UUID from your database
10
11tools = composio.tools.get(user_id=user_id, toolkits=["NOTION"])
12
13print("[!] Tools:")
14print(json.dumps(tools))
15
16def invoke_llm(task = "What can you do?"):
17 completion = openai.chat.completions.create(
18 model="gpt-4o",
19 messages=[
20 {
21 "role": "user",
22 "content": task, # Your task here!
23 },
24 ],
25 tools=tools,
26 )
27
28 # Handle Result from tool call
29 result = composio.provider.handle_tool_calls(user_id=user_id, response=completion)
30 print(f"[!] Completion: {completion}")
31 print(f"[!] Tool call result: {result}")
32
33invoke_llm()

Tool List

Tool Name: Add multiple content blocks (bulk, user-friendly)

Description

Bulk-add content blocks to notion. critical: notion api enforces 2000 char limit per text.content field. features: - accepts simplified format: {'content': 'text', 'block property': 'type'} - or full notion block format with 'type' and properties - auto-splits text >2000 chars into multiple blocks - auto-parses markdown: **bold**, *italic*, ~~strike~~, `inline code`, [links](url) - maximum 100 blocks per api call required 'content' for: paragraph, heading 1-3, callout, to do, toggle, quote, list items. for code blocks use full format: {'type': 'code', 'code': {'rich text': [...], 'language': 'python'}} common errors: - "content.length should be ≤ 2000": auto-split failed, manually split content - "content is required": missing content for text blocks - each item must be wrapped in 'content block' field

Action Parameters

after
string
content_blocks
arrayRequired
parent_block_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Add single content block to Notion page (Deprecated)

Description

Deprecated: use 'add multiple page content' for better performance. adds a single content block to a notion page/block. critical: notion api enforces a hard limit of 2000 characters per text.content field. content exceeding 2000 chars is automatically split into multiple sequential blocks. required 'content' field for text blocks: paragraph, heading 1-3, callout, to do, toggle, quote, list items. parent blocks must be: page, toggle, to-do, bulleted/numbered list item, callout, or quote. common errors: - "content.length should be ≤ 2000": text exceeds api limit (should be auto-handled) - "content is required for paragraph blocks": missing 'content' field for text blocks - "object not found": invalid parent block id or no integration access for bulk operations, use 'add multiple page content' instead.

Action Parameters

after
string
content_block
objectRequired
parent_block_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Append raw Notion blocks (advanced API)

Description

Appends raw notion api blocks to parent. critical: text content limited to 2000 chars per text.content field. use for: advanced blocks (tables, databases), pre-built block objects, complex nested structures. requires exact notion block schema - each block must have 'object':'block' and 'type'. text blocks must use rich text arrays: {'rich text': [{'type': 'text', 'text': {'content': 'text'}}]} common errors: - "content.length should be ≤ 2000": text exceeds api limit, split into multiple blocks - "validation error": using 'text' instead of 'rich text' for headings/paragraphs - "object not found": invalid block id or no integration access - missing 'object': 'block' or 'type' fields for simple content, use 'add multiple page content' instead - it handles formatting automatically.

Action Parameters

after
string
block_id
stringRequired
children
arrayRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Archive Notion Page

Description

Archives (moves to trash) or unarchives (restores from trash) a specified notion page.

Action Parameters

archive
booleanDefaults to True
page_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create comment

Description

Adds a comment to a notion page (via `parent page id`) or to an existing discussion thread (via `discussion id`); cannot create new discussion threads on specific blocks (inline comments).

Action Parameters

comment
objectRequired
discussion_id
string
parent_page_id
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create Notion Database

Description

Creates a new notion database as a subpage under a specified parent page with a defined properties schema. important notes: - the parent page must be shared with your integration, otherwise you'll get a 404 error - if you encounter conflict errors (409), retry the request as notion may experience temporary save conflicts - for relation properties, you must provide the database id of the related database - parent id must be a valid uuid format (with or without hyphens), not a template variable use this action exclusively for creating new databases.

Action Parameters

parent_id
stringRequired
properties
arrayRequired
title
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create Notion page

Description

Creates a new empty page in a notion workspace under a specified parent page or database. prerequisites: - parent page/database must exist and be accessible in your notion workspace - use search pages or list databases first to obtain valid parent ids limitations: - cannot create root-level pages (must have a parent) - may encounter conflicts if creating pages too quickly - title-based parent search is less reliable than using uuids

Action Parameters

cover
string
icon
string
parent_id
stringRequired
title
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Delete a block

Description

Archives a notion block, page, or database using its id, which sets its 'archived' property to true (like moving to "trash" in the ui) and allows it to be restored later.

Action Parameters

block_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Duplicate page

Description

Duplicates a notion page, including all its content, properties, and nested blocks, under a specified parent page or workspace.

Action Parameters

page_id
stringRequired
parent_id
stringRequired
title
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Fetch Notion Block Children

Description

Retrieves a paginated list of direct, first-level child block objects along with contents for a given parent notion block or page id; use block ids from the response for subsequent calls to access deeply nested content.

Action Parameters

block_id
stringRequired
page_size
integer
start_cursor
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Fetch Notion block metadata

Description

Fetches metadata for a notion block (including pages, which are special blocks) using its uuid. returns block type, properties, and basic info but not child content. prerequisites: 1) block/page must be shared with your integration, 2) use valid block id from api responses (not urls). for child blocks, use fetch block contents instead. common 404 errors mean the block isn't accessible to your integration.

Action Parameters

block_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Fetch comments

Description

Fetches unresolved comments for a specified notion block or page id.

Action Parameters

block_id
stringRequired
page_size
integerDefaults to 100
start_cursor
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Fetch Notion Data

Description

Fetches notion items (pages and/or databases) from the notion workspace, use this to get minimal data about the items in the workspace with a query or list all items in the workspace with minimal data

Action Parameters

get_all
boolean
get_databases
boolean
get_pages
boolean
page_size
integerDefaults to 100
query
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Fetch Database

Description

Fetches a notion database's structural metadata (properties, title, etc.) via its `database id`, not the data entries; `database id` must reference an existing database.

Action Parameters

database_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Fetch database row

Description

Retrieves a notion database row's properties and metadata; use fetch block contents for page content blocks.

Action Parameters

page_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get About Me

Description

Retrieves the user object for the bot associated with the current notion integration token, typically to obtain the bot's user id for other api operations.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get about user

Description

Retrieves detailed information about a specific notion user, such as their name, avatar, and email, based on their unique user id.

Action Parameters

user_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get page property

Description

Call this to get a specific property from a notion page when you have a valid `page id` and `property id`; handles pagination for properties returning multiple items.

Action Parameters

page_id
stringRequired
page_size
integer
property_id
stringRequired
start_cursor
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Insert row database

Description

Creates a new page (row) in a specified notion database. prerequisites: - the database must be explicitly shared with your notion integration - property names and types must match the database schema exactly - select/multi-select options must already exist in the database common errors: - 404 "could not find database": database is not shared with your integration - 400 "status is not a property": using 'status' type incorrectly (use 'select' instead) - validation error on properties: properties must be provided as a list, not a dictionary

Action Parameters

child_blocks
array
cover
string
database_id
stringRequired
icon
string
properties
array

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List users

Description

Retrieves a paginated list of users (excluding guests) from the notion workspace; the number of users returned per page may be less than the requested `page size`.

Action Parameters

page_size
integerDefaults to 30
start_cursor
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Query database

Description

Queries a notion database to retrieve pages (rows). in notion, databases are collections where each row is a page and columns are properties. returns paginated results with metadata. important requirements: - the database must be shared with your integration - property names in sorts must match existing database properties exactly (case-sensitive) - the start cursor must be a valid uuid from a previous response's next cursor field - database ids must be valid 32-character uuids (with or without hyphens) use this action to: - retrieve all or filtered database entries - sort results by one or more properties - paginate through large result sets - get database content for processing or display

Action Parameters

database_id
stringRequired
page_size
integerDefaults to 100
sorts
array
start_cursor
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Retrieve Comment

Description

Tool to retrieve a specific comment by its id. use when you have a comment id and need to fetch its details.

Action Parameters

comment_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Retrieve Database Property

Description

Tool to retrieve a specific property object of a notion database. use when you need to get details about a single database column/property.

Action Parameters

database_id
stringRequired
property_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Search Notion page

Description

Searches notion pages and databases by title; an empty query lists all accessible items, useful for discovering ids or as a fallback when a specific query yields no results.

Action Parameters

direction
string
filter_property
stringDefaults to object
filter_value
stringDefaults to page
page_size
integerDefaults to 2
query
string
start_cursor
string
timestamp
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Update block

Description

Updates existing notion block's text content. ⚠️ critical: content limited to 2000 chars. cannot change block type or archive blocks. content exceeding 2000 chars will fail with validation error. for longer content, split across multiple blocks using add multiple page content.

Action Parameters

additional_properties
object
block_id
stringRequired
block_type
stringRequired
content
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Update Page

Description

Update page properties, icon, cover, or archive status. requires at least one update parameter. common errors: - "invalid property identifier": property name doesn't exist - use exact names from your database - "should be defined": property value missing wrapper - always wrap: {'field': {'type': value}} - "input should be a valid dictionary": properties must be dict, not list property formats by type: - title/rich text: {'text': {'content': 'value'}} - select/status: {'name': 'option'} - url: plain string needs {'url': 'string'} wrapper - number: plain number needs {'number': value} wrapper

Action Parameters

archived
boolean
cover
object
icon
object
page_id
stringRequired
properties
object

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Update row database

Description

Updates a notion database row (page) by its uuid. common issues: (1) use uuid from page url, not the full url, (2) ensure page is shared with integration, (3) match property names exactly as in database, (4) use 'status' type for status properties, not 'select', (5) retry on 409 conflict errors (concurrent updates). supports updating properties, icon, cover, or archiving the row.

Action Parameters

cover
string
delete_row
boolean
icon
string
properties
array
row_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Update database schema

Description

Updates an existing notion database's schema including title, description, and/or properties (columns). important notes: - at least one update (title, description, or properties) must be provided - the database must be shared with your integration - property names are case-sensitive and must match exactly - when changing a property to 'relation' type, you must provide the database id of the target database - removing properties will permanently delete that column and its data - use notion fetch data first to get the exact property names and database structure common errors: - 'database id' missing: ensure you're passing the database id parameter (not page id) - 'data source id' undefined: when changing to relation type, database id is required in propertyschemaupdate - property name mismatch: names must match exactly including case and special characters

Action Parameters

database_id
stringRequired
description
string
properties
array
title
string

Action Response

data
objectRequired
error
string
successful
booleanRequired