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

Setup guide​

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

  • OAuth2.0 authorization (recommended for Airbyte Cloud)
  • Access Token
note

For Airbyte Cloud 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 Airbyte Cloud, you do not need to create and configure a new integration in Notion. Instead, you can proceed straight to setting up the connector in Airbyte.

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​

  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 workspace containing your data to replicate from the Associated workspace dropdown menu, and click Submit.
  2. In the navbar, select Capabilities and make sure to check the Read content checkbox to authorize Airbyte to read the content of your pages. You may also wish to check the Read comments box, as well as set a User capability to allow access to user information. For more details on the capabilities you can enable, please refer to the Notion documentation on capabilities.

Step 2: Set permissions and acquire authorization credentials

Access Token (Cloud and Open Source)

If you are authenticating via Access Token, you will need to manually set permissions for each page you want to share with Airbyte.

  1. Navigate to the page(s) you want to share with Airbyte. 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 Airbyte.

OAuth2.0 (Open Source only)

If you are authenticating via OAuth2.0 for Airbyte Open Source, 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 Airbyte

  1. Log in to your Airbyte Cloud account, or navigate to your Airbyte Open Source 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 Airbyte Cloud

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

Authentication for Airbyte Open Source

  • Access Token: Copy and paste the Access Token found in the Secrets tab of your Notion integration's page.
  • OAuth2.0: Copy and paste the Client ID, Client Secret and Access Token you acquired.
  1. Enter the Start Date using the provided datepicker, or by programmatically entering a UTC date and time in the format: YYYY-MM-DDTHH:mm:ss.SSSZ. All data generated after this date will be replicated.
  2. Click Set up source and wait for the tests to complete.

Supported sync modes

The Notion source connector supports the following sync modes:

Supported Streams

The Notion source connector supports the following streams. For more information, see the Notion API.

note

The users stream does not support Incremental - Append sync mode.

Performance considerations

The connector is restricted by Notion request limits. The Notion connector should not run into Notion API limitations under normal usage. Create an issue if you encounter any rate limit issues that are not automatically retried successfully.

Changelog

VersionDatePull RequestSubject
1.2.12023-10-0830750Add availability strategy
1.2.02023-10-0431053Add undeclared fields for blocks and pages streams
1.1.22023-08-3029999Update error handling during connection check
1.1.12023-06-1426535Migrate from deprecated authSpecification to advancedAuth
1.1.02023-06-0827170Fix typo in blocks schema
1.0.92023-06-0827062Skip streams with invalid_start_cursor error
1.0.82023-06-0727073Add empty results handling for stream Blocks
1.0.72023-06-0627060Add skipping 404 error in Blocks stream
1.0.62023-05-1826286Add parent field to Blocks stream
1.0.52023-05-0125709Fixed ai_block is unsupported by API issue, while fetching Blocks stream
1.0.42023-04-1125041Improve error handling for API /search
1.0.32023-03-0222931Specified date formatting in specification
1.0.22023-02-2423437Add retry for 400 error (validation_error)
1.0.12023-01-2722018Set AvailabilityStrategy for streams explicitly to None
1.0.02022-12-1920639Fix Pages stream schema
0.1.102022-09-2817298Use "Retry-After" header for backoff
0.1.92022-09-1616799Migrate to per-stream state
0.1.82022-09-0516272Update spec description to include working timestamp example
0.1.72022-07-2615042Update additionalProperties field to true from shared schemas
0.1.62022-07-2114924Remove additionalProperties field from schemas and spec
0.1.52022-07-1414706Added OAuth2.0 authentication
0.1.42022-07-0714505Fixed bug when normalization didn't run through
0.1.32022-04-2211452Use pagination for User stream
0.1.22022-01-119084Fix documentation URL
0.1.12021-12-309207Update connector fields title/description
0.1.02021-10-177092Initial Release