Notion API Essential Guide

What type of API does Notion provide?

Notion provides a REST API. The key characteristics of Notion's API include:

• The base URL for all API requests is https://api.notion.com
• HTTPS is required for all API requests
• It follows RESTful conventions, with operations performed via GET, POST, PATCH, and DELETE requests on resources like pages and databases
• Request and response bodies are encoded as JSON

In summary, Notion's API is a standard REST API that follows common conventions, allowing developers to interact with Notion resources programmatically using standard HTTP requests and JSON payloads.

Does the Notion API have webhooks?

Current Status of Webhooks

The official Notion API does not currently have webhooks implemented. Webhooks are on the list of features to be implemented in the future, but they are not currently available.

Key Points to Consider

1. Webhooks, also referred to as "triggers" or event notifications, are not yet part of the Notion API.

2. The current API allows for programmatic interaction with databases, pages, and content within Notion, but does not include real-time event notifications.

3. The API currently supports operations like:

   • Pulling specific database entries
   • Searching database entries based on properties
   • Creating new pages
   • Setting and retrieving page properties
   • Creating new blocks in pages
   • Getting a list of workspace users

Future Possibilities

While webhooks are not currently available, their future implementation could potentially allow for:

1. Real-time notifications when changes occur in a Notion workspace.
2. Automated triggers for actions when specific events happen in Notion.
3. More efficient integrations with other tools and services.

Best Practices

Until webhooks are implemented, developers can:

1. Use polling mechanisms to periodically check for changes in Notion data.
2. Leverage existing integration platforms like Zapier that have built connections with Notion.
3. Stay updated with Notion's API documentation and changelog for any announcements regarding webhook implementation.

In conclusion, while the Notion API offers powerful capabilities for interacting with Notion data, it does not currently support webhooks or real-time event subscriptions. Developers should plan their integrations accordingly and look out for future updates to the API.

Rate Limits and other limitations

Here's a summary of the API Rate Limits for the Notion API:

Rate Limits

The Notion API has the following rate limits:

• The rate limit for incoming requests per integration is an average of three requests per second.
• Some bursts beyond the average rate are allowed.
• Rate-limited requests will return a "rate_limited" error code (HTTP response status 429).

Handling Rate Limits

To handle rate limits, integrations should:

• Accommodate variable rate limits by handling HTTP 429 responses.
• Respect the Retry-After response header value, which is set as an integer number of seconds.
• Back off or slow down the speed of future requests.
• Implement queues for pending requests, which can be consumed by sending requests as long as Notion does not respond with an HTTP 429.

Key Points to Consider

1. Rate limits may change in the future.
2. Notion may introduce distinct rate limits for workspaces in different pricing plans.
3. The API doesn't have a hard limit, but exceeding an average of 3 requests per second is not recommended.
4. Occasional bursts above the average rate are allowed.

Best Practices

1. Implement proper rate limit error handling in your API client wrapper.
2. Use a delay mechanism to retry requests after receiving a rate limit error.
3. Consider using a dedicated TypeScript library like @notionhq/client for communicating with the Notion API.
4. Be prepared to adjust your integration's request patterns if Notion changes its rate limits in the future.

Code Example

Here's a simplified example of how to handle rate limits in your API requests:

async function request() {
  try {
    return await client.databases.retrieve({ database_id: 'c2da9700-8244-4bc0-bff1-8dccd909b211' });
  } catch (error) {
    if (!isNotionApiErrorOfType(error, APIErrorCode.RateLimited)) {
      throw error;
    }

    const retryAfter = parseInt(error.headers.get('retry-after'));

    return delay(
      () => request(),
      retryAfter * 1000,
    );
  }
}

This code demonstrates how to catch a rate limit error, extract the retry-after time, and delay the request accordingly before retrying.

By following these guidelines and implementing proper rate limit handling, you can ensure that your integration works smoothly with the Notion API while respecting its rate limits.

Latest API Version

The most recent version of the Notion API is 2022-06-28.

Key points to consider:

• Notion API versions are named for the date they are released.
• The version is set by including a Notion-Version header in API requests.
• Setting the Notion-Version header is required for all API requests.
• New API versions are released when backwards-incompatible changes are introduced.

Code example:

Here's an example of how to set the latest Notion API version in a cURL request:

curl https://api.notion.com/v1/users/01da9b00-e400-4959-91ce-af55307647e5 \
  -H "Authorization: Bearer secret_t1CdN9S8yicG5eWLUOfhcWaOscVnFXns" \
  -H "Notion-Version: 2022-06-28"

Best practices:

1. Always include the Notion-Version header in your API requests to ensure consistent responses.
2. Stay updated with the latest API version to take advantage of new features and improvements.
3. Be aware that new features and additions to the API don't always require a new version.
4. If you're using the JavaScript SDK, the appropriate Notion-Version header will be set for you automatically.
5. When upgrading to a new version, review the changelog to understand any backwards-incompatible changes that may affect your integration.

How to get a Notion developer account and API Keys?

To get a developer account and API keys for Notion:

1. Create a Notion account at notion.so if you don't have one.

2. Go to the Notion integrations dashboard at www.notion.com/my-integrations.

3. Click "New integration" to create a new integration in your Notion workspace.

4. Configure the integration:

   • Enter a name
   • Select the associated Notion workspace
   • Choose the required capabilities and access permissions

5. After creation, you'll receive an API secret token for authenticating requests to the Notion API.

6. Grant the integration access to specific pages/databases:

   • Open the page in Notion
   • Click the "..." menu in the top right
   • Select "Add connections"
   • Choose your integration

Note: You must be a Workspace Owner to create integrations.

What can you do with the Notion API?

The Notion API allows interaction with several data models, each with its own set of capabilities. Here's a breakdown of what is possible for each data model:

Database Objects

• Read Content: Retrieve a database to access existing content
• Update Content: Update existing content within a database
• Insert Content: Create new content within a database

Page Objects

• Read Content: Retrieve a page to access its content
• Update Content: Update properties of a page
• Insert Content: Create new pages

Block Objects

• Read Content: Retrieve block children to access content within blocks
• Update Content: Update existing blocks
• Insert Content: Append new block children to a page or another block

User Objects

• No User Information: Prevents access to any user information
• User Information Without Email Addresses: Access to user information excluding email addresses
• User Information With Email Addresses: Full access to user information including name, profile image, and email address

Comment Objects

• Read Comments: Access to read comments from a Notion page or block
• Insert Comments: Ability to insert comments into a page or an existing discussion

Key Points to Consider

• The capabilities of an integration determine which actions it can perform and what information it can access within a Notion workspace.
• An integration's capabilities are set during the authorization process and can be adjusted as needed.
• The Notion API uses a REST architecture, allowing developers to interact with Notion workspaces programmatically.
• The most recent version of the Notion API is Notion-Version 2022-06-28.

Best Practices

• When designing integrations, consider the specific capabilities needed for your use case and request only the necessary permissions.
• Be aware of the limitations and capabilities of each data model when planning your integration.
• Keep your integration up to date with the latest API version to ensure access to the most recent features and improvements.