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
- Go to notion.so/profile/integrations and create an internal integration.
- Copy its token (it starts with
ntn_orsecret_).
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_KEYmust 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, orhttp://localhost:<port>/api/sources/notion/oauth/callbackfor 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
localhostwith the dashboard opened at127.0.0.1sends 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_URLis set, or whenSECRET_KEYis missing. - Only a signed-in editor of the project can start it, from the dashboard; an API token or
ADMIN_TOKENcannot, 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
secretthat starts with{is refused over the API with400 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.