Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to Notion

Scalekit connector
Open markdown

The Notion connector lets your AI agent act in each user's Notion account. Each user signs in to Notion once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 51 tools.

Tools
51
What they doRead · write · destructive
26 · 20 · 526 read20 write5 destructive
Users sign in with
OAuth app
Scalekit's or your own

What you can do

  • 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

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv

  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>

  3. Create the Notion connection

    In AgentKit > Connections, create a Notion connection. The name you give it is the connection_name your code passes. See Configure connections.

    Scalekit credentials are available for Notion, so you don't need to register an OAuth app. To show your own app on the consent screen, use your own credentials instead.

    Use your own OAuth app

    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 AgentKit > Connections > Create Connection. Find Notion and click Create. Copy the redirect URI. It looks like https://<SCALEKIT_ENVIRONMENT_URL>/sso/v1/oauth/<CONNECTION_ID>/callback.

        Copy redirect URI from Scalekit dashboard

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

        Add redirect URI in Notion integration settings

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

        Add credentials in Scalekit dashboard

      • Click Save.

  4. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENVIRONMENT_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'notion'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Notion:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'notion_custom_emojis_list',
      toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user signs in once. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • notion_async_task_retrieveRetrieve the status of an asynchronous Notion operation by task ID.Read-only

    Retrieve Async Task

    Retrieve the status of an asynchronous Notion operation by task ID. Use this to poll long-running operations (such as notion_page_markdown_update when allow_async is set) until status is no longer queued/running/retrying. When complete, the response includes a result object with the operation's outcome.

    Inputs

    task_idstringrequired
    The ID of the async task to retrieve
  • notion_block_retrieveRetrieve a single Notion block by its ID.Read-only

    Retrieve Block

    Retrieve a single Notion block by its ID. Returns the block object (type, content, and metadata) but not its children — use notion_page_content_get to fetch child blocks.

    Inputs

    block_idstringrequired
    The ID of the block to retrieve
  • notion_comment_retrieveRetrieve a single Notion comment by its `comment_id`.Read-only

    Retrieve Comment

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

    Inputs

    comment_idstringrequired
    The identifier of the comment to retrieve (hyphenated UUID). Obtain it from Create-Comment responses or from a prior List-Comments call.
    notion_versionstring
    Optional Notion-Version header override (e.g., 2022-06-28).default 2022-06-28

    Also accepts schema_version and tool_version to pin a version.

  • notion_comments_fetchFetch comments for a given Notion block.Read-only

    Fetch Comments

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

    Inputs

    block_idstringrequired
    Target Notion block (or page) ID to fetch comments for. Use a hyphenated UUID.
    notion_versionstring
    Optional Notion-Version header override (e.g., 2022-06-28).default 2022-06-28
    page_sizeinteger
    Maximum number of comments to return (1–100).default 10
    start_cursorstring
    Cursor to fetch the next page of results.default

    Also accepts schema_version and tool_version to pin a version.

  • notion_custom_emojis_listList custom emojis available in the Notion workspace.Read-only

    List Custom Emojis

    List custom emojis available in the Notion workspace. Supports optional exact-name filtering (useful for resolving a custom emoji name to its ID) and pagination via page_size and start_cursor.

    Inputs

    namestring
    If supplied, filters custom emojis by exact name match. Useful for resolving a custom emoji name to its ID.
    notion_versionstring
    Optional override for the Notion-Version header (e.g., 2022-06-28).default 2022-06-28
    page_sizeinteger
    Maximum number of custom emojis to return (1–100).default 10
    start_cursorstring
    Cursor to fetch the next page of results.default

    Also accepts schema_version and tool_version to pin a version.

  • notion_data_fetchFetch data from Notion using the workspace search API (/search).Read-only

    Fetch Data

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

    Inputs

    page_sizeinteger
    Max number of results to return (1–100)default 10
    querystring
    Text query used by /searchdefault
    start_cursorstring
    Cursor for pagination; pass the previous response's next_cursor

    Also accepts schema_version and tool_version to pin a version.

  • notion_data_source_fetchRetrieve a Notion database's schema, title, and properties using the Notion 2025-09-03 API.Read-only

    Fetch Database (Data Sources)

    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.

    Inputs

    database_idstringrequired
    The target database ID in UUID format with hyphens.
  • notion_data_source_queryQuery rows (pages) from a Notion data source using the 2025-09-03 API.Read-only

    Query Data Source

    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.

    Inputs

    data_source_idstringrequired
    The ID of the data source to query. Retrieve from notion_database_fetch response under data_sources[].id.
    filterobject
    Notion filter object to narrow results. Example: {"property": "Status", "select": {"equals": "Done"}}. Supports compound filters with 'and'/'or' arrays.
    page_sizeinteger
    Maximum number of rows to return (1-100).default 10
    sortsarray
    Order the results. Each item must include either property or timestamp, plus direction.
    start_cursorstring
    Cursor to fetch the next page of results.

Workflows

Proxy API call
const result = await actions.request({
  connectionName: 'notion',
  identifier: 'user_123',
  path: '/v1/users/me',
  method: 'GET',
});
console.log(result);
Execute a tool
const result = await actions.executeTool({
  connector: 'notion',
  identifier: 'user_123',
  toolName: 'notion_user_list',
  toolInput: {},
});
console.log(result);

Related: other Project Management connectors

All 40 in Project Management