Notion

What you can do

Connect this agent connector to let your agent:

• Read pages and databases — retrieve page content and query database entries
• Create pages — add new pages and database rows with full content
• Update content — edit existing page blocks, properties, and database fields
• Search — find pages and databases across the user’s Notion workspace

Authentication

This connector uses OAuth 2.0. Scalekit acts as the OAuth client: it redirects your user to Notion, obtains an access token, and automatically refreshes it before it expires. Your agent code never handles tokens directly — you only pass a connectionName and a user identifier.

You supply your Notion Connected App credentials (Client ID + Secret) once per environment in the Scalekit dashboard.

Set up the connector

Register your Scalekit environment with the Notion connector so Scalekit handles the authentication flow and token lifecycle for you. The connection name you create will be used to identify and invoke the connection programmatically. Then complete the configuration in your application as follows:

1. Set up auth redirects

   • In Scalekit dashboard, go to Agent Auth → Create Connection. Find Notion and click Create. Copy the redirect URI. It looks like https://<SCALEKIT_ENVIRONMENT_URL>/sso/v1/oauth/<CONNECTION_ID>/callback.

     

   • Go to Notion Integrations and click New integration.

   • Fill in the integration name and select your workspace. In the OAuth Domain & URIs section, paste the redirect URI from Scalekit and click Submit.

     

2. Get client credentials

   • In your Notion integration settings, go to the Secrets tab.

   • Copy the OAuth client ID and OAuth client secret.

3. Add credentials in Scalekit

   • In Scalekit dashboard, go to Agent Auth → Connections and open the connection you created.

   • Enter your credentials:

     • Client ID (OAuth client ID from above)
     • Client Secret (OAuth client secret from above)
     • Permissions (capabilities — see Notion capabilities reference)

     

   • Click Save.

Code examples

Connect a user’s Notion account and make API calls on their behalf — Scalekit handles OAuth and token management automatically.

Proxy API Calls

Node.js

import { ScalekitClient } from '@scalekit-sdk/node';
import 'dotenv/config';

const connectionName = 'notion'; // get your connection name from connection configurations
const identifier = 'user_123';  // your unique user identifier

// Get your credentials from app.scalekit.com → Developers → Settings → API Credentials
const scalekit = new ScalekitClient(
  process.env.SCALEKIT_ENV_URL,
  process.env.SCALEKIT_CLIENT_ID,
  process.env.SCALEKIT_CLIENT_SECRET
);
const actions = scalekit.actions;

// Authenticate the user
const { link } = await actions.getAuthorizationLink({
  connectionName,
  identifier,
});
console.log('🔗 Authorize Notion:', link);
process.stdout.write('Press Enter after authorizing...');
await new Promise(r => process.stdin.once('data', r));

// Make a request via Scalekit proxy
const result = await actions.request({
  connectionName,
  identifier,
  path: '/v1/users/me',
  method: 'GET',
});
console.log(result);

Python

import scalekit.client, os
from dotenv import load_dotenv
load_dotenv()

connection_name = "notion"  # get your connection name from connection configurations
identifier = "user_123"     # your unique user identifier

# Get your credentials from app.scalekit.com → Developers → Settings → API Credentials
scalekit_client = scalekit.client.ScalekitClient(
    client_id=os.getenv("SCALEKIT_CLIENT_ID"),
    client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
    env_url=os.getenv("SCALEKIT_ENV_URL"),
)
actions = scalekit_client.actions

# Authenticate the user
link_response = actions.get_authorization_link(
    connection_name=connection_name,
    identifier=identifier
)
# present this link to your user for authorization, or click it yourself for testing
print("🔗 Authorize Notion:", link_response.link)
input("Press Enter after authorizing...")

# Make a request via Scalekit proxy
result = actions.request(
    connection_name=connection_name,
    identifier=identifier,
    path="/v1/users/me",
    method="GET"
)
print(result)

Tool list

notion_block_delete Delete (archive) a Notion block by its ID. This also deletes all child blocks within it. 1 param ▾

Delete (archive) a Notion block by its ID. This also deletes all child blocks within it.

Name Type Required Description

block_id string required The ID of the block to delete

