Automating Notion backups with the API

If you write code, you can build your own Notion backup on the official API. Plenty of people do, and it's a reasonable weekend project. This guide is an honest map of what's involved — including the parts that look small and aren't.

The basic shape

At its core, an API backup is a loop:

1. Authenticate with an internal integration token.
2. List the pages and databases the integration can see.
3. For each page, fetch its block tree (children, recursively).
4. Convert the blocks to a format you want — Markdown is the usual choice, via a library like notion-to-md.
5. Write the files somewhere durable.
6. Run the whole thing on a schedule.

The first version of this is genuinely not hard. A script that dumps a handful of pages to Markdown might take an afternoon.

The parts people underestimate

The gap between "works on my pages" and "I trust it with the whole workspace" is where the time goes:

• Pagination. Pages, databases, and block children all paginate. Miss it and you silently truncate large pages.
• Rate limits. The API caps requests. A big workspace means backoff, retries, and a job that takes a while.
• Expiring media URLs. File and image URLs from the API are signed and expire. To keep a usable backup you must download and re-host the media, not just store the link.
• Nested everything. Toggles, synced blocks, and subpages nest arbitrarily. Your recursion has to handle depth and cycles.
• Databases. Properties, relations, and rollups need deliberate handling to come out as something readable.
• Scheduling and alerting. A backup that fails silently is worse than no backup, because you think you're covered. You need a scheduler and a way to find out when a run breaks.

A realistic cost estimate

Budget a weekend for a version that handles your current workspace, and a few evenings a year for the maintenance — API changes, an expired token, a run that started failing two weeks ago. That's a fine trade if backups are something you enjoy owning. It's a bad trade if you just want the files to be there.

When to buy instead

The build-versus-buy line is simple: if your time is worth more than the maintenance, or if the backup protects something you can't afford to get wrong, a service that already solves pagination, media re-hosting, retries, and scheduling is the better call. That's exactly what Backup Notion does — the same Markdown-first output you'd build, minus the weekend and the yearly upkeep, delivered to storage you own.

If you only need a single page converted occasionally, you don't need the API at all — the free Notion to Markdown converter handles one published page in your browser. The API route is for when you want the whole workspace, on a schedule, without clicking anything — and at that point the honest question is whether you want to maintain it yourself.