Skip to main content

Notion

This page contains the setup guide and reference information for the Notion source connector.

Prerequisites​

  • Access to a Notion workspace
  • You must be a workspace owner to create a Notion integration

Setup guide​

To authenticate the Notion source connector, you need to use one of the following two methods:

  • OAuth2.0 authorization (recommended for Calabi Connect)
  • Access Token
note

For Calabi Connect users: We highly recommend using OAuth2.0 authorization to connect to Notion, as this method significantly simplifies the setup process. If you use OAuth2.0 authorization in Calabi Connect, you do not need to create and configure a new integration in Notion. Instead, you can proceed straight to setting up the connector in Calabi Connect.

We have provided a quick setup guide for creating an integration in Notion below. If you would like more detailed information and context on Notion integrations, or experience any difficulties with the integration setup process, please refer to the official Notion documentation.

Step 1: Create an integration in Notion and set capabilities​

  1. Log in to your Notion workspace and navigate to the My integrations page. Select New integration.
note

You must be the owner of the Notion workspace to create a new integration associated with it.

  1. Enter a Name for your integration. Make sure you have selected the correct workspace from the Associated workspace dropdown menu, and click Submit.
  2. In the navbar, select Capabilities. Check the following capabilities based on your use case:

Step 2: Share pages and acquire authorization credentials​

Access Token (Cloud and Open Source)​

If you are authenticating via Access Token, you will need to manually share each page you want to sync with Calabi Connect.

  1. Navigate to the page(s) you want to share with Calabi Connect. Click the ••• menu at the top right of the page, select Add connections, and choose the integration you created in Step 1.
  2. Once you have selected all the pages to share, you can find and copy the Access Token from the Secrets tab of your Notion integration's page. Then proceed to setting up the connector in Calabi Connect.

OAuth2.0 (Open Source only)​

If you are authenticating via OAuth2.0 for Calabi Connect, you will need to make your integration public and acquire your Client ID, Client Secret and Access Token.

  1. Navigate to the Distribution tab in your integration page, and toggle the switch to make the integration public.
  2. Fill out the required fields in the Organization information and OAuth Domain & URIs section, then click Submit.
  3. Navigate to the Secrets tab to find your Client ID and Client Secret.
  4. You need to use your integration's authorization URL to set the necessary page permissions and send a request to obtain your Access Token. A thorough explanation of the necessary steps is provided in the official Notion documentation. Once you have your Client ID, Client Secret and Access Token, you are ready to proceed to the next step.

Step 3: Set up the Notion connector in Calabi Connect​

  1. Log in to your Calabi Connect account, or navigate to your Calabi Connect dashboard.
  2. In the left navigation bar, click Sources. In the top-right corner, click New source.
  3. Find and select Notion from the list of available sources.
  4. Enter a Source name of your choosing.
  5. Choose the method of authentication from the dropdown menu:

Authentication for Calabi Connect​

  • OAuth2.0 (Recommended): Click Authenticate your Notion account. When the popup appears, click Select pages. Check the pages you want to give Calabi Connect access to, and click Allow access.
  • Access Token: Copy and paste the Access Token found in the Secrets tab of your private integration's page.

Authentication for Calabi Connect​

  • Access Token: Copy and paste the Access Token found in the Secrets tab of your private integration's page.
  • OAuth2.0: Copy and paste the Client ID, Client Secret and Access Token you acquired after setting up your public integration.
  1. (Optional) You may optionally provide a Start Date using the provided datepicker, or by programmatically entering a UTC date and time in the format: YYYY-MM-DDTHH:mm:ss.SSSZ. When using incremental syncs, only data generated after this date will be replicated. If left blank, Calabi Connect will set the start date two years from the current date by default.
  2. Click Set up source and wait for the tests to complete.

Supported sync modes​

The Notion source connector supports the following sync modes:

StreamFull Refresh (Overwrite/Append)Incremental (Append/Append + Deduped)
Blocks✓✓
Comments✓✓
Data Sources✓✓
Pages✓✓
Users✓

Supported streams​

The Notion source connector supports the following streams:

  • Blocks: Retrieves content blocks for all synced pages, including recursively nested child blocks up to 30 levels deep. Block types child_page, child_database, and ai_block are excluded.
  • Comments: Retrieves comments on all synced pages. Requires the Read comments integration capability.
  • Data Sources: Retrieves data source objects. In the Notion API 2025-09-03, a data source represents a structured table that contains pages and properties — previously called a "database." This stream replaces the former Databases stream as of v4.0.0. For details on migrating, see the Notion migration guide.
  • Pages: Retrieves page objects from all shared pages.
  • Users: Retrieves user objects from the workspace. Requires the Read user information integration capability.

Performance considerations​

The Notion API enforces a rate limit of approximately three requests per second per integration. When the connector receives an HTTP 429 response, it respects the Retry-After header and retries the request automatically. Rate-limited requests do not count toward the maximum retry limit, so syncs continue indefinitely until the rate limit clears. For more details, see Notion's request limits documentation.

The Blocks stream recursively fetches child blocks up to 30 levels deep. Pages with deeply nested content can generate a large number of API requests, which may slow down syncs for workspaces with complex page structures.