Notion

Connect & Ingest data from Notion

Notion is an all-in-one workspace for notes, databases, wikis, and project management. The Sling Notion connector extracts data from the Notion REST API, supporting pages, databases, blocks (content), users, and comments.

CLI Pro Required: APIs require a CLI Pro token or Platform Plan.

Setup

The following credentials are accepted:

Secrets:

• api_key (required) -> Your Notion Internal Integration Token

Getting Your Integration Token

1. Go to My Integrations in your Notion settings

2. Click "Create new integration"

3. Give it a name (e.g., "Sling Integration")

4. Select the workspace you want to connect

5. Under Capabilities, ensure these are enabled:

   • Read content — required for pages, databases, and blocks

   • Read comments — required for the comments endpoint

   • Read user information including email addresses — required for the users endpoint

6. Click "Save" and copy the Internal Integration Secret (starts with ntn_)

Important: Notion integrations must be explicitly added to each page or database you want to access. Open a page in Notion, click the ⋯ menu → Connections → search for your integration name → add it. Child pages inherit the connection automatically.

Using sling conns

Here are examples of setting a connection named NOTION. We must provide the type=api property:

sling conns set NOTION type=api spec=notion secrets='{ api_key: ntn_xxxxxxxxxxxx }'

Environment Variable

export NOTION='{ type: api, spec: notion, secrets: { api_key: "ntn_xxxxxxxxxxxx" } }'

Sling Env File YAML

See here to learn more about the sling env.yaml file.

connections:
  NOTION:
    type: api
    spec: notion
    secrets:
      api_key: "ntn_xxxxxxxxxxxx"

Replication

Here's an example replication configuration to sync Notion data to a PostgreSQL database:

source: NOTION
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: notion.{stream_name}

streams:
  # sync all endpoints
  '*':

Incremental sync for pages and databases:

source: NOTION
target: MY_POSTGRES

defaults:
  object: notion.{stream_name}

streams:
  users:
    mode: full-refresh

  databases:
    mode: incremental

  pages:
    mode: incremental

  blocks:
    mode: full-refresh

  comments:
    mode: full-refresh

Endpoints

Endpoint	Description	Incremental	Depends On
users	All users in the workspace (people and bots)	No	—
databases	All databases shared with the integration	Yes	—
pages	All pages shared with the integration (including database rows)	Yes	—
blocks	Content blocks (paragraphs, headings, lists, etc.) for each page	No	pages
comments	Comments on each page	No	pages

The blocks and comments endpoints are child endpoints — they iterate over all page IDs collected by the pages endpoint. This means the pages endpoint must run first to populate the queue.

To discover available endpoints:

sling conns discover NOTION

Endpoint Details

users — Returns workspace members and bot integrations. Includes name, email (if permission granted), avatar URL, and user type (person or bot).

databases — Returns database metadata including title, properties schema, and parent information. Supports incremental sync via last_edited_time. Database IDs are also queued for potential child endpoint use.

pages — Returns all pages the integration can access, including standalone pages and database rows. Supports incremental sync via last_edited_time. Page IDs are queued for the blocks and comments child endpoints.

blocks — Returns content blocks for each page. Block types include paragraphs, headings, lists, to-dos, toggles, images, code blocks, and more. Each record includes a _page_id field linking it back to the parent page.

comments — Returns comments on each page. Each record includes the comment text, author, timestamps, and a _page_id field linking it to the parent page.

Incremental Sync

The databases and pages endpoints support incremental sync using the last_edited_time field:

• First run: Fetches all records shared with the integration

• Subsequent runs: Only fetches records edited after the last sync timestamp

The users, blocks, and comments endpoints always run in full-refresh mode since they don't support server-side time-based filtering.

Rate Limiting

The Notion API has rate limits:

• All requests: 3 requests per second

The connector automatically:

• Uses conservative rate limiting (3 requests/second with concurrency of 1)

• Retries with exponential backoff on 429 (rate limit) responses

• Allows up to 5 retry attempts

Sharing Pages with the Integration

Unlike some APIs where a token grants access to all data, Notion requires you to explicitly share pages and databases with your integration:

1. Open a page or database in Notion

2. Click the ⋯ (three-dot) menu in the top right

3. Select Connections

4. Search for your integration name and select it

5. Confirm the capabilities

Child pages and databases within a shared page automatically inherit access. To grant access to your entire workspace, share each top-level page.

Common Use Cases

Sync All Notion Data

source: NOTION
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: notion.{stream_name}

streams:
  '*':

Sync Pages and Databases Incrementally

source: NOTION
target: MY_POSTGRES

defaults:
  object: notion.{stream_name}

streams:
  databases:
    mode: incremental
  pages:
    mode: incremental

Extract Page Content for Search or Analysis

source: NOTION
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: content.{stream_name}

streams:
  pages:
  blocks:

Sync Workspace Members

source: NOTION
target: MY_POSTGRES

defaults:
  mode: full-refresh

streams:
  users:
    object: notion.users

If you are facing issues connecting, please reach out to us at [email protected], on discord or open a Github Issue here.