Notion Getting Started: API Integration Guide (2026)

Getting started overview

Integrating with the Notion API enables programmatic interaction with Notion workspaces, allowing developers to automate tasks, synchronize data, and build custom applications. This guide focuses on the initial steps required to set up an environment and make a first successful API call. The process involves creating a Notion account, setting up an internal integration to generate an API token, and then using that token to fetch data from a Notion database or page.

Notion's API is designed to interact with blocks, pages, and databases, reflecting the platform's hierarchical data structure. Blocks are the fundamental units of content, which can be combined into pages. Pages can reside within databases or independently. The API supports various operations, including creating, reading, updating, and deleting these elements. Understanding this structure is foundational for effective API use, as outlined in the Notion API reference documentation.

Before making API calls, it is necessary to grant the integration access to specific pages or databases within a Notion workspace. This permission model ensures that integrations only access data to which they have been explicitly granted access, enhancing security and control over data exposure. This granular access control is a key aspect of Notion's security framework, aligning with broader principles of least privilege often discussed in cloud security best practices.

Below is a quick reference table summarizing the key steps to get started with the Notion API:

Create an account and get keys

To begin using the Notion API, a Notion account is required. Users can sign up for a free personal plan or explore paid tiers that offer additional features. Once an account is established, the next step is to create an internal integration to generate an API token, which serves as the authentication credential for API requests.

1. Sign up for a Notion Account: Navigate to the Notion signup page and complete the registration process. A free account is sufficient for initial API exploration and development.

2. Access Integrations Settings: After logging into Notion, navigate to the "Settings & members" menu, then select "Connections." Alternatively, directly visit the My Integrations page.

3. Create a New Integration: Click on the "Develop or manage integrations" button. On the integrations page, select "New integration."

4. Configure Integration Details:

   • Name: Provide a descriptive name for your integration (e.g., "My First API Test").
   • Associated workspace: Select the Notion workspace where this integration will operate.
   • Capabilities: Review and select the necessary permissions for the integration. For most initial tests, the default permissions are adequate, but these can be adjusted later based on specific requirements. For instance, to read a database, the integration needs read access to databases.

5. Generate and Copy API Token: After creating the integration, Notion will display an "Internal Integration Token." This token is a sensitive credential and should be treated like a password. Copy this token immediately, as it will only be shown once. If lost, a new token will need to be generated.

6. Grant Integration Access to Pages/Databases: For your integration to interact with specific Notion pages or databases, it must be explicitly invited. In your Notion workspace, open the page or database you want the integration to access. Click the "Share" button, then click "Invite" and select your newly created integration from the list. Ensure the integration has the appropriate access level (e.g., "Can edit content" for write operations, "Can view" for read-only).

Your first request

After obtaining an internal integration token and sharing a Notion database or page with your integration, you can make your first API request. This example demonstrates how to retrieve the details of a specific database using its ID.