notion_block_update Update the text content of an existing Notion block. Supports paragraph, heading, list item, quote, callout, and code blocks. 4 params ▾

Update the text content of an existing Notion block. Supports paragraph, heading, list item, quote, callout, and code blocks.

Name Type Required Description

block_id string required The ID of the block to update

text string required New text content for the block

type string required The block type (must match the existing block type)

language string optional Programming language for code blocks

notion_comment_create Create a comment in Notion. Provide a comment object with rich_text content and either a parent object (with page_id) for a page-level comment or a discussion_id to reply in an existing thread. 6 params ▾

Create a comment in Notion. Provide a comment object with rich_text content and either a parent object (with page_id) for a page-level comment or a discussion_id to reply in an existing thread.

Name Type Required Description

comment object required Comment object containing a rich_text array. Example: {"rich_text":[{"type":"text","text":{"content":"Hello"}}]}

discussion_id string optional Existing discussion thread ID to reply to.

notion_version string optional Optional override for the Notion-Version header (e.g., 2022-06-28).

parent object optional Parent object for a new top-level comment. Shape: {"page_id":"<uuid>"}.

schema_version string optional Internal override for schema version.

tool_version string optional Internal override for tool implementation version.

notion_comment_retrieve Retrieve a single Notion comment by its `comment_id`. LLM tip: you typically obtain `comment_id` from the response of creating a comment or by first listing comments for a page/block and selecting the desired item’s `id`. 4 params ▾

Retrieve a single Notion comment by its `comment_id`. LLM tip: you typically obtain `comment_id` from the response of creating a comment or by first listing comments for a page/block and selecting the desired item’s `id`.

Name Type Required Description

comment_id string required The identifier of the comment to retrieve (hyphenated UUID). Obtain it from Create-Comment responses or from a prior List-Comments call.

notion_version string optional Optional Notion-Version header override (e.g., 2022-06-28).

schema_version string optional Internal override for schema version.

tool_version string optional Internal override for tool implementation version.

notion_comments_fetch Fetch comments for a given Notion block. Provide a `block_id` (the target page/block ID, hyphenated UUID). Supports pagination via `start_cursor` and `page_size` (1–100). LLM tip: extract `block_id` from a Notion URL’s trailing 32-char id, then insert hyphens (8-4-4-4-12). 6 params ▾

Fetch comments for a given Notion block. Provide a `block_id` (the target page/block ID, hyphenated UUID). Supports pagination via `start_cursor` and `page_size` (1–100). LLM tip: extract `block_id` from a Notion URL’s trailing 32-char id, then insert hyphens (8-4-4-4-12).

Name Type Required Description

block_id string required Target Notion block (or page) ID to fetch comments for. Use a hyphenated UUID.

notion_version string optional Optional Notion-Version header override (e.g., 2022-06-28).

page_size integer optional Maximum number of comments to return (1–100).

schema_version string optional Internal override for schema version.

start_cursor string optional Cursor to fetch the next page of results.

tool_version string optional Internal override for tool implementation version.

notion_data_fetch Fetch data from Notion using the workspace search API (/search). Supports pagination via start_cursor. 5 params ▾

Fetch data from Notion using the workspace search API (/search). Supports pagination via start_cursor.

Name Type Required Description

page_size integer optional Max number of results to return (1–100)

query string optional Text query used by /search

schema_version string optional Optional schema version to use for tool execution

start_cursor string optional Cursor for pagination; pass the previous response's next_cursor

tool_version string optional Optional tool version to use for execution

notion_data_source_fetch Retrieve a Notion database's schema, title, and properties using the Notion 2025-09-03 API. Unlike notion_database_fetch, this returns a data_sources array — each entry contains a data_source_id required by notion_data_source_query and notion_data_source_insert_row. Use this as the first step when working with merged, synced, or multi-source databases. For standard single-source databases, notion_database_fetch is sufficient. LLM guidance: extract data_sources[0].id (or the relevant source) from the response and pass it to the query or insert tools. 1 param ▾

