# Source: https://developers.notion.com/guides/get-started/getting-started.md

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

# Notion API Overview

> Discover how to leverage Notion's Public API to build integrations.

## Using Notion's Public API for Integrations

A Notion workspace is a collaborative environment where teams can organize work, manage projects, and store information in a highly customizable way. Notion's REST API facilitates direct interactions with workspace elements through programming. Key functionalities include:

<CardGroup cols={2}>
  <Card title="Pages" icon="file-lines" href="/guides/data-apis/working-with-page-content" horizontal color="#0076d7">
    Create, update, and retrieve page content.
  </Card>

  <Card title="Databases" icon="database" href="/guides/data-apis/working-with-databases" horizontal color="#0076d7">
    Manage database, properties, entries, and schemas.
  </Card>

  <Card title="Data Sources" icon="database" href="/reference/create-a-data-source" horizontal color="#0076d7">
    Manage data sources, properties, entries, and schemas.
  </Card>

  <Card title="Users" icon="users" href="/reference/user" horizontal color="#0076d7">
    Access user profiles and permissions.
  </Card>

  <Card title="Comments" icon="comment-dots" href="/guides/data-apis/working-with-comments" horizontal color="#0076d7">
    Handle page and inline comments.
  </Card>

  <Card title="Content Queries" icon="magnifying-glass" href="/reference/post-search" horizontal color="#0076d7">
    Search through workspace content.
  </Card>

  <Card title="Authentication" icon="key" href="/guides/get-started/authorization" horizontal color="#0076d7">
    Secure integrations with OAuth 2.0.
  </Card>

  <Card title="Link Previews" icon="link" href="/guides/link-previews/link-previews" horizontal color="#0076d7">
    Customize how links appear when shared.
  </Card>
</CardGroup>

To make interactions within Notion workspaces programmatically, you must associate these actions with a Notion user. Notion facilitates this by allowing API requests to be linked to a "bot" user.

Developers create integrations to define a bot's capabilities, including authenticating API requests, deciding when to make requests, and setting the bot's read/write permissions. Essentially, using Notion's Public API involves creating an integration that outlines how a bot interacts with your workspace and assigns REST API requests to the bot.

There are two primary integration types:

