> ## Documentation Index
> Fetch the complete documentation index at: https://explore.airia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Notion

# Set Up the Notion Connector

The Notion Connector allows you to ingest pages, subpages, and their attachments from your Notion workspace into your project. You can authenticate in one of two ways:

* **Airia-managed OAuth** — Use Airia's built-in Notion integration. No Notion integration setup is required.
* **Bring Your Own OAuth (BYOO)** — Register your organization's own Notion integration. This gives you full control over the integration's name, branding, and capabilities shown on the consent screen.

> 💡 Note: The connector currently supports only text content. Images, tables, and videos are not supported.

> 💡 Tip: To use **Airia-managed OAuth**, skip ahead to [Create a Notion Data Source](#create-a-notion-data-source) and select the **Airia Managed OAuth Connector** when configuring the data source. To use **BYOO**, complete the integration setup below first.

## Set Up Your Notion Integration

> 💡 Note: This section applies only if you are using **Bring Your Own OAuth**. If you are using **Airia-managed OAuth**, skip to [Create a Notion Data Source](#create-a-notion-data-source).

This one-time setup registers your organization's integration in Notion so Airia can access Notion pages on your users' behalf.

### 1. Get the Redirect URL from Airia

Before creating the integration in Notion, copy the redirect URL that Airia will use for the OAuth callback:

1. In the Airia platform, navigate to **Settings** > **Ecosystem** > **App connections**.
2. Select the **Available** tab and click **Notion**.
3. Copy the **Redirect URL** displayed on the form (for example, `https://auth.airia.ai/OAuth/callback`).

> ⚠️ Warning: The redirect URL must be pasted into the Notion integration settings exactly as shown. A mismatch causes a redirect error during authentication.

### 2. Create a Public Notion Integration

1. Go to [Notion integrations](https://www.notion.so/profile/integrations) and click **New integration**.
2. Enter a **Name** (e.g., `Airia Connector`) and select the associated workspace.
3. Set the integration **Type** to **Public**. Only public integrations support the OAuth flow; internal integrations cannot be used with the connector.
4. Fill in the required public-integration fields (company name, website, privacy policy, and terms of use URLs).
5. Under **OAuth Domain & URIs**, add the **Redirect URI** you copied from Airia in Step 1.
6. Under **Capabilities**, enable **Read content**. Write and comment capabilities are not needed.
7. Save the integration, then copy the **OAuth Client ID** and **OAuth Client Secret** — you will need these in the next section.

## Register the OAuth Connector in Airia

1. In the Airia platform, navigate to **Settings** > **Ecosystem** > **App connections**.
2. Select the **Available** tab and click **Notion**.
3. Enter the following details:
   * **Name**: A descriptive name to identify this connector (e.g., `Company Notion`).
   * **Client ID**: The OAuth Client ID from your Notion integration.
   * **Client Secret**: The OAuth Client Secret from your Notion integration.
   * **Scopes**: Add `read` (see [Scopes and Page Access](#scopes-and-page-access)).
4. Click **Create**.

## Create a Notion Data Source

### 1. Add a New Notion Data Source

1. In the Airia platform, navigate to **Available data sources**.
2. Select the **Notion** card.

### 2. Configure Data Source Details

1. Provide the following details:
   * **Name**: A mandatory, descriptive name for your data source.
   * **Description**: (Optional) A brief description.
   * **Scope**: Select the Airia project for this data source.
   * **OAuth connector**: From the dropdown, select the **Airia Managed OAuth Connector**, or the Notion OAuth connector you registered above (BYOO).
2. For **Credentials**, choose `Create new credential`, or select an existing Notion credential.
3. Enter a **Name** for the new credential.
4. Click **Authenticate**. Notion's authorization screen opens.

### 3. Select Pages on Notion's Authorization Screen

Unlike file-storage connectors, you select content for Notion **during the OAuth flow itself**. On Notion's authorization screen:

1. Sign in to Notion with an account that has access to the content you want to ingest.
2. When prompted, choose **Select pages to share** and pick the pages to give Airia access to.
3. Confirm to complete the authorization.

Airia ingests **all pages you shared with the integration**, including their subpages and supported attachments.

> 💡 Tip: When you share a page, all its sub-content — subpages and their supported attachments — is also ingested.

### 4. Monitor Ingestion Status

Once you save the data source, the page refreshes to display the ingestion status. You can view the current status at any time by opening the data source. In the detailed list, ingested pages and subpages are shown as `json` file types; attachments are listed as separate file types.

## Change Which Pages Are Ingested

To change the shared pages, open the data source and click **Select Content**. This restarts the Notion authorization flow and **replaces the existing credential** — reselect all the pages you want shared, including ones you shared before. After updating the selection, reprocess the data source to sync the changes.

## Scopes and Page Access

Notion does not use granular OAuth scopes the way file-storage providers do. Access is controlled by two things:

| Control                      | Where it is set                    | Effect                                                                                   |
| ---------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------- |
| **Integration capabilities** | Notion integration settings (BYOO) | Must include **Read content** for ingestion to work.                                     |
| **Shared pages**             | Notion's authorization screen      | Airia can only see the pages the user explicitly shares — nothing else in the workspace. |

The `read` scope on the Airia connector records this read-only intent; the effective access is always limited to the pages shared during authorization.

## Migrate Existing Data Sources from the Legacy Authentication Flow

Notion data sources created with the legacy authentication flow (signing in to Notion directly, without an OAuth connector) should be updated to the connector-based flow. An administrator updates each existing data source once:

1. Open the data source and click **Edit**.
2. Select the **OAuth connector** — your BYOO Notion connector, or the Airia Managed OAuth Connector.
3. **Create** a new credential, or **select** an existing one.
4. Complete the Notion authorization flow, selecting the pages to share, then save.

## Limitations

| Limitation                             | Details                                                                                                                                                  |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Text content only**                  | Images, tables, and videos inside pages are not ingested.                                                                                                |
| **Credentials are user-specific**      | Credentials are not shared. Each user must authenticate independently through the OAuth flow.                                                            |
| **Page selection lives in Notion**     | Changing the ingested pages requires re-running the Notion authorization flow (see [Change Which Pages Are Ingested](#change-which-pages-are-ingested)). |
| **Public integration required (BYOO)** | Notion's OAuth flow is only available to public integrations; internal integrations cannot be used.                                                      |

## Troubleshooting

| Symptom                                           | Likely Cause                                                                             | Resolution                                                                                                                             |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| OAuth callback fails with a redirect error        | The redirect URI in the Notion integration does not match Airia's                        | Copy the exact Redirect URL from the Airia Notion connector form and paste it into the integration's **OAuth Domain & URIs** settings. |
| Authorization succeeds but no content is ingested | No pages were shared with the integration on the authorization screen                    | Click **Select Content** on the data source and share the pages you want to ingest.                                                    |
| A page is missing from the data source            | The page was not shared with the integration, or it was moved outside a shared page tree | Re-run **Select Content** and include the page in the shared selection, then reprocess the data source.                                |
| Ingestion fails after authorization               | The integration is missing the **Read content** capability                               | Enable **Read content** in the Notion integration settings, then re-authenticate.                                                      |

## Next Steps

After your data has been successfully ingested, the Notion data source is ready to be used with an Agent.