First, identify the ID of the Notion database you wish to query. The database ID can be found in the URL of the database in your Notion workspace. It is the alphanumeric string between notion.so/ and ?v=, or after the workspace name if no view parameter is present (e.g., https://www.notion.so/yourworkspace/[database_id]?v=...).

Replace YOUR_NOTION_API_TOKEN with the integration token you copied, and YOUR_DATABASE_ID with the ID of your target database.

curl -X GET "https://api.notion.com/v1/databases/YOUR_DATABASE_ID" \
  -H "Authorization: Bearer YOUR_NOTION_API_TOKEN" \
  -H "Notion-Version: 2022-06-28"

This cURL command sends an HTTP GET request to the Notion API's /v1/databases/{database_id} endpoint. The Authorization header includes your API token, prefixed with Bearer. The Notion-Version header specifies the API version you are targeting, which is critical for ensuring compatibility and consistent behavior, as described in the Notion API versioning guide.

A successful response will return a JSON object containing metadata about the database, including its title, properties, and other configuration details. An example of a successful response structure might look like this (abbreviated):

{
  "object": "database",
  "id": "YOUR_DATABASE_ID",
  "cover": null,
  "icon": null,
  "created_time": "2023-01-01T12:00:00.000Z",
  "last_edited_time": "2023-01-01T12:00:00.000Z",
  "title": [
    {
      "type": "text",
      "text": {
        "content": "My Projects",
        "link": null
      },
      "annotations": {
        "bold": false,
        "italic": false,
        "strikethrough": false,
        "underline": false,
        "code": false,
        "color": "default"
      },
      "plain_text": "My Projects",
      "href": null
    }
  ],
  "properties": {
    "Name": {
      "id": "title",
      "name": "Name",
      "type": "title",
      "title": {}
    },
    "Status": {
      "id": "%3B%3CD%",
      "name": "Status",
      "type": "select",
      "select": {
        "options": [
          {
            "id": "1",
            "name": "Not started",
            "color": "gray"
          }
        ]
      }
    }
  },
  "parent": {
    "type": "workspace",
    "workspace": true
  },
  "url": "https://www.notion.so/YOUR_DATABASE_ID"
}

Common next steps

After successfully retrieving database information, developers typically proceed with more complex interactions to build functional integrations. Common next steps include:

• Querying Database Pages: To retrieve the actual entries (pages) within a database, use the Query a database endpoint. This allows for filtering, sorting, and pagination of results.

• Creating New Pages: To add new entries to a database or create standalone pages, utilize the Create a page endpoint. This often involves specifying properties for database entries or content blocks for standalone pages.

• Updating Pages and Blocks: Modify existing content using the Update block or Update page endpoints. This is crucial for synchronizing data or automating content updates.

• Working with Blocks: Interact with individual content blocks (paragraphs, headings, to-do items, etc.) within pages using the various Block API endpoints. This enables fine-grained control over page content.

• Error Handling: Implement robust error handling in your application. The Notion API returns specific error codes and messages that can help diagnose issues such as invalid IDs, permission problems, or rate limiting.

• Using SDKs: For development in specific programming languages, consider using official or community-maintained Notion API client libraries (SDKs). These libraries abstract away the complexities of HTTP requests and JSON parsing, providing a more idiomatic way to interact with the API.

• Building Webhooks: For real-time updates and event-driven architectures, explore using Notion webhooks. These allow your application to receive notifications when changes occur in your Notion workspace, eliminating the need for constant polling.

Troubleshooting the first call

When making your first API call to Notion, several common issues can arise. Here are typical problems and their solutions:

• 401 Unauthorized: Invalid API Token
  This error typically means your Authorization header is incorrect or missing. Double-check that your internal integration token is correctly copied and prefixed with Bearer. Ensure there are no leading or trailing spaces. If you suspect the token is compromised or incorrect, generate a new one from your Notion integrations page.

• 403 Forbidden: Not Shared with Integration
  If your integration receives a 403 error, it usually indicates that the database or page you are trying to access has not been shared with your integration. Go to the specific Notion database or page, click the "Share" button, and ensure your integration is listed with appropriate access permissions (e.g., "Can view" or "Can edit content"). Remember that even if the integration is in the workspace, it still needs explicit page/database sharing.

• 400 Bad Request: Missing or Invalid Notion-Version Header
  The Notion API requires a Notion-Version header in all requests. This header ensures your request is processed against a specific API version. Ensure the header is present and the date format (YYYY-MM-DD) is correct, for example, Notion-Version: 2022-06-28. The Notion API versioning documentation lists supported versions.

• 404 Not Found: Incorrect Database or Page ID
  Verify that the database or page ID in your request URL is accurate. IDs are long alphanumeric strings. Minor typos will result in a 404. Retrieve the ID directly from the Notion page URL or by using the Retrieve block children endpoint to discover IDs of nested blocks.

• Rate Limiting (429 Too Many Requests)
  Notion implements rate limits to prevent abuse and ensure service stability. If you receive a 429 error, your application is sending too many requests in a short period. Implement exponential backoff and retry logic in your application to handle these errors gracefully.

• CORS Issues (Browser-based applications)
  If you are developing a browser-based application, you might encounter Cross-Origin Resource Sharing (CORS) errors. The Notion API does not directly support CORS for browser-initiated requests. For browser-based applications, it is necessary to route requests through a backend server or a proxy to avoid CORS restrictions, as direct client-side calls are generally not permitted. This is standard practice when dealing with APIs that do not explicitly enable CORS for all origins, a common security measure for APIs to prevent unauthorized access from arbitrary web pages.