* [**Internal**](#internal-vs-public-integrations): For private workspace workflows and automations.
* [**Public**](#internal-vs-public-integrations): For broader, shareable functionalities, including [Link Previews](/guides/link-previews/link-previews).

For further details on integration possibilities and API specifics, proceed with the guide or consult the [API reference](/reference/intro). Check out our [demos](/page/examples) for practical examples.

## What is a Notion Integration?

A Notion integration, sometimes referred as a [connection](https://www.notion.so/help/add-and-manage-connections-with-the-api), enables developers to programmatically interact with Notion workspaces. These integrations facilitate linking Notion workspace data with other applications or the automation of workflows within Notion.

Integrations are installed in Notion workspaces and require **explicit permission** from users to access Notion pages and databases.

<Frame caption="Create Notion integrations that unlock new possibilities for teams.">
  <img src="https://mintcdn.com/notion-demo/LHm9qfrJYJOPRxs6/images/docs/0f06356-notion_overview.jpg?fit=max&auto=format&n=LHm9qfrJYJOPRxs6&q=85&s=ab31886c0c84514c8db8a2801d4fffe4" data-og-width="1800" width="1800" data-og-height="1200" height="1200" data-path="images/docs/0f06356-notion_overview.jpg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/notion-demo/LHm9qfrJYJOPRxs6/images/docs/0f06356-notion_overview.jpg?w=280&fit=max&auto=format&n=LHm9qfrJYJOPRxs6&q=85&s=21d5d398c973d82465297615cad6b879 280w, https://mintcdn.com/notion-demo/LHm9qfrJYJOPRxs6/images/docs/0f06356-notion_overview.jpg?w=560&fit=max&auto=format&n=LHm9qfrJYJOPRxs6&q=85&s=af5a2264b86ae5ffadb0ea53ada3cdfd 560w, https://mintcdn.com/notion-demo/LHm9qfrJYJOPRxs6/images/docs/0f06356-notion_overview.jpg?w=840&fit=max&auto=format&n=LHm9qfrJYJOPRxs6&q=85&s=c048e5f1db362ebf127263571cc7f41f 840w, https://mintcdn.com/notion-demo/LHm9qfrJYJOPRxs6/images/docs/0f06356-notion_overview.jpg?w=1100&fit=max&auto=format&n=LHm9qfrJYJOPRxs6&q=85&s=ffe19676cb29949f0f5eed1bc218a447 1100w, https://mintcdn.com/notion-demo/LHm9qfrJYJOPRxs6/images/docs/0f06356-notion_overview.jpg?w=1650&fit=max&auto=format&n=LHm9qfrJYJOPRxs6&q=85&s=945c38c6e6cd30861ab3ab94a9721e2c 1650w, https://mintcdn.com/notion-demo/LHm9qfrJYJOPRxs6/images/docs/0f06356-notion_overview.jpg?w=2500&fit=max&auto=format&n=LHm9qfrJYJOPRxs6&q=85&s=c06a22ed64ca97f2a5cd442c5edbefc8 2500w" />
</Frame>

Notion users have access to a vast [library](https://www.notion.so/integrations/all) of existing integrations to enrich their experience further. For developers interested in creating custom solutions, Notion supports the development of both internal and public integrations. Both utilize the Notion API for workspace interactions.

Let's explore internal and public integrations.

## Internal vs. Public Integrations

Notion integrations come in two types: Internal and Public. Understanding the differences between them helps in choosing the right approach for your development needs.

* **Internal Integrations** are exclusive to a single workspace, accessible only to its members. They are ideal for custom workspace automations and workflows.
* **Public Integrations** are designed for a wider audience, usable across any Notion workspace. They cater to broad use cases and follow the OAuth 2.0 protocol for workspace access.

<Warning>
  Public integrations must undergo a Notion security review before publishing.
</Warning>

### Key Differences

| Feature              | Internal Integrations                                                                               | Public Integrations                                                                                             |
| :------------------- | :-------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| Scope                | Confined to a single, specific workspace.                                                           | Available across multiple, unrelated workspaces.                                                                |
| User Access          | Only accessible by members of the workspace where it's installed.                                   | Accessible by any Notion user, regardless of their workspace.                                                   |
| Creation             | Created by Workspace Owners within the integration dashboard.                                       | Created by Workspace Owners within the integration dashboard.                                                   |
| Permissions          | Workspace members explicitly grant access to their pages or databases via Notion’s UI.              | Users authorize access to their pages during the OAuth flow, or by sharing pages directly with the integration. |
| OAuth Protocol       | Not applicable, as access is limited to a single workspace.                                         | Uses the OAuth 2.0 protocol to securely access information across multiple workspaces.                          |
| Dashboard Visibility | Visible to Workspace Owners in the integration dashboard, including integrations created by others. | -                                                                                                               |

## What You Can Build: Integration Use Cases

Notion’s REST API opens up a world of possibilities for integrations, ranging from enhancing internal workflow to creating public-facing applications. Here’s a closer look at some of the innovative integrations developers have built with Notion:

### Data Integrations

Data integrations leverage the Notion API to automate data flow between Notion and other systems.

* **Automated Notifications:** Develop integrations that monitor Notion databases for changes. Upon detecting a change, these integrations can automatically send notifications various communication channels.
* **Github Synchronization**: Create integrations that keep Notion issues in sync with GitHub issues.
* **External Data Import:** Build integrations that import data from external sources directly into Notion databases. This can include importing customer data, project updates, or any other relevant information.

<Card title="Examples:" icon="link" color="#0076d7">
  <CardGroup cols={2}>
    <Card title="Create an integration" icon="link" href="/guides/get-started/create-a-notion-integration" horizontal color="#0076d7" />

    <Card title="Working with comments" icon="comment-dots" href="/guides/data-apis/working-with-comments" horizontal color="#0076d7" />

    <Card title="Working with databases" icon="database" href="/guides/data-apis/working-with-databases" horizontal color="#0076d7" />

    <Card title="Working with files and media" icon="file-image" href="/guides/data-apis/working-with-files-and-media" horizontal color="#0076d7" />

    <Card title="Working with page content" icon="file-lines" href="/guides/data-apis/working-with-page-content" horizontal color="#0076d7" />
  </CardGroup>
</Card>

### Link Preview Integrations

Enhance the sharing experience within Notion with Link preview integrations, offering a glimpse into the content of shared links:

<Frame caption="Link Preview of a GitHub PR.">
  <img src="https://mintcdn.com/notion-demo/LHm9qfrJYJOPRxs6/images/docs/ce5daa3-Screen_Shot_2023-06-27_at_3.48.22_PM.png?fit=max&auto=format&n=LHm9qfrJYJOPRxs6&q=85&s=9e77dea080a3e4d82012927d3107600e" data-og-width="1440" width="1440" data-og-height="124" height="124" data-path="images/docs/ce5daa3-Screen_Shot_2023-06-27_at_3.48.22_PM.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/notion-demo/LHm9qfrJYJOPRxs6/images/docs/ce5daa3-Screen_Shot_2023-06-27_at_3.48.22_PM.png?w=280&fit=max&auto=format&n=LHm9qfrJYJOPRxs6&q=85&s=95e2b735fcfdd727e8b4dd903892cd34 280w, https://mintcdn.com/notion-demo/LHm9qfrJYJOPRxs6/images/docs/ce5daa3-Screen_Shot_2023-06-27_at_3.48.22_PM.png?w=560&fit=max&auto=format&n=LHm9qfrJYJOPRxs6&q=85&s=3ae39ad94cb6a30f63dfc37655445110 560w, https://mintcdn.com/notion-demo/LHm9qfrJYJOPRxs6/images/docs/ce5daa3-Screen_Shot_2023-06-27_at_3.48.22_PM.png?w=840&fit=max&auto=format&n=LHm9qfrJYJOPRxs6&q=85&s=014cb460ea5da84367d2012eb0c80fc3 840w, https://mintcdn.com/notion-demo/LHm9qfrJYJOPRxs6/images/docs/ce5daa3-Screen_Shot_2023-06-27_at_3.48.22_PM.png?w=1100&fit=max&auto=format&n=LHm9qfrJYJOPRxs6&q=85&s=0122dc9d4f5afb2ec865995f733b8a2c 1100w, https://mintcdn.com/notion-demo/LHm9qfrJYJOPRxs6/images/docs/ce5daa3-Screen_Shot_2023-06-27_at_3.48.22_PM.png?w=1650&fit=max&auto=format&n=LHm9qfrJYJOPRxs6&q=85&s=3fe858238b79cab19aa44a898377e510 1650w, https://mintcdn.com/notion-demo/LHm9qfrJYJOPRxs6/images/docs/ce5daa3-Screen_Shot_2023-06-27_at_3.48.22_PM.png?w=2500&fit=max&auto=format&n=LHm9qfrJYJOPRxs6&q=85&s=b25033a6958a4ed0623146ab6e5cd512 2500w" />
</Frame>

Create integrations that allow for the customization of how shared links are presented in Notion, providing context and enhancing engagement.

<Warning>
  Link Preview Integrations differ from public integrations. Review the [Link Preview guide](/guides/link-previews/build-a-link-preview-integration).
</Warning>

<Danger>
  To build a Link Preview integration, developers must first apply for access to the feature through the [Notion Link Preview API request form](https://notionup.typeform.com/to/BXheLK4Z?typeform-source=developers.notion.com).

  Link Preview integrations published for distribution require a review from Notion's platform and security teams.
</Danger>

<Card title="Quick Links" icon="link" color="#0076d7">
  <CardGroup cols={2}>
    <Card title="Introduction to Link Preview integrations" icon="link" href="/guides/link-previews/link-previews" horizontal color="#0076d7" />

    <Card title="Build a Link Preview integration" icon="paintbrush" href="/guides/link-previews/build-a-link-preview-integration" horizontal color="#0076d7" />

    <Card title="API reference docs for the Link Preview unfurl attribute object" icon="code-simple" href="/reference/unfurl-attribute-object" horizontal color="#0076d7" />

    <Card title="Help Centre" icon="circle-info" href="https://www.notion.so/help/guides/notion-api-link-previews-feature" horizontal color="#0076d7" />
  </CardGroup>
</Card>

### Identity Management Integrations (Enterprise Plans ONLY)

For enterprise-level workspaces, Notion offers advanced identity management capabilities:

* **SCIM API for User and Group Management**: Utilize the SCIM API to automate the provisioning and management of users and groups within enterprise workspaces, streamlining administrative tasks.
* **SAML SSO for Enhanced Security**: Implement Single Sign-On (SSO) using SAML for a secure and convenient authentication process, simplifying access for users across the enterprise.

<Card title="Quick Links" icon="link" color="#0076d7">
  <CardGroup cols={2}>
    <Card title="Provision users and groups with SCIM" icon="angles-right" href="https://www.notion.so/help/provision-users-and-groups-with-scim" horizontal color="#0076d7" />

    <Card title="SAML SSO configuration" icon="angles-right" href="https://www.notion.so/help/saml-sso-configuration" horizontal color="#0076d7" />
  </CardGroup>
</Card>

## Starting Your Integration Journey

Embarking on building an integration with Notion? Begin with our foundational [*Build your first integration guide*](/guides/get-started/create-a-notion-integration). As you become more familiar with the basics, expand your knowledge and skills with in-depth guides on [Authorization](/guides/get-started/authorization), [Page content](/guides/data-apis/working-with-page-content), and [Databases](/guides/data-apis/working-with-databases).

## Key resources

* [Notion SDK for JavaScript](https://github.com/makenotion/notion-sdk-js): Leverage our SDK designed for JavaScript environments to simplify interactions with the REST API, making development more efficient.
* [Technology Partner Program](https://www.notion.so/technology-partner-program): Have you developed a public integrations? Join our Technology Partner Program for access to dedicated support, exclusive distribution channels, and marketing opportunities.

Explore these resources and join the [Notion Devs Slack community](https://join.slack.com/t/notiondevs/shared_invite/zt-20b5996xv-DzJdLiympy6jP0GGzu3AMg) to share your projects, gain insights from fellow developers, and discover new ways to enhance Notion with integrations.

<Card title="Quick Links" icon="link" color="#0076d7">
  <CardGroup cols={2}>
    <Card title="API reference documentation" icon="code-simple" href="/reference/intro" horizontal color="#0076d7" />

    <Card title="Notion SDK for JavaScript" icon="js" href="https://github.com/makenotion/notion-sdk-js" horizontal color="#0076d7" />

    <Card title="Postman collection" icon="box" href="https://www.postman.com/notionhq/" horizontal color="#0076d7" />

    <Card title="TypeScript starter template" icon="code" href="https://github.com/makenotion/notion-sdk-typescript-starter" horizontal color="#0076d7" />

    <Card title="FAQs" icon="circle-question" href="/page/frequently-asked-questions" horizontal color="#0076d7" />

    <Card title="Notion Devs Slack community" icon="slack" href="https://join.slack.com/t/notiondevs/shared_invite/zt-20b5996xv-DzJdLiympy6jP0GGzu3AMg" horizontal color="#0076d7" />
  </CardGroup>
</Card>