Connect Notion
For organisation admins. Connects your Speclr organisation to Notion once, so project teams can keep their requirements documentation as pages below a Notion page they choose.
Updated
Use a dedicated machine account
- Survives people leavingThe connection works for the account that authorised it. A personal account takes the wiki updates down with it when its owner leaves.
- Anyone on the team can share pagesOnly the account that authorised Speclr can share more pages with it. With a team mailbox, every admin can sign in as that account.
- Only the pages it needsNotion offers every page the authorising account has full access to. An account with access to the parent pages only cannot share anything else by mistake.
Speclr writes to Notion: it keeps your project's requirements documentation as pages below a page you choose. It never imports anything from Notion.
Create the account and give it the parent pages
Add an account such as
speclr-bot@acme.com, with a team mailbox, as a member of your Notion workspace. Give it full access to each page your project teams will put their documentation under, for example a page named Engineering. Its sub-pages come with it.- Two-step verification on, backup codes stored with the team
- Full access to each parent page: Notion offers only those pages to Speclr
- No access to private pages Speclr does not need
Allow Speclr in an Enterprise workspace
On Notion's Enterprise plan, workspace owners can limit which connections members may install, under Settings › Connections. If your workspace does, a workspace owner approves Speclr there first. Other plans have no such step.
Connect in Speclr and select the pages
Open Organisation settings › Integrations › Discover and choose "Connect" on Notion. Only organisation admins see the integrations. When Notion asks you to sign in, use the machine account, not your own. A private browser window avoids mix-ups.
Notion then shows "Speclr wants to access …" and asks which pages Speclr may use. Choose "Select pages", tick the parent pages and choose "Allow access". Pages you do not select stay invisible to Speclr.
Back in Speclr, the connection appears under Yours. It reads "Acts as" Speclr "on" your Notion workspace: in Notion, every change Speclr makes shows the bot "Speclr" as its author, and the connection is listed as "Speclr" under Settings › Connections. Check that the workspace is the right one.
Check the permissions
Notion has no OAuth scopes. Speclr's integration asks for these capabilities, and only for the pages you selected:
- Read content
- to find its pages and notice edits
- Update content
- to update its pages
- Insert content
- to create pages below the parent page
- User information
- without email addresses
- Comments
- none
Pick the parent page in each Speclr project
Any member of a Speclr project can do this. Open Project settings › "Integrations" and, in the "Wiki" row under "Parent page", choose "Choose page". Only pages shared with Speclr and their sub-pages are listed; a missing page has to be shared first, as described under Share more pages. Once saved, the row reads "Saved · the page is shared with Speclr".
Right after saving, Speclr asks "Put the requirements documentation into Notion?". Choose "Put it in" to create the pages. With "Not now", the row keeps "Not in Notion yet" with "Put it in…" for later. Speclr needs a committed version of the Discovery first.
Afterwards, the row's "Pages" line links the project page "In Notion" and shows the last sync, for example "Last sync · 2 updated · 9 unchanged" after a commit.
What Speclr creates in Notion
Below the parent page, Speclr creates one project page, for example Shop – Requirements for a project named Shop. Below it come the documentation pages. They follow the req42 framework and keep its numbers:
- 1. Vision and goals: the problem, the solution, the value proposition, the business model and the success metrics from the vision.
- 2. Stakeholders: the target users and market, and the actors.
- 3. Scope: the first milestone with its goal and stories, and what is out of scope.
- 4. Product backlog: 4.1 epics (the activities), 4.2 features (the steps) and 4.3 user stories, each with story id, title, milestone, hand-over status and a link to its work item.
- 5. Supporting models: the business rules with their ids, such as BR-021, and the data fields.
- 6. Quality requirements: the stories' non-functional requirements, with their story ids.
- 7. Constraints: the project's constitution.
- 8. Domain terminology: the glossary.
- 11. Roadmap: the milestones in order, with their goals and stories.
- 12. Risks and assumptions: the risks from the vision, then the risks your team tracks, under "Risk register" and "Closed risks". See Risks.
req42 also has 9 (resources and staff) and 10 (team structure). Speclr has nothing for them and creates no page. There is no page per story either.
Your team can add its own pages inside the project page, for example for 9 and 10. Speclr leaves them alone: it never changes, moves or deletes them, and they do not count as an edit of its pages.
Every page starts with a note such as "Generated by Speclr · edit in Speclr · exported 2 Nov 2026". Speclr creates a page for each req42 section it has content for; a part without content yet reads "Not yet specified.". The pages show committed versions only, so an open draft does not appear. The exception is 7. Constraints: the constitution has no versions, so the page shows its current text.
Edit in Speclr, not in Notion
Unlike a GitHub issue or a Jira description, these pages are Speclr's from top to bottom. Change the content in Speclr. After each commit, Speclr updates the affected pages on its own and leaves the others alone. A page title changed in Notion is set back on the next sync.
If someone edits a Speclr page in Notion, Speclr does not overwrite it. The "Wiki" row says, for example, "5. Supporting models was edited in Notion." "Resolve…" compares "Written by Speclr" with what is in Notion now and offers two ways out:
- Keep the Notion version: the row then says "5. Supporting models was kept as edited in Notion. Later versions are not written there." "Replace…" undoes that later.
- Replace with the Speclr version: Speclr writes its version over the edit.
A page deleted in Notion, or moved where Speclr cannot see it, shows for example "8. Domain terminology no longer exists." Choose "Recreate the page", or "Detach" to let Speclr forget it. Recreating the project page also recreates the missing pages below it. Nothing is ever imported from Notion into Speclr.
Choosing another parent page later leaves the old pages in Notion. Speclr no longer updates them.
Share more pages
Only the machine account can share pages with Speclr. Choose "Reconnect" on the connection in Speclr, sign in to Notion as the machine account and select the page in Notion's page picker.
Or, signed in to Notion as the machine account, open the page's ••• menu and add the Speclr connection under Connections.
Reconnect or disconnect
Reconnect when the connection shows "Nothing is handed over until it is reconnected", as the same machine account.
Disconnecting first names the affected projects. Their parent pages and the pages in Notion stay; Speclr stops updating them.
Troubleshooting
- "The parent page Engineering is not accessible.": the page was deleted, moved to the trash or is no longer shared with Speclr. Share it again, or choose another parent page.
- "Speclr may not edit 5. Supporting models in Notion. Share Engineering with the Speclr connection again.": the parent page lost its connection to Speclr. Share it again as described under Share more pages.
- "This page is not shared with Speclr.", or a page is missing from the list: the machine account has no full access to it, or it was not selected. Share it as described under Share more pages.
- "Commit a version of the Discovery first.": the documentation starts from the vision. Commit the Discovery once, then put it in.
- "The project page Shop – Requirements is missing in Notion. Recreate it first.": recreate the project page from the "Wiki" row; the missing pages below it come back with it.
- "An admin must reconnect the Notion connection.": reconnect as the machine account. Projects without any wiki show "An organisation admin must connect a wiki first."
- Notion does not let you connect Speclr: in an Enterprise workspace, a workspace owner approves it under Settings › Connections first.
- A change made in Notion is not in Speclr: Speclr never imports. Make the change in Speclr and commit it.