Retrieve a Notion database's schema, title, and properties using the Notion 2025-09-03 API. Unlike notion_database_fetch, this returns a data_sources array — each entry contains a data_source_id required by notion_data_source_query and notion_data_source_insert_row. Use this as the first step when working with merged, synced, or multi-source databases. For standard single-source databases, notion_database_fetch is sufficient. LLM guidance: extract data_sources[0].id (or the relevant source) from the response and pass it to the query or insert tools.

Name Type Required Description

database_id string required The target database ID in UUID format with hyphens.

notion_data_source_insert_row Create a new row (page) in a Notion data source using the 2025-09-03 API. Required for merged, synced, or multi-source databases — these require parent.data_source_id instead of parent.database_id which the older notion_database_insert_row uses. Provide the data_source_id from notion_data_source_fetch (data_sources[].id) and a properties object mapping column names to Notion property value shapes. Optionally attach child blocks (page content), an icon, or a cover image. LLM guidance: step 1 — call notion_data_source_fetch to get the data_source_id; step 2 — build the properties object using exact column names from the schema (use 'title' key for title-type fields); step 3 — call this tool. 5 params ▾

Create a new row (page) in a Notion data source using the 2025-09-03 API. Required for merged, synced, or multi-source databases — these require parent.data_source_id instead of parent.database_id which the older notion_database_insert_row uses. Provide the data_source_id from notion_data_source_fetch (data_sources[].id) and a properties object mapping column names to Notion property value shapes. Optionally attach child blocks (page content), an icon, or a cover image. LLM guidance: step 1 — call notion_data_source_fetch to get the data_source_id; step 2 — build the properties object using exact column names from the schema (use 'title' key for title-type fields); step 3 — call this tool.

Name Type Required Description

data_source_id string required The ID of the data source to insert a row into. Retrieve from notion_database_fetch response under data_sources[].id.

properties object required Object mapping column names (or property ids) to property values. Example: {"title": {"title": [{"text": {"content": "Task A"}}]}, "Status": {"select": {"name": "Todo"}}}

child_blocks array optional Optional array of Notion blocks to append as page content.

cover object optional Optional page cover object. Example: {"type":"external","external":{"url":"https://example.com/cover.jpg"}}

icon object optional Optional page icon object. Example: {"type":"emoji","emoji":"📝"}

notion_data_source_query Query rows (pages) from a Notion data source using the 2025-09-03 API. Required for merged, synced, or multi-source databases — these cannot be queried via notion_database_query as that tool uses the older /databases/{id}/query endpoint which does not support multiple data sources. Provide the data_source_id obtained from notion_data_source_fetch (data_sources[].id). Supports filtering by property values, sorting, and cursor-based pagination. LLM guidance: step 1 — call notion_data_source_fetch with the database_id to retrieve the data_source_id; step 2 — pass that id here along with an optional filter, sorts, and page_size. 5 params ▾

Query rows (pages) from a Notion data source using the 2025-09-03 API. Required for merged, synced, or multi-source databases — these cannot be queried via notion_database_query as that tool uses the older /databases/{id}/query endpoint which does not support multiple data sources. Provide the data_source_id obtained from notion_data_source_fetch (data_sources[].id). Supports filtering by property values, sorting, and cursor-based pagination. LLM guidance: step 1 — call notion_data_source_fetch with the database_id to retrieve the data_source_id; step 2 — pass that id here along with an optional filter, sorts, and page_size.

Name Type Required Description

data_source_id string required The ID of the data source to query. Retrieve from notion_database_fetch response under data_sources[].id.

filter object optional Notion filter object to narrow results. Example: {"property": "Status", "select": {"equals": "Done"}}. Supports compound filters with 'and'/'or' arrays.

page_size integer optional Maximum number of rows to return (1-100).

sorts array optional Order the results. Each item must include either property or timestamp, plus direction.

start_cursor string optional Cursor to fetch the next page of results.

notion_database_create Create a new database in Notion under a parent page. Provide a parent object with page_id, a database title (rich_text array), and a properties object that defines the database schema (columns). 5 params ▾

Create a new database in Notion under a parent page. Provide a parent object with page_id, a database title (rich_text array), and a properties object that defines the database schema (columns).

Name Type Required Description

