Skip to main content

Notion

In this example, we will show you how you can get started working with the Notion API and produce a working use case that allows you to list all of the users in your Notion workspace.

Before you start

You will need to get an API token for a Notion Internal Integration that is valid for the workspace you want to access. Find out how to set that up in the Notion Authorization documentation.

Please ensure that the capabilities for your Notion Internal Integration include the User Capability "Read user information without an email address".

Install & Authorize Superface​

The Superface CLI provides all the tooling needed to author the Comlinks for your integration.

Install with Homebrew
brew install superfaceai/cli/superface

If you don't have a Superface account already, you can sign up here. You can use your account to authenticate the CLI.

superface login

Prepare the documentation​

Notion's documentation is hosted by Readme.io, which is a format that Superface can accept without any additional changes so you can copy and paste the URL for the GET users endpoint.

superface prepare https://developers.notion.com/reference/get-users

Once the documentation has been indexed, you will need to edit the notion.provider.json that has been created to ensure that the correct API endpoint and security policy are used. The exact provider definition you need to use is below:

notion.provider.json
{
  "name": "notion",
  "defaultService": "default",
  "parameters": [],
  "services": [
    {
      "baseUrl": "https://api.notion.com",
      "id": "default"
    }
  ],
  "securitySchemes": [
    {
      "type": "http",
      "scheme": "bearer",
      "id": "bearerAuth"
    }
  ]
}

Define your use case​

superface new notion "list all users"

To turn the Comlink profile into runnable code in either Node.js or Python, use the following command and include the name of the provider and a use case profile you want to work with.

superface map notion notion-workspace/user-listing

Add your API key​

If you don't already have your Notion API key in your environment, you can add it to your .env file as NOTION_TOKEN=<your-notion-api-key>.

Set up your inputs​

In order to list the users correctly, you will need to modify the boilerplate code from the Notion documentation so it contains a real request object. From the superface folder, open notion-workspace.user-listing.notion.mjs (or .py if you created Python files) and modify the object in the usecase.perform() function.

notion-workspace.user-listing.notion.mjs
{
    notionVersion : '2022-06-28',
    page_size: 10,
}

Test it​

To test it you can use the execute command.

superface execute notion notion-workspace/user-listing

If successful, you will see a JSON response listing the users in your workspace.