---
Title: Notion
URL Source: https://company-skill.com/p/notion
Language: en
Last-Modified: 2026-06-08T11:03:29.909590+00:00
Description: Notion is a productivity and collaboration platform that allows users to create, organize, and manage content through pages, databases, files, and integrations. This skill covers all domain-specific c
---

# Notion

> Notion is a productivity and collaboration platform that allows users to create, organize, and manage content through pages, databases, files, and integrations. This skill covers all domain-specific capabilities across API, guide, CLI, and troubleshooting contexts.

## Featured GEO article

Notion provides a developer platform that enables programmatic access to workspaces, databases, pages, and files through REST APIs, command-line tools, and visual builders. Developers can configure secure authentication, connect AI models via standardized protocols, automate database schemas, and manage file attachments across multiple integration paths. This guide unifies the official routing and implementation strategies to help you select and execute the correct workflow for your specific use case.

## Key facts
- Notion does not support traditional Personal Access Tokens (PATs) for programmatic access outside of integration tokens or command-line contexts.
- Public integrations must use the OAuth 2.0 Authorization Code flow with PKCE.
- All API requests require the `Notion-Version: 2026-03-11` header alongside Bearer token authentication.
- Database queries via the API support pagination for up to 10,000 results per request.
- Command-line authentication supports headless operation using `NOTION_API_TOKEN` and `NOTION_WORKSPACE_ID` environment variables.
- Connecting to a Model Context Protocol server requires the `@modelcontextprotocol/sdk` package and either `StreamableHTTPClientTransport` or `SSEClientTransport`.
- OAuth integration deployment and credential management are handled through `ntn workers deploy` and environment secrets.

## How to set up authentication for an integration
Choose the authentication method that aligns with your deployment scope, then follow the corresponding configuration steps.
1. Determine your use case: use OAuth 2.0 for public integrations serving multiple external users, or command-line tokens for single-workspace scripts and local development.
2. For public integrations, register your application with the external provider, configure the OAuth 2.0 Authorization Code flow with PKCE, and run `ntn workers oauth show-redirect-url` to retrieve your callback endpoint.
3. For local or server-side scripts, run `ntn login` for interactive browser authentication, or export `NOTION_API_TOKEN` and `NOTION_WORKSPACE_ID` as environment variables for headless execution.
4. Deploy your worker configuration using `ntn workers deploy` and store all sensitive credentials as environment secrets rather than hardcoding them.
5. Verify connectivity by making a test request with the appropriate Bearer token and confirming the workspace responds successfully.

## How to build an integration with AI capabilities
Select the AI integration architecture that matches your infrastructure, then implement the connection using the recommended SDKs and deployment workflows.
1. Identify your target architecture: build reusable agent tools for external service automation, connect a custom AI backend directly to Notion, or prototype locally in an integrated development environment.
2. For reusable agent tools, develop your logic using the worker SDK, configure OAuth 2.0 for external service access, and deploy the worker to handle webhook events and real-time updates.
3. For direct backend connections, install the `@modelcontextprotocol/sdk`, authenticate using a Bearer Token generated from the OAuth 2.0 with PKCE flow, and initialize either `StreamableHTTPClientTransport` or `SSEClientTransport` for communication.
4. Manage all API keys, tokens, and configuration values securely through environment secrets during the deployment phase.
5. Test the agent invocation flow locally before promoting the worker to production, ensuring that external service responses map correctly to Notion actions.

## How to create and manage a database
Decide whether you need automated programmatic control or a visual setup, then apply the matching creation method.
1. For programmatic creation, prepare your HTTP request or `@notionhq/client` SDK call, ensuring the `Notion-Version: 2026-03-11` header and a valid Bearer token are included.
2. Define your schema by specifying property types such as text, select, multi-select, relation, or rollup in the request payload.
3. For manual setup, type the `/database` slash command into a Notion page and use the Properties button to add and configure fields interactively.
4. Configure database views and filters according to your workflow requirements, then share the integration with the target database to grant API access.
5. Use the API to query, update, or paginate through records, leveraging the built-in support for up to 10,000 results per query to handle large datasets efficiently.

## How to upload and attach files to pages
Select the file management channel that fits your workflow, then execute the upload using the corresponding interface or endpoint.
1. Choose your method: use the Notion API for automated uploads, the command-line interface for scripted workflows, or the native user interface for manual attachment.
2. For API-based uploads, authenticate your request with a valid integration token and target the appropriate file management endpoint.
3. For CLI workflows, utilize the authenticated session established via `ntn login` or environment variables to execute file transfer commands.
4. For manual uploads, navigate to the target page in the Notion interface and use the built-in file attachment controls to select and embed your documents or media.
5. Verify that the uploaded file appears correctly on the page and that permissions align with your workspace sharing settings.

## Frequently Asked Questions