parent object required Parent object specifying the page under which the database is created. Example: {"page_id": "2561ab6c-418b-8072-beec-c4779fa811cf"}

properties object required Database schema object defining properties (columns). Example: {"Name": {"title": {}}, "Status": {"select": {"options": [{"name": "Todo"}, {"name": "Doing"}, {"name": "Done"}]}}}

title array required Database title as a Notion rich_text array.

schema_version string optional Internal override for schema version.

tool_version string optional Internal override for tool implementation version.

notion_database_fetch Retrieve a Notion database's full definition, including title, properties, and schema. Required: database_id (hyphenated UUID). LLM tip: Extract the last 32 characters from a Notion database URL, then insert hyphens (8-4-4-4-12). 1 param ▾

Retrieve a Notion database's full definition, including title, properties, and schema. Required: database_id (hyphenated UUID). LLM tip: Extract the last 32 characters from a Notion database URL, then insert hyphens (8-4-4-4-12).

Name Type Required Description

database_id string required The target database ID in UUID format with hyphens.

notion_database_insert_row Insert a new row (page) into a Notion database. Required: `database_id` (hyphenated UUID) and `properties` (object mapping database column names to Notion **property values**). Optional: `child_blocks` (content blocks), `icon` (page icon object), and `cover` (page cover object). LLM guidance: - `properties` must use **property values** (not schema). Example: { "title": { "title": [ { "text": { "content": "Task A" } } ] }, "Status": { "select": { "name": "Todo" } }, "Due": { "date": { "start": "2025-09-01" } } } - Use the **exact property key** as defined in the database (case‑sensitive), or the property **id`. - `icon` example (emoji): {"type":"emoji","emoji":"📝"} - `cover` example (external): {"type":"external","external":{"url":"https://example.com/image.jpg"}} - Runtime note: the executor/host should synthesize `parent = {"database_id": database_id}` before sending to Notion. 8 params ▾

Insert a new row (page) into a Notion database. Required: `database_id` (hyphenated UUID) and `properties` (object mapping database column names to Notion **property values**). Optional: `child_blocks` (content blocks), `icon` (page icon object), and `cover` (page cover object). LLM guidance: - `properties` must use **property values** (not schema). Example: { "title": { "title": [ { "text": { "content": "Task A" } } ] }, "Status": { "select": { "name": "Todo" } }, "Due": { "date": { "start": "2025-09-01" } } } - Use the **exact property key** as defined in the database (case‑sensitive), or the property **id`. - `icon` example (emoji): {"type":"emoji","emoji":"📝"} - `cover` example (external): {"type":"external","external":{"url":"https://example.com/image.jpg"}} - Runtime note: the executor/host should synthesize `parent = {"database_id": database_id}` before sending to Notion.

Name Type Required Description

database_id string required Target database ID (hyphenated UUID).

properties object required Object mapping **column names (or property ids)** to **property values**. ️ **CRITICAL: Property Identification Rules:** - For title fields: ALWAYS use 'title' as the property key (not 'Name' or display names) - For other properties: Use exact property names from database schema (case-sensitive) - DO NOT use URL-encoded property IDs with special characters **Recommended Workflow:** 1. Call fetch_database first to see exact property names 2. Use 'title' for title-type properties 3. Match other property names exactly as shown in schema Example: { "title": { "title": [ { "text": { "content": "Task A" } } ] }, "Status": { "select": { "name": "Todo" } }, "Due": { "date": { "start": "2025-09-01" } } }

_parent object optional Computed by host: `{ "database_id": "<database_id>" }`. Do not supply manually.

child_blocks array optional Optional array of Notion blocks to append as page content (paragraph, heading, to_do, etc.).

cover object optional Optional page cover object. Example external: {"type":"external","external":{"url":"https://example.com/cover.jpg"}}.

icon object optional Optional page icon object. Examples: {"type":"emoji","emoji":"📝"} or {"type":"external","external":{"url":"https://..."}}.

schema_version string optional Optional schema version override.

tool_version string optional Optional tool version override.

