developers.notion.com Open in urlscan Pro
2606:4700::6810:f176  Public Scan

Form analysis
0 forms found in the DOM

Text Content

Jump to Content

HomeGuidesAPI ReferenceChangelogExamples

--------------------------------------------------------------------------------

View my integrations
Guides
View my integrations

HomeGuidesAPI ReferenceChangelogExamples
Search
CTRL-K
Get startedIntroduction to Notion’s APIBuild your first
integrationAuthorizationData APIsWorking with page contentWorking with
databasesWorking with commentsWorking with files and mediaLink
previewsIntroductionBuild a Link Preview integrationResourcesExample codePostman
workspace
All
Guides
Reference
Pages

START TYPING TO SEARCH…


GET STARTED

 * Introduction to Notion’s API
 * Build your first integration
 * Authorization


DATA APIS

 * Working with page content
 * Working with databases
 * Working with comments
 * Working with files and media


LINK PREVIEWS

 * Introduction
 * Build a Link Preview integration


RESOURCES

 * Example code
 * Postman workspace


INTRODUCTION TO NOTION’S API

Learn about Notion’s public API and building integrations.

Suggest Edits

USING NOTION’S PUBLIC API TO BUILD INTEGRATIONS

Developers can use Notion’s public REST API to interact with Notion workspaces
programmatically. Interactions include working with:

 * Pages
 * Databases
 * Users
 * Page and inline comments
 * Querying workspace content
 * Authenticating integrations
 * Customizing unfurled links

All workspace interactions, such as the above, need to be attributed to a Notion
user. To accommodate this requirement for interactions made programmatically,
Notion allows for API requests to be attributed to a "bot". To define the
capabilities of a bot, developers build integrations, which handle
authenticating API requests for the bot, defining when requests should be made,
and the read/write capabilities of the integration.

In other words, using Notion’s public API means building an integration — the
blueprint for how a bot can interact with your workspace — and attributing the
REST API requests that are made to the bot.

There are two main types of integrations:

 * Internal
 * Public, which include Link Previews

Keep reading to learn more about types of integrations and some example ideas of
what developers can build. Alternatively, jump to the API reference
documentation to learn more about available endpoints, or see our collection of
integration demos for sample code.


WHAT IS A NOTION INTEGRATION?

A Notion integration (sometimes referred to as a "connection") allows developers
to interact with Notion workspaces programmatically. This allows developers to
connect their Notion workspace data to other tools or automate workflows within
Notion.

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

You can build Notion integrations that help collaborators expand what they can
do with Notion

There is a large library of existing integrations available to Notion users to
improve their Notion experiences. For developers looking to build their own
integration, they can create either public or internal integrations, both of
which rely on the REST API to interact with workspaces.

Let’s look deeper at what these two types of integrations are and how they
differ.


INTERNAL VS. PUBLIC INTEGRATIONS


INTERNAL INTEGRATIONS

An internal integration is tied to a single, specific workspace. Only members
within the workspace can use the integration. They are created by Workspace
Owners through the integration dashboard.

> 📘
> 
> By default, all integrations start out as internal integrations.
> 
> 
> 
> You can set an integration to public from the integration’s settings page.

Once an internal integration has been added to a workspace, members must give
the integration permission to access specific pages or databases through
Notion’s UI.

In order to add an internal integration to the workspace, a Notion member needs
to be a Workspace Owner. If you don’t have admin access to the target workspace,
then you can always develop the integration in a personal workspace, and later
ask a Workspace Owner for assistance.

> 📘
> 
> Workspace Owners can see all integrations created in the integration dashboard
> — both ones they and others have created.

To learn more about internal integrations, read our Create an integration and
Authorization guides.


PUBLIC INTEGRATIONS

Public integrations are built for a broad audience. Any Notion user in any
workspace can use a public integration. This is in contrast to internal
integrations, which are built for a specific workspace.

By default, all integrations start out as internal integrations and can be made
public via the integration’s settings page.

Public integrations follow the OAuth 2.0 protocol to access multiple workspaces.
To share pages with public integrations, users either select pages from the page
picker interface during the authorization flow, or they can share individual
pages from the workspace.

This is explained in more detail in our Authorization guide.

