# Notion

> Indexing a Notion workspace through the API — creating an integration, sharing pages, what gets imported, and the export-zip alternative.

- Updated: 2026-10-30
- Source: https://contextator.com/en/docs/notion/
- Language: en-US
- Author: Muhammet Şafak

---
Index a Notion workspace directly through the API: every page shared with an internal integration is
rendered to Markdown and kept in sync. Pages that change are re-rendered; pages that stop being shared
are removed.

If you would rather not create an integration, you can also upload a Notion **Export → Markdown & CSV**
zip — see [the export route](#the-export-zip-alternative) at the bottom.

## 1. Create an integration

1. Go to **notion.so/profile/integrations** and create an **internal integration**.
2. Copy its token (it starts with `ntn_` or `secret_`).

## 2. Share the pages with it

In Notion, open each page or database you want indexed and share it with the integration
(**… → Connections → your integration**). Sharing a parent page shares its children.

Nothing is visible to Contextator until you do this — a brand-new integration sees nothing.

## 3. Add the source

**Add source → Notion**

| Field | Notes |
|-------|-------|
| **Name** | The mount prefix. Immutable |
| **Integration token** | Stored encrypted with `SECRET_KEY`, never shown again |
| **Root pages or databases** | Optional. Page or database ids — or simply their URLs, the id is picked out. One per line. Leave empty to take everything shared with the integration |

Once the source is saved, press **Test** on its row (or **Test connection** in its **Edit** dialog): it reads
the integration's own user and answers with its name (`Connected as Docs Importer`), so a wrong token is
obvious before any indexing starts.

> `SECRET_KEY` must be set (32+ characters) before a source can store a token. See
> [Configuration](/en/docs/configuration/).

## Connect with Notion (OAuth)

Since 0.6.0 there is a second way to authorise a source: **Connect with Notion**, where you pick the pages in Notion's own
page picker instead of creating an integration and pasting its token. It needs a **public connection you register
yourself** at `notion.so/profile/integrations` (a *public* connection, not an internal one) — there is no
Contextator-owned connection — and three variables on the instance: `NOTION_OAUTH_CLIENT_ID`,
`NOTION_OAUTH_CLIENT_SECRET` and a redirect URI (`NOTION_OAUTH_REDIRECT_URI`, or derived from `PUBLIC_BASE_URL`; see
[Configuration](/en/docs/configuration/#connect-with-notion-oauth)). With none of them set nothing changes: the dashboard
shows only the token field.

- The redirect URI must name this instance: `https://<your-domain>/api/sources/notion/oauth/callback`, or
  `http://localhost:<port>/api/sources/notion/oauth/callback` for an instance on your own machine. Not an IP address.
- Open the dashboard on that same host: sign-in cookies belong to a host name, so a redirect URI that says `localhost`
  with the dashboard opened at `127.0.0.1` sends the browser back to a host where you are not signed in.
- Startup is refused when only one of the id and the secret is set, when neither a redirect URI nor `PUBLIC_BASE_URL` is
  set, or when `SECRET_KEY` is missing.
- Only a signed-in editor of the project can start it, from the dashboard; an API token or `ADMIN_TOKEN` cannot, because
  it is a browser round trip.
- The access and refresh token are stored encrypted with `SECRET_KEY`. The source refreshes them when Notion refuses the
  access token, and a revoked connection ends the run asking for **Reconnect**, which authorises the source again without
  changing its name or settings.
- An OAuth source has **no webhook**: a public connection's webhook belongs to the connection, not to one source, so the
  schedule keeps it fresh. A project export drops the tokens, so an imported OAuth source needs Reconnect. A Notion
  `secret` that starts with `{` is refused over the API with `400 invalid_request`: that is the shape of an OAuth
  connection, which only the dashboard flow creates.

## What gets imported

Each page becomes one Markdown file, nested in a folder per parent page, with the title,
Notion id, URL and `last_edited_time` in frontmatter. File and folder names are the title as a slug plus
the first eight characters of the Notion id; a page that lives in a database sits in a
`database--<first eight id characters>` folder:

```
notion/engineering--1a2b3c4d/runbooks--5e6f7a8b/rotating-the-signing-key--9c0d1e2f.md
```

Rendered block types: paragraphs, all three heading levels (including the blocks folded under a
toggleable heading), bulleted, numbered and to-do lists with their nesting, quotes, callouts, code
blocks, tables, dividers, equations, bookmarks, images and file links. Unknown block types are skipped
rather than failing the page, so a new Notion feature never breaks an import.

Limits per source: 5000 pages by default (`NOTION_MAX_PAGES`, 1 to 100 000, set per instance — see [Configuration](/en/docs/configuration/)) and 25 levels of nesting. Requests are throttled to about three per
second, which is Notion's documented rate limit — a large workspace takes a while on the first sync and
is fast afterwards.

## Keeping it in sync

At the start of every index run, Contextator pulls the workspace again and **re-renders only pages
whose `last_edited_time` changed**. A page that is no longer shared, or was deleted, has its file
removed.

Notion's own push webhook works the other way around from a git provider's: the URL is still pasted
into a Notion subscription, the same pattern as [Push Webhooks](/en/docs/push-webhooks/) elsewhere, but
the secret runs in the opposite direction. Open a **15-minute verification window** first, with **Open verification window** in the source's **Edit**
dialog; Notion's first delivery to that URL carries the token, which is pasted back into Notion's
*Webhooks* tab to finish verification. Once verified it starts a sync when a page is edited, deleted or moved — not within seconds, since a burst of
deliveries is collapsed into one run and runs are at least `WEBHOOK_MIN_INTERVAL_MINUTES` (5 by default)
apart — but it does not close every gap: Notion sends no event when a page is unshared, so an unshare has no event of its own. The next full sync drops the page, whether a webhook for some other page, **Sync** or the **Sync every** interval started it. The interval's check cannot see an unshare by itself: it looks only at the newest edit time in the workspace, so it notices edits, not unshares.

If nothing else starts a sync, the guarantee is the scheduled check, and it is bounded. A scheduled source is synced in full whenever its last successful sync is older than
`SYNC_MAX_SKIP_HOURS` (24 hours by default), whatever the check says. The page is missing from that pull, so its
file is removed: an unshared page leaves the index, and search results, within that many hours plus the source's
own **Sync every** interval and up to a minute, plus the time the sync itself takes or a run already in progress. Set the variable to `0` and the bound is off: the page then stays
until the next edit anywhere in the workspace triggers a run. A source set to *Never* is not scheduled, so the bound does not reach it.

To drop an unshared page right away, press **Sync** on the source, **Re-index** on the project, or call
`POST /api/projects/:id/reindex` — the page is missing from that pull, so its file is removed (see
[Admin API](/en/docs/admin-api/)). Until the webhook is verified, **Sync every** is what picks up edits.

## When something is wrong

If the token is rejected, or **none** of the configured root pages can be read, the sync **fails** and
says so. It does not report an empty workspace — which would otherwise delete every page already
imported. The other sources of the project still index, and the project reports:

```
2/3 sources synced; notion: No configured Notion root could be read — 1a2b3c4d… (object_not_found)
```

If *some* roots are readable and others are not, the readable ones import and the failures are reported.

| Symptom | Cause and fix |
|---------|---------------|
| **Test** answers with Notion's own message about an invalid API token (its error code is `unauthorized`) | Wrong or revoked token. Create a new one and paste it |
| The source imports nothing | Nothing is shared with the integration yet. Share the pages (**… → Connections**) |
| A specific page is missing | It — or its parent — is not shared with the integration, or it is deeper than 25 levels |
| `object_not_found` for a root id | The id is wrong, or that page is not shared with the integration |
| A database's rows are missing | Share the database itself, not only the pages inside it |

## The export-zip alternative

If you cannot create an integration, export from Notion (**… → Export → Markdown & CSV**) and upload
the zip as an **Upload files** source with content type **Notion export**. The 32-character page id
Notion appends to every file and folder name is stripped from paths and from the links pointing at
them, and the nested `Part-1.zip` inside the export is unpacked automatically.

The trade-off: nothing syncs by itself — you re-export and re-upload when the content changes.