notion_database_property_retrieve Query a Notion database and return only specific properties by supplying one or more property IDs. Use when you need page rows but want to limit the returned properties to reduce payload. Provide the database_id and an array of filter_properties (each item is a property id like "title") 4 params ▾

Query a Notion database and return only specific properties by supplying one or more property IDs. Use when you need page rows but want to limit the returned properties to reduce payload. Provide the database_id and an array of filter_properties (each item is a property id like "title")

Name Type Required Description

database_id string required Target database ID (hyphenated UUID).

property_id string optional property ID to filter results by a specific property. get the property id by querying database.

schema_version string optional Optional schema version override.

tool_version string optional Optional tool version override.

notion_database_query Query a Notion database for rows (pages) using the 2022-06-28 API. Works for standard single-source databases. NOTE: If you encounter an 'Invalid request URL' error or are working with a merged, synced, or multi-source database, use the newer data source tools instead — call notion_data_source_fetch with the database_id to get the data_source_id, then call notion_data_source_query with that id. Provide database_id (hyphenated UUID). Optional: filter (Notion filter object), page_size (default 10), start_cursor for pagination, and sorts. LLM guidance: extract the last 32 characters from a Notion database URL and insert hyphens (8-4-4-4-12) to form database_id. Sort rules: each sort item MUST include either property OR timestamp (last_edited_time/created_time), not both. 7 params ▾

Query a Notion database for rows (pages) using the 2022-06-28 API. Works for standard single-source databases. NOTE: If you encounter an 'Invalid request URL' error or are working with a merged, synced, or multi-source database, use the newer data source tools instead — call notion_data_source_fetch with the database_id to get the data_source_id, then call notion_data_source_query with that id. Provide database_id (hyphenated UUID). Optional: filter (Notion filter object), page_size (default 10), start_cursor for pagination, and sorts. LLM guidance: extract the last 32 characters from a Notion database URL and insert hyphens (8-4-4-4-12) to form database_id. Sort rules: each sort item MUST include either property OR timestamp (last_edited_time/created_time), not both.

Name Type Required Description

database_id string required Target database ID (hyphenated UUID).

filter object optional Notion filter object to narrow results. Example: {"property": "Status", "select": {"equals": "Done"}}. Supports compound filters with 'and'/'or' arrays.

page_size integer optional Maximum number of rows to return (1–100).

schema_version string optional Optional schema version override.

sorts array optional Order the results. Each item must include either property or timestamp, plus direction.

start_cursor string optional Cursor to fetch the next page of results.

tool_version string optional Optional tool version override.

notion_database_update Update a Notion database's title, description, or property schema. 4 params ▾

Update a Notion database's title, description, or property schema.

Name Type Required Description

database_id string required The ID of the database to update

description string optional New description for the database

properties object optional Property schema updates (add, rename, or reconfigure columns)

title string optional New title for the database

notion_page_content_append Append blocks to a Notion page or block. IMPORTANT: This tool uses a simplified block format — do NOT pass raw Notion API block objects. Each block takes a 'type' and a 'text' string (plain text only). The tool internally converts these into the Notion API format. Supported types: paragraph, heading_1, heading_2, heading_3, bulleted_list_item, numbered_list_item, code, quote, callout, divider. For code blocks, add a 'language' field. Dividers require only the 'type' field. Example: [{"type": "heading_1", "text": "My Title"}, {"type": "paragraph", "text": "Some content"}, {"type": "code", "text": "print('hi')", "language": "python"}, {"type": "divider"}]. 2 params ▾

Append blocks to a Notion page or block. IMPORTANT: This tool uses a simplified block format — do NOT pass raw Notion API block objects. Each block takes a 'type' and a 'text' string (plain text only). The tool internally converts these into the Notion API format. Supported types: paragraph, heading_1, heading_2, heading_3, bulleted_list_item, numbered_list_item, code, quote, callout, divider. For code blocks, add a 'language' field. Dividers require only the 'type' field. Example: [{"type": "heading_1", "text": "My Title"}, {"type": "paragraph", "text": "Some content"}, {"type": "code", "text": "print('hi')", "language": "python"}, {"type": "divider"}].

Name Type Required Description

block_id string required The ID of the page or block to append content to

