How a Notion backup actually works
A backup is a long series of requests to an API that was never designed for backups. You get a copy you can trust when you know exactly what that API will and will not return.
It starts with a token
Notion uses integrations to decide who can read what. You create an internal integration, and it can only read the pages and databases you share with it. It reads nothing else in the workspace, and it reads nothing at all until you share something. The token identifies that integration.
That is the whole access model NotionManager uses. There is no Notion password, no workspace-wide key that could read everything, and no access to pages you have not shared. The sharing list decides what the integration can read. Notion applies the same rule to every other tool. Revoke the integration in Notion and every future run fails immediately.
Then the API decides what is possible
The Notion API is a read-oriented, paginated interface to blocks and pages. It returns results in pages of at most a hundred items and limits how many requests you can send per second. It returns in full what it can represent. For anything it cannot represent, it reports the block without its content rather than guessing.
Pagination, rate limits and missing content shape the design of any Notion backup. A backup is therefore not one request. It is a paced traversal, and on a large workspace it can take minutes, ten minutes or even longer. NotionManager shows live progress, so you know where the copy has got to.
Notion also keeps updating the API to fix faults, add capabilities and improve how it organises data. NotionManager is built on the newest version of the API, so a backup captures as much information as it can.
The data model a backup copies
Everything in Notion is built from blocks. A paragraph, a heading, a to-do, a toggle and a table row are all blocks. A page is a block that contains other blocks, so everything you read in Notion is a tree of blocks. A backup reads that tree the same way: start at a node, read its children, repeat.
A database is a container for pages. Its content lives in one or more data sources, and each row of a data source is a page whose properties that data source defines. A view holds no data of its own. It defines how you look at the data: which data source, which filters and sort order, and whether it appears as a table, a board, a calendar or a gallery. The Notion API returns the key structure of a view, and no styling.
How NotionManager reads a workspace
One traversal from the top down, and it continues until the API returns no more results.
- 1
Start from what you shared
The integration token exposes the top-level pages and databases you shared with it. Those are the roots of the walk.
- 2
Read each one in full
NotionManager fetches every root with its properties and its blocks, page by page until the pagination runs out, so nothing is missed.
- 3
Follow the children down
It fetches every child page found on the way in turn, recursively, until there are no more child pages.
- 4
Rebuild the structure, then read it
NotionManager renders what it read back into pages, databases and relations. The result is a read-only copy you can browse offline, close in feel to Notion itself, instead of a pile of JSON.
What the API will not do, and what happens instead
| Limit of the Notion API | What NotionManager does about it |
|---|---|
| The API rate-limits requests, so a backup takes longer | NotionManager paces its requests and waits when it hits a limit, so the copy stays complete |
| The API reports some block types without their contents | The copy keeps every piece of raw data it can read, and the rendering marks the missing parts, so the gap is visible instead of silent |
| Complex view styling: colours, layout, grouping, the board or gallery you actually look at | NotionManager copies the data behind the view and rebuilds the view from its properties, mimicking Notion as closely as it can |
| No change feed: the API cannot say "these three pages changed since Tuesday" | Incremental and differential backup are not available yet, so every run walks every page and every block. A block that has not changed takes no extra disk space, and NotionManager keeps external media files deduplicated, so disk use stays under control |
| No write-back: the API cannot restore a workspace for you | Backup restore is not supported directly. Every backup tool that claims to restore rebuilds the workspace completely, and it carries severe limits: new IDs, lost relations. NotionManager does not support restore by design |
| Anything not shared with the integration | Nothing. The copy holds exactly the pages you shared. NotionManager can narrow that further, to a subset of those pages, and it cannot go beyond it |
Back up with NotionManager
Create an integration, share a page or a database with it, and watch the first copy appear.
Where to go next
Frequently asked questions
Does NotionManager need my Notion password?
No. It uses an integration token, and that integration can only read what you have explicitly shared with it. There is no workspace-wide credential involved.
Why does a backup take minutes, or longer?
First, the Notion API rate-limits calls strictly, and any attempt to speed a backup up ends in concurrent calls that get throttled. Second, every backup is a full read: the data may not need downloading again, but NotionManager has to walk every page and every block to be sure the copy is complete.
Can it back up only what changed?
The Notion API gives no reliable list of everything that has changed since the last backup. So every run is a full backup, and NotionManager makes sure that repeated data is stored only once.
What happens to blocks the API does not describe?
NotionManager records the declared type of the block and its position in the tree, so the gap is visible in the browsable copy instead of a silent hole in the middle of a page.