Skip to main content

​
About Notion

Serval’s Notion integration connects a Notion workspace to Serval so workflows can search and read your Notion content, and so pages and databases shared with the integration can be ingested into Serval’s knowledge base. Serval stores your credentials securely and attaches them to every call on your behalf - all traffic goes only to Notion’s official API host (api.notion.com). The integration also installs one ready-to-use workflow, Search and Read Notion Pages, which finds relevant pages and reads their full content so it can be used to answer questions. Authentication: Serval-managed OAuth (recommended), a bring-your-own Notion public integration, or a Notion internal integration secret (API key). All three behave identically once connected. Data sync: Background knowledge sync of every page and database shared with the integration. After the first full sync, items are only re-synced when they have been edited in Notion (or when a previous sync attempt didn’t complete). You can also trigger a manual sync from the Serval UI at any time.

​
What the Notion integration enables

Anything defined in the Notion API can be accessed through Serval.

​
Get your credentials

What you need depends on which connect option you choose. All Notion integrations are created and managed from the Notion integrations dashboard.
Nothing to create. You’ll sign in to Notion in a popup, choose a workspace, and pick which pages to share - Serval handles everything else. Skip ahead to Connect in Serval.

​
Connect in Serval

Open the Notion integration in Serval and pick one of the three options in the connect modal.
1

Choose the OAuth option

Select Sign in with Notion (OAuth).
2

Authorize in the popup

Sign in to Notion, choose the workspace to connect, and pick the pages to share with Serval. There is no permissions screen to review - Notion OAuth has no scopes; access is governed entirely by which workspace you select and which pages you share.
3

Confirm the new connection

The connection is named after your Notion workspace, with your email in parentheses when Notion provides it - for example, a workspace called Acme connected by jane@acme.com appears as Acme (jane@acme.com). If a teammate connects the same workspace, they get their own separate connection; this is expected.

​
Verifying the connection

After connecting, run the integration’s health checks:
  • Test Notion Connection - verifies basic connectivity and authentication by fetching the integration’s bot user.
    • Success: “Successfully connected to Notion as “[name]"" (the name falls back to “Unknown” when Notion returns no name)
    • Failure: “Unable to connect to Notion. Please verify your integration token and permissions are correct.”
  • List Notion Users - verifies the integration can list users in the workspace.
    • Success: “Successfully listed users from Notion (found [number])”
    • Failure: “Unable to list users from Notion. Please verify your integration has access to the workspace.”
  • Search Notion Content - verifies the integration can search pages and databases.
    • Success: “Successfully searched Notion content (found [number] items)” - with ”, more available” appended inside the parentheses when more results exist
    • Failure: “Unable to search content in Notion. Please verify your integration has access to pages and databases.”
The most common “all checks green but nothing syncs” cause: Search Notion Content succeeds even when it finds zero items. Read the count in the success message - “found 0 items” means authentication works but no content has been shared with the integration yet.

​
Gotchas and troubleshooting

This is the #1 source of Notion confusion. Every read path - knowledge sync, the Search Notion Content health check, and the seeded search workflow - sees only pages and databases connected to the integration. There is no workspace-wide crawl. A successful connect with nothing shared yields an empty knowledge sync and “Successfully searched Notion content (found 0 items)”. Share content in Notion via ••• → Connections on each top-level page or database; child pages inherit the connection. (Adding a connection to a page requires edit access on that page - that’s Notion’s rule, not Serval’s.) For the OAuth path, the page picker on Notion’s authorize screen controls the initial grant.
Search Notion Content reports success regardless of how many items it finds. The found-count in the message is the real signal - “found 0 items” means the credentials work but nothing is shared with the integration yet.
On a knowledge source’s first sync, Serval deliberately waits 30 seconds for Notion’s search indexing before searching. Pages newly shared with the integration can also take time to appear in Notion’s search index, so a sync triggered immediately after sharing may miss them - re-sync if a just-shared page is absent.
Serval verifies the pasted secret against Notion before saving anything. An invalid secret - or any token that isn’t a real internal integration secret (for example, a pasted user OAuth token) - fails immediately with: “Could not verify this Notion secret. Make sure it’s a valid Internal Integration Secret with read content access, and that the integration is connected to at least one page.” Note that this check validates the secret itself; it cannot tell whether any pages have actually been shared with the integration yet.
When rotating the Internal Integration Secret, Serval re-validates whatever you submit and never falls back to the stored value - a blank field fails with “A Notion internal integration secret is required.” and a masked value fails verification. Paste the complete new secret. Similarly, reconnecting a bring-your-own integration pre-fills only the Display name and OAuth client ID - the OAuth client secret must be re-entered every time.
Notion rejects any redirect URI that doesn’t exactly match a registered one. Always copy the URI from Serval’s connect modal rather than typing it. Your submitted client ID and secret are held for only 10 minutes - if the Notion authorize step takes longer, the connection fails with “Invalid or expired OAuth state” and you must re-submit the form.
Only public Notion integrations support OAuth. If you have an internal integration, use the API-key path instead - both end up with the same access and behave identically at runtime.
The OAuth flow requests no scopes and Notion returns none. Access is controlled entirely by which workspace you select at authorize time, plus per-page sharing afterwards.
OAuth and bring-your-own connections are identified by workspace and the connecting user’s email, and named after the workspace with the connecting user’s email in parentheses. Two teammates connecting the same Notion workspace create two distinct connections. This is expected behavior, not a duplicate-connection bug.
Need help? Contact support@serval.com for assistance with your Notion integration.