blocks array required Array of blocks to append. Each block uses a simplified format with 'type' and 'text' fields — NOT the raw Notion API format. Do not pass Notion block objects with rich_text arrays.

notion_page_content_get Retrieve the content (blocks) of a Notion page or block. Returns all child blocks with their type and text content. 3 params ▾

Retrieve the content (blocks) of a Notion page or block. Returns all child blocks with their type and text content.

Name Type Required Description

block_id string required The ID of the page or block whose children to retrieve

page_size number optional Number of blocks to return (max 100)

start_cursor string optional Cursor for pagination from a previous response

notion_page_create Create a page in Notion either inside a database (as a row) or as a child of a page. Use exactly one parent mode: provide database_id to create a database row (page with properties) OR provide parent_page_id to create a child page. When creating in a database, properties must use Notion property value shapes and the title property key must be "title" (not the display name). Children (content blocks), icon, and cover are optional. The executor should synthesize the Notion parent object from the chosen parent input. Target rules: - Use database_id OR parent_page_id (not both) - If database_id is provided → properties are required - If parent_page_id is provided → properties are optional 10 params ▾

Create a page in Notion either inside a database (as a row) or as a child of a page. Use exactly one parent mode: provide database_id to create a database row (page with properties) OR provide parent_page_id to create a child page. When creating in a database, properties must use Notion property value shapes and the title property key must be "title" (not the display name). Children (content blocks), icon, and cover are optional. The executor should synthesize the Notion parent object from the chosen parent input. Target rules: - Use database_id OR parent_page_id (not both) - If database_id is provided → properties are required - If parent_page_id is provided → properties are optional

Name Type Required Description

_parent object optional Computed by the executor: {"database_id": "..."} OR {"page_id": "..."} derived from database_id/parent_page_id.

child_blocks array optional Optional blocks to add as page content (children).

cover object optional Optional page cover object.

database_id string optional Create a page as a new row in this database (hyphenated UUID). Extract from the database URL (last 32 chars → hyphenate 8-4-4-4-12).

icon object optional Optional page icon object.

notion_version string optional Optional Notion-Version header override.

parent_page_id string optional Create a child page under this page (hyphenated UUID). Extract from the parent page URL.

properties object optional For database rows, supply property values keyed by property name (or id). For title properties, the key must be "title". Example (database row): { "title": { "title": [ { "text": { "content": "Task A" } } ] }, "Status": { "select": { "name": "Todo" } }, "Due": { "date": { "start": "2025-09-01" } } }

schema_version string optional Optional schema version override.

tool_version string optional Optional tool version override.

notion_page_get Retrieve a Notion page by its ID. Returns the page properties, metadata, and parent information. 1 param ▾

Retrieve a Notion page by its ID. Returns the page properties, metadata, and parent information.

Name Type Required Description

page_id string required The ID of the Notion page to retrieve

notion_page_search Search Notion pages by text query. Returns matching pages with their titles, IDs, and metadata. Optionally sort by last_edited_time or created_time, and paginate with start_cursor. 5 params ▾

Search Notion pages by text query. Returns matching pages with their titles, IDs, and metadata. Optionally sort by last_edited_time or created_time, and paginate with start_cursor.

Name Type Required Description

page_size integer optional Maximum number of pages to return (1–100).

query string optional Text to search for across Notion pages.

sort_direction string optional Direction to sort results.

sort_timestamp string optional Timestamp field to sort results by.

start_cursor string optional Cursor to fetch the next page of results.

notion_page_update Update a Notion page's properties, archive/unarchive it, or change its icon and cover. 5 params ▾

Update a Notion page's properties, archive/unarchive it, or change its icon and cover.

Name Type Required Description

page_id string required The ID of the Notion page to update

archived boolean optional Set to true to archive (delete) the page, false to unarchive it

cover object optional Page cover image to set

icon object optional Page icon to set

properties object optional Page properties to update using Notion property value shapes

notion_user_list List all users in the Notion workspace including people and bots. 2 params ▾

List all users in the Notion workspace including people and bots.

Name Type Required Description

page_size number optional Number of users to return (max 100)

start_cursor string optional Cursor for pagination from a previous response