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

# Notion

> Integration details and setup guide for the Notion connector in Alloy Automation.

## Pre-Built Tooling

| Category                            | Details                                                                 |
| ----------------------------------- | ----------------------------------------------------------------------- |
| **Authentication**                  | OAuth 2.0 (Authorization Code with refresh tokens)                      |
| **Two-Way Sync**                    | No                                                                      |
| **Events Supported**                | No                                                                      |
| **Realtime**                        | Polling                                                                 |
| **Supports Rate Limiting**          | Yes                                                                     |
| **Authentication Scopes Supported** | No granular scopes (full workspace access granted during authorization) |

***

## Objects Supported

Alloy Automation supports syncing the following objects from **Notion**:

Based on the Notion API, typical objects include:

* **Pages**
* **Databases**
* **Blocks**
* **Comments**
* **Users**
* **Search Results**

***

## Set Up Guide

### Trial Access

| Question                                           | Answer                                                                                                                           |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Offers free trial?**                             | Yes. Notion offers a free plan for individuals with unlimited pages and blocks. [Sign up for free](https://www.notion.so/signup) |
| **Requires paid sandbox**                          | No. Free personal workspaces can be used for testing and development.                                                            |
| **Requires partnership to obtain authentication?** | No, but you must create an integration in the Notion developer portal.                                                           |

***

### Authentication (OAuth 2.0)

For customers who want to completely whitelabel their OAuth experience, you can provide your own developer keys instead of using Alloy Automation's.

#### Create your OAuth app (Notion Integrations)

1. Go to **Notion Integrations** ([https://www.notion.so/my-integrations](https://www.notion.so/my-integrations)) and sign in with your Notion account.
2. Click **New integration** (or **Create new integration**).
3. Fill in your integration details:
   * **Name**: Your integration's name
   * **Logo**: Upload an icon for your integration (optional)
   * **Associated workspace**: Select the workspace where you'll test the integration
   * **Type**: Choose "Public" for OAuth integrations used by multiple users
4. Under **Integration type**, select **Public Integration**.
5. Configure the **OAuth Domain & URIs**:
   * **Redirect URIs**: Add `https://api.runalloy.com/api/strategy/connector/notion/callback`
6. Under **Capabilities**, select the permissions your integration needs:
   * Read content
   * Update content
   * Insert content
   * Read comments
   * Create comments
   * Read user information (including email)
7. Click **Submit** to create the integration.
8. You'll receive your **OAuth client ID** and **OAuth client secret**.
9. Copy these credentials into Alloy Automation.

#### Important Notes

* Notion uses a permission model where users explicitly grant access to specific pages and databases during authorization.
* The integration will only have access to content that users share with it.
* The `Notion-Version` header is required on all API requests (current version: `2022-06-28`).

***

## Use Cases

### 1) Knowledge base synchronization

Sync content from Notion pages and databases into your documentation platform, help center, or internal wiki, keeping knowledge bases up-to-date across multiple systems.

### 2) Project and task management integration

Extract project tasks, roadmaps, and sprint boards from Notion databases and sync them with project management tools, enabling teams to work in their preferred environment while maintaining centralized tracking.

### 3) CRM and sales pipeline

Use Notion databases as a flexible CRM, syncing contact information, deal stages, and sales activities with traditional CRM systems or data warehouses for reporting and analytics.

### 4) Content publishing automation

Automatically publish blog posts, documentation, or marketing content from Notion to your website or CMS, treating Notion as a content authoring platform while maintaining SEO-optimized published versions.

### 5) Meeting notes and action items

Extract action items, decisions, and meeting summaries from Notion pages and distribute them via email, Slack, or task management tools, ensuring follow-up on commitments made during meetings.

***

## API Gotchas

* Notion's permission model is workspace-based, meaning users must explicitly share pages and databases with your integration during OAuth authorization. If content isn't shared, API calls will return empty results rather than permission errors, which can be confusing.

* The `Notion-Version` header is mandatory on every API request. Omitting it causes requests to fail with 400 errors. The version format is date-based (e.g., `2022-06-28`), and Notion deprecates old versions periodically, requiring version migration.

* Block content has deeply nested structures with different schemas for each block type (paragraph, heading, list, code, etc.). Parsing block content requires recursive traversal and type-specific handling. Rich text within blocks is also nested with styling annotations.

* Database properties have complex schemas that vary by property type (select, multi-select, date, people, formula, relation, etc.). Reading and writing database entries requires understanding each property type's specific JSON structure, which is not intuitive and poorly documented.

> For questions or troubleshooting, contact **[support@runalloy.com](mailto:support@runalloy.com)**.