Contextator
ENTR

Sources

Notion

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

Updated:

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 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.

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). 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) 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 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). 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.

Arrow keys to move, Enter to open.