> 📘
> 
> Add a template to an integration
> 
> 
> 
> When you create a public integration, you can provide a URL to a Notion page
> that a user can opt to duplicate in their workspace during the OAuth flow.
> Learn more about using templates in the Authorization guide.


WHAT YOU CAN BUILD: INTEGRATION USE CASES

"Integrations" is a broad term in terms of what can be built with Notion’s REST
API. Let’s look at some examples of different types of internal and public
integrations that have been built with Notion.

For code examples, see the Notion SDK for JavaScript's examples directory.


DATA INTEGRATIONS

You can use the Notion API to build an integration that sends data to and/or
from Notion. For example, you can poll for changes to a Notion database to send
automated emails, sync Notion with Github issues, or import data from an
external source to a Notion database.

> 👍
> 
> Related resources
> 
> 
> 
>  * Create an integration
>  * Working with comments
>  * Working with databases
>  * Working with files and media
>  * Working with page content


LINK PREVIEW INTEGRATIONS

Link Preview integrations are a type of public integration that handle how links
unfurl. With a Link Preview integration, you can share an excerpt of content in
Notion when an authenticated collaborator shares a supported link.

Link Preview of a GitHub PR

In other words, developers can build Link Preview integrations to allow links
with a domain they own to unfurl in a customizable format. Since Link Preview
integrations use OAuth 2.0, the main benefit of Link Preview integrations is
being able to display information that requires users to be authenticated to
view.

Note: Authorizing Link Preview integrations differs from other public
integrations. Use the Link Preview guide to set up authorization.

> 👍
> 
> Related resources
> 
> 
> 
>  * Introduction to Link Preview integrations guide
>  * Build a Link Preview integration guide
>  * API reference docs for the Link Preview unfurl attribute object
>  * Help Centre guide

> 🚧
> 
> To build a Link Preview integration, developers must first apply for access to
> the feature through the Notion Link Preview API request form.
> 
> Additionally, all Link Preview integrations published for distribution require
> a review from Notion's platform and security teams.


IDENTITY MANAGEMENT INTEGRATIONS

Workspaces on Notion’s enterprise plan are granted access to a SCIM API. SSO
using SAML can also be configured for enterprise workspaces.

> 👍
> 
> Related resources
> 
> 
> 
>  * Provision users and groups with SCIM
>  * SAML SSO configuration

--------------------------------------------------------------------------------

These examples represent just a few ideas. Join our Notion Devs Slack community
to share your own ideas, and learn from other developers building with Notion.


GETTING STARTED

If you’re new to Notion’s public REST API and integrations, we recommend
starting with the:

 * Create an integration guide

Once you have a good idea of how to create an integration, continue learning
with the following guides:

 * Authorization
 * Working with page content
 * Working with databases

See our API reference docs for a list of available endpoints, a more in-depth
description of each type of object used in Notion, and ensuring your
integrations have the correct capabilities.

> 👍
> 
> Notion SDK for JavaScript
> 
> 
> 
> Notion has built an SDK for integrations built in a JavaScript environment to
> simplify interacting the with REST API. We typically recommend JavaScript
> developers use this SDK.


KEY RESOURCES

> 📘
> 
> Technology Partner Program
> 
> 
> 
> If you’ve already built a public integration using our Public API or the Link
> Previews API, you may be eligible to become a technology partner and receive
> dedicated support from Notion, as well as access to exclusive distribution and
> marketing opportunities.
> See our Technology Partner Program page to learn more.

 * API reference documentation
 * Notion SDK for JavaScript
 * Postman collection
 * TypeScript starter template
 * FAQs
 * Notion Devs Slack community

Updated about 2 months ago

--------------------------------------------------------------------------------

Build your first integration
Did this page help you?
Yes
No
 * Table of Contents
 * * Using Notion’s public API to build integrations
   * What is a Notion integration?
   * Internal vs. public integrations
     * Internal integrations
     * Public integrations
   * What you can build: Integration use cases
     * Data integrations
     * Link Preview integrations
     * Identity management integrations
   * Getting started
     * Key resources










The all-in-one workspace for your notes, tasks, wikis, and databases.
©2022 Notion Labs, Inc.
Terms & Privacy

DEVELOPERS

Guides API reference My integrations Developer terms

NOTION

Product Teams Enterprise Blog Careers

COMMUNITY

Slack Stack Overflow Twitter