Notion

Connect to Notion workspace. Create, edit pages, manage databases, and collaborate on content

Supports authentication: OAuth 2.0

Set up the agent 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.

Usage

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

You can interact with Notion in two ways — via direct proxy API calls or via Scalekit optimized tool calls. Scroll down to see the list of available Scalekit tools.

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)

Scalekit Tools

Tool list

notion_block_delete

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

Name	Type	Required	Description
block_id	string	Yes	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.

Name	Type	Required	Description
block_id	string	Yes	The ID of the block to update
language	string	No	Programming language for code blocks
text	string	Yes	New text content for the block
type	string	Yes	The block type (must match the existing block type)

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.

Name	Type	Required	Description
comment	object	Yes	Comment object containing a rich_text array. Example: {"rich_text":[{"type":"text","text":{"content":"Hello"}}]}
discussion_id	string	No	Existing discussion thread ID to reply to.
notion_version	string	No	Optional override for the Notion-Version header (e.g., 2022-06-28).
parent	object	No	Parent object for a new top-level comment. Shape: {"page_id":"<uuid>"}.
schema_version	string	No	Internal override for schema version.
tool_version	string	No	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.

Name	Type	Required	Description
comment_id	string	Yes	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	No	Optional Notion-Version header override (e.g., 2022-06-28).
schema_version	string	No	Internal override for schema version.
tool_version	string	No	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).

Name	Type	Required	Description
block_id	string	Yes	Target Notion block (or page) ID to fetch comments for. Use a hyphenated UUID.
notion_version	string	No	Optional Notion-Version header override (e.g., 2022-06-28).
page_size	integer	No	Maximum number of comments to return (1–100).
schema_version	string	No	Internal override for schema version.
start_cursor	string	No	Cursor to fetch the next page of results.
tool_version	string	No	Internal override for tool implementation version.

notion_data_fetch

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

Name	Type	Required	Description
page_size	integer	No	Max number of results to return (1–100)
query	string	No	Text query used by /search
schema_version	string	No	Optional schema version to use for tool execution
start_cursor	string	No	Cursor for pagination; pass the previous response’s next_cursor
tool_version	string	No	Optional tool version to use for execution

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).

Name	Type	Required	Description
notion_version	string	No	Optional override for the Notion-Version header (e.g., 2022-06-28).
parent	object	Yes	Parent object specifying the page under which the database is created. Example: {"page_id": "2561ab6c-418b-8072-beec-c4779fa811cf"}
properties	object	Yes	Database schema object defining properties (columns). Example: {"Name": {"title": {}}, "Status": {"select": {"options": [{"name": "Todo"}, {"name": "Doing"}, {"name": "Done"}]}}}
schema_version	string	No	Internal override for schema version.
title	array<object>	Yes	Database title as a Notion rich_text array.
tool_version	string	No	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).

Name	Type	Required	Description
database_id	string	Yes	The target database ID in UUID format with hyphens.
notion_version	string	No	Optional override for the Notion-Version header.
schema_version	string	No	Optional schema version override.
tool_version	string	No	Optional tool version override.

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), andcover` (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
_parent	object	No	Computed by host: { "database_id": "<database_id>" }. Do not supply manually.
child_blocks	array<unknown>	No	Optional array of Notion blocks to append as page content (paragraph, heading, to_do, etc.).
cover	object	No	Optional page cover object. Example external: {"type":"external","external":{"url":"https://example.com/cover.jpg"}}.
database_id	string	Yes	Target database ID (hyphenated UUID).
icon	object	No	Optional page icon object. Examples: {"type":"emoji","emoji":"📝"} or {"type":"external","external":{"url":"https://..."}}.
notion_version	string	No	Optional Notion-Version header override (e.g., 2022-06-28).
properties	object	Yes	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" } } }
schema_version	string	No	Optional schema version override.
tool_version	string	No	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”)

Name	Type	Required	Description
database_id	string	Yes	Target database ID (hyphenated UUID).
property_id	string	No	property ID to filter results by a specific property. get the property id by querying database.
schema_version	string	No	Optional schema version override.
tool_version	string	No	Optional tool version override.

notion_database_query

Query a Notion database for rows (pages). Provide database_id (hyphenated UUID). Optional: page_size, start_cursor for pagination, and sorts (array of sort objects). 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	Yes	Target database ID (hyphenated UUID).
notion_version	string	No	Optional Notion-Version header override.
page_size	integer	No	Maximum number of rows to return (1–100).
schema_version	string	No	Optional schema version override.
sorts	array<object>	No	Order the results. Each item must include either property or timestamp, plus direction.
start_cursor	string	No	Cursor to fetch the next page of results.
tool_version	string	No	Optional tool version override.

notion_database_update

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

Name	Type	Required	Description
database_id	string	Yes	The ID of the database to update
description	string	No	New description for the database
properties	object	No	Property schema updates (add, rename, or reconfigure columns)
title	string	No	New title for the database

notion_page_content_append

Append blocks to a Notion page or block. Supports paragraph, heading_1/2/3, bulleted_list_item, numbered_list_item, code, quote, callout, and divider block types.

Name	Type	Required	Description
block_id	string	Yes	The ID of the page or block to append content to
blocks	array<object>	Yes	Array of blocks to append. Each block has a type and text (plus optional language for code blocks).

notion_page_content_get

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	Yes	The ID of the page or block whose children to retrieve
page_size	number	No	Number of blocks to return (max 100)
start_cursor	string	No	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

Name	Type	Required	Description
_parent	object	No	Computed by the executor: {"database_id": "..."} OR {"page_id": "..."} derived from database_id/parent_page_id.
child_blocks	array<unknown>	No	Optional blocks to add as page content (children).
cover	object	No	Optional page cover object.
database_id	string	No	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	No	Optional page icon object.
notion_version	string	No	Optional Notion-Version header override.
parent_page_id	string	No	Create a child page under this page (hyphenated UUID). Extract from the parent page URL.
properties	object	No	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	No	Optional schema version override.
tool_version	string	No	Optional tool version override.

notion_page_get

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

Name	Type	Required	Description
page_id	string	Yes	The ID of the Notion page to retrieve

notion_page_update

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

Name	Type	Required	Description
archived	boolean	No	Set to true to archive (delete) the page, false to unarchive it
cover	object	No	Page cover image to set
icon	object	No	Page icon to set
page_id	string	Yes	The ID of the Notion page to update
properties	object	No	Page properties to update using Notion property value shapes

notion_user_list

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

Name	Type	Required	Description
page_size	number	No	Number of users to return (max 100)
start_cursor	string	No	Cursor for pagination from a previous response