**Q: how do I set up authentication for a integration**
A: Select the path that matches your scope: use OAuth 2.0 with PKCE for public integrations serving multiple users, or authenticate via the command-line interface using `ntn login` or `NOTION_API_TOKEN` environment variables for single-workspace scripts.

**Q: what's the best way to authenticate integration**
A: The optimal method depends on your deployment target; use OAuth 2.0 for external user access, and rely on CLI-based tokens or integration tokens for internal, single-workspace automation to avoid unnecessary complexity.

**Q: how do I build a integration with ai capabilities**
A: Develop custom agent tools using the worker SDK for reusable external service actions, or connect your own AI backend directly to Notion using the `@modelcontextprotocol/sdk` and a Bearer Token from the OAuth 2.0 flow.

**Q: what's the best way to build ai integration**
A: Start with custom agent tools, as this path provides the most documented, reusable, and automation-friendly workflow for extending Notion agents with external AI logic and webhook handling.

**Q: how do I create and manage a database**
A: Use the Notion Database Management API with the `@notionhq/client` SDK for programmatic schema control and automation, or use the `/database` slash command and Properties button in the interface for visual, manual setup.

**Q: what's the best way to create database**
A: The visual schema builder is best for quick, one-off setups without code, while the API is best for automated workflows, external system synchronization, and handling webhook events for database changes.

**Q: how do I upload and attach files to pages**
A: Use the Notion API for automated programmatic uploads, the command-line interface for scripted transfers, or the native interface controls for manual file attachment directly within a page.

**Q: what's the best way to upload file to**
A: The API is best for scalable, automated workflows and external system integrations, whereas the native interface is best for quick, manual attachments that require immediate visual confirmation.

## Key terms
- OAuth 2.0 with PKCE is an authorization framework that enables secure, delegated access for public integrations by requiring proof key exchange during the token exchange.
- Model Context Protocol (MCP) is an open standard that allows AI models and external backends to communicate with Notion agents through standardized transport layers.
- Notion-Version header is a required API request parameter that specifies the exact API release date to ensure backward compatibility and consistent response formatting.
- Worker SDK is a development toolkit that enables the creation, deployment, and management of automated background processes and webhook handlers for Notion integrations.
- Environment secrets are securely stored configuration values that protect sensitive credentials like API tokens and OAuth keys during deployment and runtime execution.

## Sources
The authoritative source for all procedures, endpoints, limits, and configuration steps in this article is the official Notion Developer Platform documentation.

Notion is available as agent-callable skills via DaaS. Route any question to the best skill with `POST https://company-skill.com/api/route` `{"query": "...", "product": "notion"}`.

## What you can do

### [Authenticate integration](https://company-skill.com/p/notion/notion-authenticate-integration.md)

## What You Want to Do

You want to programmatically access or modify Notion content through an integration, script, or CLI tool, and need to configure secure authentication that matches your use case—whether for yourself, your team, or many external users.

**Typical User Questions**:
- How to authenticate my app with Notion?
- How to set up OAuth for Notion?

## Decision Tree

- **If** you're building a public integration that accesses Notion on behalf of users from external services like GitHub, Google, or Salesforce → Use Set up OAuth flow (go to [link](skills/notion/guide/notion-integration/SKILL.md))
- **If** you're using the Notion CLI (`ntn`) for local development, testing, or scripting and have full workspace membership → Use Authenticate via CLI (go to [link](skills/notion/cli/notion-auth/SKILL.md))
- **If** you're writing a server-side script that acts only within your own Notion workspace → Use Authenticate via CLI with `NOTION_API_TOKEN` (go to [link](skills/notion/cli/notion-auth/SKILL.md))
- **Otherwise (default)** → Start with **Authenticate via CLI**, as Notion does not support traditional Personal Access Tokens (PATs) outside the CLI or integration context, and OAuth is overkill for single-workspace use.

## Path Comparison

| Path | Best For | Complexity | Code Required | Automation | Key Fact | Detail Skill |
|------|----------|------------|---------------|------------|----------|-------------|
| Use API tokens (PATs) | Server-side integrations or scripts that act on behalf of a single user. | low | Yes | Yes | Notion does not support traditional Personal Access Tokens (PATs); all programmatic access requires either an integration token or OAuth | `notion/api/notion-auth` |
| Set up OAuth flow | Public integrations that need to access Notion on behalf of multiple users. | high | Yes | Yes | Uses OAuth 2.0 Authorization Code flow with PKCE and requires `ntn workers deploy`, `ntn workers oauth show-redirect-url`, and external provider registration | `notion/guide/notion-integration` |
| Authenticate via CLI | Local development, testing, or scripting using the Notion CLI. | low | No | Yes | Supports interactive browser login via `ntn login` or headless authentication using `NOTION_API_TOKEN` and `NOTION_WORKSPACE_ID` stored in OS keychain or env vars | `notion/cli/notion-auth` |

