Notion API Getting Started: Quickstart Guide (2026)

Getting started overview

Integrating with the Notion API involves a sequence of steps to establish a connection between your application and a Notion workspace. This process typically begins with creating a dedicated integration within Notion, which generates an API token. This token serves as the authentication credential for your application. Following integration creation, it is necessary to grant the integration access to specific Notion pages, databases, or blocks that your application intends to interact with. Access control is managed directly within the Notion user interface.

Once the integration is configured and permissions are set, you can use the API token to send HTTP requests to Notion's endpoints. The Notion API supports standard RESTful operations, allowing you to read, create, update, and delete content within Notion workspaces. Common use cases include automating data entry, synchronizing external data sources, and building custom dashboards or reporting tools that pull information from Notion databases.

The API provides specific endpoints for interacting with Notion databases, Notion pages, and Notion blocks. Developers can choose to use one of the officially supported SDKs for JavaScript or Python, or make direct HTTP requests. The API also supports webhooks for receiving real-time notifications about changes in Notion content, which can be configured to trigger external actions or updates.

Here is a quick reference table outlining the essential steps to get started:

Create an account and get keys

To begin using the Notion API, you first need a Notion account. If you do not have one, you can sign up for a free Notion account. The free plan provides sufficient functionality to test API integrations. Once logged in, navigate to the Notion My Integrations page. This is the central hub for managing your API integrations.

On the My Integrations page, click the "New integration" button. You will be prompted to provide a name for your integration, choose an associated workspace, and select capabilities. For initial testing, you can leave the capabilities as default. After creating the integration, Notion will generate an "Internal Integration Token." This token is your API key and must be kept secure, as it grants access to the Notion content that the integration is shared with. Copy this token immediately, as it will only be shown once.

After creating the integration and obtaining the token, the next critical step is to grant your integration access to the specific Notion pages or databases it needs to interact with. An integration does not automatically have access to any content in your workspace. To grant access, open the Notion page or database you want to share. Click the "Share" button located in the top right corner, then search for your integration by its name and click "Invite." This action explicitly shares the selected content with your integration, enabling it to read or modify data according to the permissions you selected during integration creation (e.g., read content, update content, insert content).

It is important to note that the API token is a Bearer Token. This means it should be included in the Authorization header of your HTTP requests, prefixed with Bearer. For example, Authorization: Bearer YOUR_SECRET_TOKEN. This authentication method is detailed in the Notion API authorization documentation.

Your first request

After setting up your integration and granting it access, you can make your first API request. This example demonstrates how to retrieve a Notion database. First, you need the ID of the database. To find a database ID, open the database in your Notion workspace. The database ID is the string of characters between the workspace domain and the ?v= parameter in the URL. For example, in https://www.notion.so/myworkspace/a8d9c0e1f2g3h4i5j6k7l8m9n0o1p2q3?v=..., the database ID is a8d9c0e1f2g3h4i5j6k7l8m9n0o1p2q3.

Use the following cURL command to query a database:

curl 'https://api.notion.com/v1/databases/YOUR_DATABASE_ID/query' \
  -H 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  -H 'Notion-Version: 2022-06-28' \
  -H 'Content-Type: application/json' \
  --data '{}'

Replace YOUR_DATABASE_ID with the actual ID of your Notion database and YOUR_SECRET_TOKEN with your integration's API token. The Notion-Version header specifies the API version your request is compatible with; always use the latest stable version recommended in the Notion API changelog. The Content-Type: application/json header is standard for requests sending JSON data, even if the body is empty for a simple query.

A successful response will return a JSON object containing an array of page objects within the specified database. Each page object represents an entry in your Notion database, including its properties and content. If the request fails, check the HTTP status code and the error message in the response body for troubleshooting information. Common issues include incorrect API token, invalid database ID, or insufficient permissions.

Alternatively, if you prefer using an SDK, here's a Python example:

from notion_client import Client

notion = Client(auth="YOUR_SECRET_TOKEN")

database_id = "YOUR_DATABASE_ID"

try:
    response = notion.databases.query(
        database_id=database_id
    )
    print(response)
except Exception as e:
    print(f"An error occurred: {e}")

Before running the Python example, ensure you have installed the Notion Python SDK: pip install notion-client. For JavaScript, the setup is similar, requiring installation of the @notionhq/client package.

Common next steps

After successfully making your first API call, several common next steps can deepen your integration with Notion:

1. Explore different endpoints: The Notion API offers endpoints for interacting with individual pages, blocks (e.g., paragraphs, headings, to-do lists), and users. Review the Notion API reference documentation to understand the full range of available operations.
2. Understand rich text and properties: Notion content often includes rich text formatting and complex property types (e.g., multi-select, relations, rollups). Learning how to correctly format and parse these structures is essential for robust integrations. The Notion guide on working with page content provides relevant details.
3. Implement webhooks: For applications requiring real-time updates from Notion, configure webhooks. Webhooks allow Notion to notify your application when specific events occur, such as a page being updated or a new entry added to a database. This eliminates the need for constant polling and improves efficiency. Refer to the Notion webhooks documentation for setup instructions.
4. Error handling and rate limits: Implement robust error handling in your application to gracefully manage API errors, such as invalid requests or rate limit exceedances. The Notion API has rate limits to ensure fair usage. Your application should be designed to handle 429 Too Many Requests responses, potentially with exponential backoff.
5. OAuth for public integrations: If you are building an integration intended for multiple users or public distribution, you will need to implement OAuth 2.0. This allows users to grant your application access to their Notion workspaces without sharing their personal API tokens. The Notion API documentation on OAuth provides guidance for this process.
6. Utilize SDKs: While direct HTTP requests are feasible, using the official JavaScript or Python SDKs can simplify development by abstracting HTTP requests and providing type-safe methods for interacting with the API.

Troubleshooting the first call

When making your first Notion API call, you might encounter issues. Here are common problems and their solutions:

• 401 Unauthorized: This typically means your API token is incorrect or missing. Double-check that you copied the "Internal Integration Token" correctly from your Notion My Integrations page and included it in the Authorization: Bearer YOUR_SECRET_TOKEN header. Ensure there are no leading or trailing spaces.
• 404 Not Found: If you receive a 404, it often indicates an incorrect page or database ID. Verify the ID by opening the Notion page or database in your browser and extracting the ID from the URL. Also, confirm that the endpoint path in your request is correct (e.g., /v1/databases/YOUR_DATABASE_ID/query).
• 403 Forbidden: This error means your integration does not have permission to access the specific Notion content you are trying to interact with. Go to the Notion page or database within your workspace, click "Share," and ensure your integration is explicitly invited and has the necessary permissions (e.g., can read content, can edit content).
• Notion-Version header missing or incorrect: The Notion API requires a Notion-Version header. Ensure it is present and set to a valid, current API version string, such as 2022-06-28. Consult the Notion API changelog for the latest supported versions.
• Invalid JSON in request body: When sending data (e.g., creating a page), ensure your request body is valid JSON. Use a JSON linter if you are constructing complex payloads manually. The Content-Type: application/json header must also be set correctly.
• Network or firewall issues: Less common, but ensure your network environment or firewall is not blocking outbound HTTP requests to api.notion.com.

When troubleshooting, always examine the full HTTP response, including status codes and response body, as Notion often provides descriptive error messages that can pinpoint the exact problem. Tools like Postman or Insomnia can be helpful for testing API requests outside of your application code.