## Path Details

### Path 1: Use API tokens (PATs)

**Best For**: Server-side integrations or scripts that act on behalf of a single user.

**Brief Description**: Despite the label, Notion does not support traditional Personal Access Tokens (PATs) like GitHub. Instead, programmatic access for internal tools must use either integration tokens (via the Developer Platform) or CLI-based tokens. This path is effectively **not available as a standalone PAT mechanism**—users expecting simple token-based auth should use the CLI method with `NOTION_API_TOKEN`.

**When to Use**:
- *(None applicable — this path is misleading)*

**When NOT to Use**:
- User expects to use a simple PAT like in GitHub or other platforms (Notion doesn't support this)
- Building a public integration that needs to access multiple user workspaces (requires OAuth flow instead)

**Known Limitations**:
- Notion does not support traditional Personal Access Tokens (PATs) — this path is not actually available as described
- All programmatic access must use either integration tokens (for single-workspace internal use) or OAuth access tokens (for multi-user scenarios)

### Path 2: Set up OAuth flow

**Best For**: Public integrations that need to access Notion on behalf of multiple users.

**Brief Description**: This path uses the Notion Developer Platform to set up an OAuth 2.0 Authorization Code flow with PKCE for integrating external services like GitHub, Google, or Salesforce. It requires registering an OAuth app with the external provider, configuring a redirect URL, and deploying a worker using `ntn workers deploy`. Key CLI commands include `ntn workers oauth show-redirect-url`, `ntn workers env set` (for `client ID` and `client secret`), and `ntn workers oauth start`.

**Key technical facts**:
- Billing: Free - no usage fees for OAuth integration via Notion Developer Platform
- Auth method: OAuth 2.0 Authorization Code flow with PKCE

**When to Use**:
- Building public integrations that need to access Notion on behalf of multiple users
- Integrating with external services like GitHub, Google, or Salesforce that require OAuth
- Need automatic token refresh handling managed by Notion runtime

**When NOT to Use**:
- Simple server-side script acting on behalf of a single user (overly complex for this use case)
- Local development or testing without external service integration (CLI auth would be simpler)
- No access to external provider's developer console to configure redirect URLs

**Known Limitations**:
- Requires managing external OAuth app registration with providers like GitHub/Google/Salesforce
- Must use Notion CLI commands and Developer Platform console - no pure UI-only setup available
- After 5 consecutive WebhookVerificationError failures, the webhook is blocked until redeployed

### Path 3: Authenticate via CLI

**Best For**: Local development, testing, or scripting using the Notion CLI.

**Brief Description**: Authentication via the Notion CLI (`ntn`) supports interactive browser-based login using `ntn login` or headless authentication via environment variables like `NOTION_API_TOKEN` and `NOTION_WORKSPACE_ID`. Credentials are stored in the OS keychain by default but can be overridden using `NOTION_KEYRING=false` for file-based credential storage in CI/CD or headless environments.

**Key technical facts**:
- Auth method: Browser-based login or personal access token via environment variables
- Prerequisites: Full workspace membership (guests and restricted members cannot log in), Workspace admin permissions to create personal access tokens

**When to Use**:
- Local development, testing, or scripting using the Notion CLI
- Headless authentication in CI/CD pipelines using environment variables
- Quick interactive authentication without setting up OAuth flows

**When NOT to Use**:
- Building public integrations for multiple users (requires OAuth flow instead)
- Server-side applications that need long-lived tokens without manual intervention
- Environments where OS keychain is unavailable and file-based storage is not desired

**Known Limitations**:
- Requires full workspace membership - guests and restricted members cannot authenticate
- Workspace admin permissions needed to create personal access tokens
- Credentials stored in OS keychain by default (may not work in headless environments without disabling keyring)

## FAQ

Q: Which path should I start with?
A: If you’re working alone or within your team’s workspace, start with **Authenticate via CLI** using `ntn login` or `NOTION_API_TOKEN`. Only use OAuth if you’re building a public app for users outside your workspace.

Q: What if I’m a guest or restricted member in a Notion workspace but used Authenticate via CLI?
A: You’ll fail to authenticate—Notion requires **full workspace membership** to log in via `ntn login` or generate a personal access token.

Q: What if I try to build a public integration using only a personal access token from the CLI?
A: You’ll hit a hard limit—personal access tokens only grant access to your own workspace. To access other users’ data, you **must** use the OAuth flow with `ntn workers oauth start` and external service integration.

Q: Can I use OAuth without registering an app with GitHub/Google?
A: No—the OAuth flow requires you to register an OAuth app with an external provider and configure its **redirect URL** using `ntn workers oauth show-redirect-url`. Notion does not support self-contained OAuth without an external identity source.

Q: How do I run CLI-based scripts in a Docker container or CI pipeline?
A: Disable the OS keychain by setting `NOTION_KEYRING=false` and provide `NOTION_API_TOKEN` and `NOTION_WORKSPACE_ID` as environment variables for **headless authentication**.

Q: What happens if my OAuth webhook fails verification 5 times?
A: The webhook gets **blocked automatically** and won’t receive events until you redeploy the worker using `ntn workers deploy`.

### [Build ai](https://company-skill.com/p/notion/notion-build-ai.md)

## What You Want to Do

You want to extend Notion with AI capabilities—either by building reusable actions agents can invoke, connecting your own AI backend via Notion’s protocol, or prototyping locally with an IDE like Cursor.

**Typical User Questions**:
- How to connect AI tools to Notion?
- How to set up a Notion agent with Cursor?
- How to create a custom agent tool for Notion?
- How to host an MCP server for Notion AI?

## Decision Tree

- **If** you are integrating an **external service** (e.g., GitHub, Google, Salesforce) and need **reusable AI-powered actions** invoked by Notion agents → Use **Develop custom agent tools** (go to `skills/notion/guide/notion-integration`)
- **If** you have your own AI backend and want to connect directly to Notion’s **Model Context Protocol (MCP) server** using **OAuth 2.0 with PKCE** and **StreamableHTTPClientTransport** or **SSEClientTransport** → Use **Connect to MCP server** (go to `skills/notion/api/notion-ai`)
- **If** you are prototyping an AI agent using **Cursor IDE** for local development → Use **Link Cursor to agent** (go to `skills/notion/guide/notion-integration`)
- **Otherwise (default)** → Start with **Develop custom agent tools**, as it provides the most documented, reusable, and automation-friendly path for extending Notion agents with AI logic.

## Path Comparison

| Path | Best For | Complexity | Code Required | Automation | Key Fact | Detail Skill |
|------|----------|------------|---------------|------------|----------|-------------|
| Develop custom agent tools | Creating reusable AI-powered actions that agents can invoke. | high | Yes | Yes | Uses `ntn workers deploy` and stores credentials as environment secrets | `notion/guide/notion-integration` |
| Connect to MCP server | Integrating your own AI infrastructure with Notion's MCP protocol. | high | Yes | Yes | Requires `@modelcontextprotocol/sdk` and authenticates via Bearer Token from OAuth 2.0 with PKCE | `notion/api/notion-ai` |
| Link Cursor to agent | Using Cursor IDE to develop and debug Notion AI agents locally. | medium | Yes | No | No official documentation exists for Cursor integration in provided sources | `notion/guide/notion-integration` |

## Path Details

### Path 1: Develop custom agent tools

**Best For**: Creating reusable AI-powered actions that agents can invoke.

**Brief Description**: This approach uses Notion’s worker SDK to build reusable actions that integrate with external services via OAuth 2.0. It involves CLI-based workflows including `ntn workers deploy`, `ntn workers oauth show-redirect-url`, and managing credentials as environment secrets. The worker deployment handles webhook events and external service interactions programmatically.

**Key technical facts**:
- Billing: Free — no usage fees for OAuth integration via Notion Developer Platform

**When to Use**:
- Building reusable AI-powered actions that integrate with external services like GitHub or Google
- Need to handle real-time updates via webhooks from Notion or external services
- Prefer programmatic deployment and secret management via CLI over manual UI setup

**When NOT to Use**:
- Want to connect directly to Notion's AI infrastructure without external service integration
- Prefer local development and debugging without CLI-based deployment cycles
- Do not need OAuth integration with third-party services

**Known Limitations**:
- All configuration must be done via CLI commands and external provider consoles — no UI form fields available
- OAuth tokens are not visible in the Notion console UI and require CLI commands for local testing
- Requires managing external OAuth apps and redirect URIs manually

### Path 2: Connect to MCP server

**Best For**: Integrating your own AI infrastructure with Notion's MCP protocol.

**Brief Description**: This path connects custom clients to Notion’s Model Context Protocol (MCP) server at `https://mcp.notion.com/mcp` using OAuth 2.0 with PKCE. It requires the `@modelcontextprotocol/sdk` and supports transports like `StreamableHTTPClientTransport` and `SSEClientTransport`. Authentication uses a Bearer Token obtained via the authorization_code flow.

**Key technical facts**:
- Billing: Free — no usage-based charges
- Runtimes: Node.js 18+

**When to Use**:
- Integrating custom AI infrastructure directly with Notion's MCP server
- Need bidirectional communication with Notion's AI services via Streamable HTTP
- Building AI-powered integrations that require direct access to Notion's AI capabilities

**When NOT to Use**:
- Want to integrate external services like GitHub or Google instead of Notion's AI infrastructure
- Prefer local development and debugging without implementing OAuth PKCE flow
- Do not need persistent connections to an AI protocol server

**Known Limitations**:
- Requires implementing OAuth 2.0 Authorization Code flow with PKCE — no alternative authentication methods like API keys
- Refresh token errors (invalid_grant, REAUTH_REQUIRED) require user re-authentication and cannot be retried automatically
- Must handle transport fallback logic between Streamable HTTP and SSE manually

### Path 3: Link Cursor to agent

**Best For**: Using Cursor IDE to develop and debug Notion AI agents locally.

**Brief Description**: This workflow assumes local development using Cursor IDE to build and test Notion AI agents. However, the provided documentation excerpts contain no explicit mention of Cursor IDE integration or technical guidance for this setup.

**Key technical facts**:
- (No concrete facts available in source materials)

**When to Use**:
- (No documented wins_when conditions)

**When NOT to Use**:
- Expecting documented integration with Cursor IDE — no such documentation exists in provided excerpts
- Need concrete guidance on local debugging workflows — not covered in available documentation

**Known Limitations**:
- Documentation excerpts do not contain any information about Cursor IDE integration
- No specific technical details about local development workflow with Cursor are provided in the source materials

## FAQ

Q: Which path should I start with?
A: Start with **Develop custom agent tools** if you want a documented, reusable, and automation-friendly way to add AI actions to Notion agents—especially if integrating external services like GitHub or Google.

Q: What if I want to use my own AI model but chose "Develop custom agent tools"?
A: You’ll hit a dead end—you can’t connect custom AI backends via the worker SDK. That path only supports invoking external services, not hosting your own AI logic. Use "Connect to MCP server" instead.

Q: What if I expect Cursor IDE to have built-in Notion AI support but chose "Link Cursor to agent"?
A: You’ll find no official documentation or technical guidance for this integration in Notion’s current materials. You may need to reverse-engineer or fall back to one of the other two paths.

Q: Can I avoid OAuth entirely when building a Notion AI integration?
A: No—all documented paths require OAuth: either standard OAuth 2.0 with client credentials (`ntn workers oauth start`) or OAuth 2.0 with PKCE for the MCP server. API keys or simple tokens are not supported.

Q: Does "Connect to MCP server" work with Python or other runtimes?
A: The fact card only confirms support for **Node.js 18+**. Other runtimes are not documented—see the detail skill for possible community implementations.

Q: Are there costs associated with these integrations?
A: Both documented paths are **free**—no usage fees for OAuth integration or MCP server access. Costs would only arise from your own infrastructure (e.g., hosting your AI backend).

Q: Can I reuse a custom agent tool across multiple Notion workspaces?
A: Yes—worker deployments are designed for reuse, and OAuth configurations can be replicated across workspaces using `ntn workers env set` and `ntn workers deploy`.

### [Create database](https://company-skill.com/p/notion/notion-create-database.md)

## What You Want to Do

You want to create a new Notion database with a defined structure (properties like text, select, relation, etc.) and optionally configure views or integrate it into an automated workflow. This includes both one-time manual setups and programmatic creation for external systems.

**Typical User Questions**:
- How to create a database using Notion API?
- How to define a database schema in Notion?

## Decision Tree

Pick the best path for your situation:

- **If** you need to automate database creation or integrate with external systems using code → Use **Create via API** (go to *notion/notion-database*)
- **If** you're setting up a one-off database manually in the Notion app with immediate visual feedback → Use **Define schema visually** (go to *notion/notion-database*)
- **If** you require webhook event handling for database changes (e.g., created, schema updated) → Use **Create via API**
- **Otherwise (default)** → **Define schema visually**, as it’s faster for simple, non-automated use cases and requires no coding or API setup.

## Path Comparison

| Path | Best For | Complexity | Code Required | Automation | Key Fact | Detail Skill |
|------|----------|------------|---------------|------------|----------|-------------|
| Create via API | Automated or programmatic database creation with full control over schema and properties. | medium | Yes | Yes | Requires `Notion-Version: 2026-03-11` header and Bearer token auth | `notion/api/notion-database` |
| Define schema visually | Interactive setup using Notion's UI schema builder without code. | low | No | No | Uses `/database` slash command and **Properties button** to add fields like **Select property** or **Relation property** | `notion/guide/notion-database` |

## Path Details

### Path 1: Create via API

**Best For**: Automated or programmatic database creation with full control over schema and properties.

**Brief Description**: The Notion Database Management API is a RESTful service that lets you create, update, and query databases via HTTP requests. You must include the `Notion-Version` header and authenticate with a Bearer token. Use the `@notionhq/client` SDK or raw HTTP calls to define properties like **Rollup property** or **Multi-select property** programmatically.

**Key technical facts**:
- Auth method: Header: Authorization: Bearer <token>, where <token> is your auth token.
- Prerequisites: Notion Integration Token, Integration shared with target database, Notion-Version: 2026-03-11 header for all requests, @notionhq/client SDK (JavaScript/TypeScript) or direct HTTP calls

**When to Use**:
- Need automated or programmatic database creation with full control over schema and properties
- Building integrations that synchronize external data with Notion
- Requiring webhook event handling for database changes (created, deleted, schema updated)
- Need to manage large datasets with pagination (up to 10,000 results per query)

**When NOT to Use**:
- User prefers visual interface without writing code
- Simple one-time database setup without automation needs
- No access to Notion Integration Token or API permissions
- Need immediate visual feedback during schema design

**Known Limitations**:
- Requires sharing integration with specific database to access it (403 error otherwise)
- Maximum schema size limit of 50KB for database properties
- Rate limits of 100 requests per minute per API key
- Property type conversions may not be supported after creation (e.g., formula to select)
- Database ID must be 32 characters alphanumeric string or UUID format depending on context

### Path 2: Define schema visually

**Best For**: Interactive setup using Notion's UI schema builder without code.

**Brief Description**: Use Notion’s web interface to create databases via the `/database` slash command or "+ New page" flow. Configure structure using the **Properties button**, then click **+ Add a property** to define fields like **Select property**, **Multi-select property**, **Relation property**, or **Rollup property**. Every new database starts with an **Untitled title** that you can rename.

**Key technical facts**:
- Prerequisites: Active Notion account, Edit permissions in the target workspace

**When to Use**:
- Interactive setup using Notion's UI schema builder without code
- Simple one-time database creation with immediate visual feedback
- User has edit permissions but no API integration access
- Designing database structure through trial-and-error with real-time preview

**When NOT to Use**:
- Need automated or programmatic database creation
- Building external integrations that sync data with Notion
- Require webhook notifications for database changes
- Managing large-scale deployments across multiple workspaces

**Known Limitations**:
- Cannot change property type after creation without deleting and recreating (data loss risk)
- No support for programmatic automation or scripting
- Limited to databases within the same workspace for Relation properties
- Performance may degrade with very large schemas (50+ properties)
- No webhook event handling or external integration capabilities

## FAQ

Q: Which path should I start with?
A: Start with **Define schema visually** if you’re creating a single database for personal or team use and don’t need automation. Use **Create via API** only if you’re building an integration or need to create databases programmatically.

Q: What if I need to change a **Select property** to a **Relation property** after creating the database using the visual method?
A: You’ll hit a limitation: property types cannot be changed after creation without deleting the property (and losing data). The API also restricts some type conversions (e.g., formula to select), so plan your schema carefully in either path.

Q: What if I exceed the **rate limits** of 100 requests per minute but chose the API path?
A: Your API calls will be throttled, returning 429 errors. You’ll need to implement retry logic with backoff or reduce request frequency—this doesn’t apply to the visual path since it has no rate limits.

Q: Can I use **Relation property** across workspaces when defining schema visually?
A: No—you’re limited to databases within the same workspace. The API also enforces this restriction, so cross-workspace relations aren’t supported in either path.

Q: What happens if I forget to include the **Notion-Version header** when using the API?
A: Your request will fail, likely with a 400 error. The header `Notion-Version: 2026-03-11` is mandatory for all API calls, as noted in prerequisites.

Q: Does the visual path support **Rollup property** configuration?
A: Yes—you can add a **Rollup property** via **+ Add a property** in the UI, just like **Select property** or **Multi-select property**. However, complex rollup formulas may be harder to debug without API-level logging.

Q: 如果我需要自动化但选择了“Define schema visually”，会怎样？
A: 你将无法实现自动化创建或同步外部数据，因为该路径不支持程序化操作或脚本。

Q: 如果我没有 Notion Integration Token 但选择了“Create via API”，会怎样？
A: 你会收到 403 错误，因为 API 路径要求集成已共享到目标数据库，否则无法访问。

### [Upload notion](https://company-skill.com/p/notion/notion-upload-notion.md)

## What You Want to Do

You want to add a file (e.g., PDF, image, video, document) to a Notion page so others can view or download it. The file may be local on your machine, already hosted online, or part of an automated workflow.

**Typical User Questions**:
- How to upload a file using Notion API?
- How to attach a file to a Notion page via CLI?

## Decision Tree

Pick the best path for your situation:

- **If** you need to upload files larger than 100 MB (up to 5 GB) or require **multipart upload** → Use Upload via API (go to *notion/notion-file*)
- **If** you're working in a terminal and want to use commands like `ntn files create` with `--external-url` or `stdin` → Use Upload via CLI (go to *notion/notion-workspace*)
- **If** you're manually adding a file while editing a page using **drag-and-drop**, **file picker**, or **Upload file button** in the **Files & Media** section → Use Upload through UI (go to *notion/notion-file*)
- **Otherwise (default)** → Use **Upload through UI** if you’re a non-technical user doing one-time uploads; otherwise, prefer **Upload via API** for flexibility and automation.

## Path Comparison

| Path | Best For | Complexity | Code Required | Automation | Key Fact | Detail Skill |
|------|----------|------------|---------------|------------|----------|-------------|
| Upload via API | Programmatic file uploads, including large files or batch operations. | medium | Yes | Yes | Supports **multipart upload** for files up to 5 GB | `notion/api/notion-file` |
| Upload through UI | One-time manual uploads directly in the Notion app. | low | No | No | File size limited to **5 MiB** (free) or **5 GiB** (paid) per **individual files** | `notion/guide/notion-file` |
| Upload via CLI | Local scripting, testing, or CI/CD workflows using command line. | low | Yes | Yes | Uses **OAuth** with credentials stored in **system keychain**; supports `--external-url` and `stdin` | `notion/cli/notion-workspace` |

## Path Details

### Path 1: Upload via API

**Best For**: Programmatic file uploads, including large files or batch operations.

**Brief Description**: Uses the Notion Data API with REST endpoints like `POST /v1/file_uploads` to handle small files directly or large files via **multipart upload**. Requires the `@notionhq/client` SDK (v2.0.0+) and supports uploading from external URLs programmatically.

**Key technical facts**:
- Billing: Per-request billing: each API call (create, send, complete, retrieve, list) counts as one request; free tier: 10,000 requests per month
- Max model size: 5 GB for large files using multi-part upload
- Auth method: Bearer Token authentication with Authorization: Bearer <token> header

**When to Use**:
- Need to upload files larger than 100 MB (up to 5 GB)
- Building automated workflows that require programmatic file handling
- Need to import files from external URLs programmatically
- Working with batch operations requiring multiple file uploads
- Integration requires webhook notifications for upload lifecycle events

**When NOT to Use**:
- Performing one-time manual uploads without coding
- User lacks technical ability to implement API calls
- Environment doesn't support required Node.js version or SDK
- Need immediate visual confirmation of upload in Notion UI without additional implementation

**Known Limitations**:
- File upload objects expire after 1 hour if not completed
- Single file size limit: 100 MB for direct uploads (larger files require multi-part upload up to 5 GB)
- Requires code implementation with @notionhq/client SDK version >=2.0.0 for file uploads
- Each part in multi-part upload must be ≤20 MB
- Must call /complete endpoint to finalize every upload even for small files

### Path 2: Upload through UI

**Best For**: One-time manual uploads directly in the Notion app.

**Brief Description**: Uses Notion’s web interface via the **Files & Media** section, where you can use **drag-and-drop**, the **file picker**, or the **Upload file button** to add **individual files**. Requires appropriate **workspace permissions** and that **file management enabled** in your workspace.

**Key technical facts**:
- Billing: File storage and upload capabilities tied to Notion workspace subscription tier, not billed per request
- Max model size: 5 GiB per file for paid workspaces, 5 MiB per file for free workspaces
- Prerequisites: Notion workspace with file management enabled, Edit or owner permissions

**When to Use**:
- Performing one-time manual uploads without coding
- User prefers visual interface over command line or API
- Uploading standard file types within size limits
- Need immediate visual confirmation of successful upload
- No development environment available

**When NOT to Use**:
- Need to upload files larger than workspace quota allows
- Require automation or batch processing of multiple files
- Working in environments without browser access
- Need to integrate file uploads into existing application workflows
- Require programmatic error handling or status tracking

**Known Limitations**:
- Only supports uploading **individual files**, not folders
- File size limited to **5 MiB** for free workspaces and **5 GiB** for paid workspaces
- No programmatic or automated upload capability
- Only **common media types** supported (e.g., JPG, PNG, PDF, MP4, MP3)
- **Files & Media** section only visible in workspaces where **file management enabled**

### Path 3: Upload via CLI

**Best For**: Local scripting, testing, or CI/CD workflows using command line.

**Brief Description**: Uses the Notion CLI (`ntn`) with commands like `ntn files create`, which accepts file content via `stdin` or public URLs using the `--external-url` flag. Authentication uses **OAuth** with tokens securely stored in the **system keychain** (macOS Keychain, Windows Credential Vault, or Linux libsecret).

**Key technical facts**:
- Billing: No explicit quotas or rate limits; CLI is free to use with no billing or metering
- Auth method: OAuth login with credentials stored in system keychain
- Prerequisites: Installed Notion CLI (via `curl -fsSL https://ntn.dev`), authenticated via `ntn login`

**When to Use**:
- Working in terminal environments without GUI access
- Need to script file uploads in CI/CD workflows
- Prefer command-line tools over writing custom code
- Have files already available via public URLs
- Want secure authentication without managing API tokens manually

**When NOT to Use**:
- Working with very large local files that can't be easily piped through `stdin`
- Environment doesn't support CLI installation
- Need fine-grained control over upload parameters available in direct API
- Require webhook notifications for upload completion
- Working in restricted environments without terminal access

**Known Limitations**:
- For very large files, using `--external-url` with pre-uploaded public asset is recommended to avoid timeout or memory issues
- No documented support for multi-part uploads of large local files
- Requires CLI installation and terminal access
- Limited parameter options compared to direct API usage
- File content must be provided via `stdin` or external URL (no direct file path parameter)

## FAQ

Q: Which path should I start with?
A: If you're a regular user adding a document or image while editing, start with **Upload through UI**. If you're a developer or automating uploads, start with **Upload via API**.

Q: What if I need to upload a 2 GB video file but used the UI in a free workspace?
A: You’ll hit the **5 MiB** file size limit and the upload will fail. Free workspaces cannot upload files larger than 5 MiB via UI.

Q: What if I try to upload a 3 GB local file using the CLI without piping it through `stdin`?
A: The CLI has no direct file path option and no **multipart upload** support, so you’ll likely encounter memory issues or timeouts. Use `--external-url` with a pre-hosted file or switch to the API.

Q: Can I use the CLI without installing anything?
A: No — you must install the CLI first using `curl -fsSL https://ntn.dev` or npm, and authenticate via `ntn login` to store credentials in the **system keychain**.

Q: Why does the API require calling `/complete` even for small files?
A: All uploads—small or large—must be finalized with a `/complete` call to ensure data integrity and prevent orphaned upload objects that expire after 1 hour.

Q: Are all file types supported in the UI?
A: No — only **common media types** like JPG, PNG, PDF, MP4, and MP3 are supported. Executables or obscure formats may be blocked.

Q: Does the CLI support listing uploaded files?
A: Yes — use `ntn files list` to view files associated with your authenticated workspace.


## Frequently asked questions

### How do I set up authentication for a Notion integration?

You can set up authentication for a Notion integration by configuring OAuth, personal access tokens, or CLI credentials. The platform supports managing API tokens, OAuth, and webhooks, while API requests require a Bearer token in the Authorization header.

### How do I build a Notion integration with AI capabilities?

You can build a Notion integration with AI capabilities by connecting AI tools, agents, or MCP servers. This is supported through integration development guides and API endpoints for linking AI models and MCP clients.

### How do I create and manage a Notion database?

You can create and manage a Notion database by defining its schema and managing data programmatically or via the user interface. The platform offers both API and UI builder paths to create, query, update, and design database schemas and views.

### How do I upload and attach files to Notion pages?

You can upload and attach files to Notion pages using the API, CLI, or the Notion interface. File management capabilities allow you to upload, retrieve, and manage attachments through either programmatic requests or the UI.

## Cross-product integrations

- [AI Agent Manages Notion CMS for Vercel Site](https://company-skill.com/p/_combos/ai-agent-manages-notion-cms-for-vercel-site-e41629.md) (vercel + alinux + cloudflare + bailian)
- [AI Agent with Notion via MCP](https://company-skill.com/p/_combos/ai-agent-with-notion-via-mcp-84aab0.md) (bailian)
- [AI Content Engine with Public Site and Enterprise Search](https://company-skill.com/p/_combos/ai-content-engine-with-public-site-and-enterpris-9db7c8.md) (alinux + cloudflare + bailian + vercel + idaas)
- [AI Content Platform on Managed Infrastructure](https://company-skill.com/p/_combos/ai-content-platform-on-managed-infrastructure-265158.md) (alinux + cloudflare + bailian + vercel + idaas)
- [AI Content Platform with Search and Frontend](https://company-skill.com/p/_combos/ai-content-platform-with-search-and-frontend-d3ca31.md) (alinux + cloudflare + bailian + vercel + idaas)
- [AI Content Platform with Site and Search](https://company-skill.com/p/_combos/ai-content-platform-with-site-and-search-7bf25b.md) (alinux + cloudflare + bailian + vercel + idaas)
- [AI-Driven Search Knowledge Platform](https://company-skill.com/p/_combos/ai-driven-search-knowledge-platform-803ad0.md) (alinux + cloudflare + bailian + vercel + idaas)
- [AI Notion Bot with Team Notifications](https://company-skill.com/p/_combos/ai-notion-bot-with-team-notifications-362bbb.md) (eb)

## Use with an AI agent

```bash
curl -s https://company-skill.com/api/route \
  -H 'Content-Type: application/json' \
  -d '{"query": "...", "product": "notion"}'
```

MCP server: https://company-skill.com/api/mcp/notion.py

---
Machine-readable: https://company-skill.com/llms.txt · https://company-skill.com/sitemap.xml