Enhanced Metadata (Unofficial API)

N2O can optionally use Notion’s internal API — the same API Notion’s own web app uses — to access metadata that Notion doesn’t expose through their official public API. This unlocks a handful of features. It’s completely optional, disabled by default, and degrades gracefully if you don’t enable it.

This page explains exactly what it does, what it costs, and what you’re opting into.

---

What the unofficial API provides

Notion’s official public API (the one you connect with an integration token) is intentionally limited. It doesn’t expose things like:

• Which view is set as the default in a database
• What filters a linked database view applies
• Which database a linked view inside a page points to
• Block-level format metadata (image widths, column ratios, code wrap settings, embed types)

Notion’s internal API (www.notion.so/api/v3/) does expose these. N2O uses two endpoints:

• loadPageChunk — fetches a page’s full block map including format metadata
• syncRecordValuesMain — fetches specific blocks and view configs

What this unlocks

Feature	Without unofficial API	With unofficial API
Bases default view	Uses your global default setting (table/cards/list)	Auto-detects which view Notion has set as default
Linked database view filters	Bases files use no filter, show all items	Bases files are filtered to match what Notion’s linked view shows
Linked view auto-resolution	A modal appears asking you to manually identify the source database	Resolved automatically in the background
Typed embeds	All embeds are generic	Tweets, Figma, Google Maps, CodePen, Excalidraw, etc. detected and preserved
Image/column formatting	Default sizing	Notion’s original widths and column ratios preserved

Everything still works without it — you just lose these enrichments. The sync itself, all block content, all properties, and all Bases generation continue normally.

---

What “token 2” is

To call the internal API, N2O needs your Notion browser session cookie — the token_v2 cookie that Notion’s web app uses to authenticate you.

This is not a separate API key. It’s the same credential your browser uses when you’re logged in to notion.so. It proves to Notion’s servers that requests are coming from an authenticated user.

This is your session credential

The token_v2 cookie grants the same level of access as being logged into Notion in your browser. Anyone with it can read and modify everything your Notion account can access. Treat it like a password.

N2O stores it in Obsidian’s plugin data (local to your device). It is never sent to N2O’s servers — only to www.notion.so directly.

---

How to enable it

In N2O Settings

1. Open N2O Settings → scroll to Enhanced Metadata.
2. Toggle Enable Enhanced Metadata on.
3. Enter your session token (see below).
4. Click Validate to confirm it works.

Getting the token_v2 cookie

On desktop (automatic):

N2O can grab the token automatically from your browser’s cookie store if you’re running Obsidian on desktop. Click Grab Token — N2O reads the token_v2 cookie from Notion’s domain directly. No manual copying needed.

Manually (if automatic doesn’t work):

1. Open notion.so in Chrome or Firefox and log in.
2. Open DevTools (F12 or Cmd+Option+I).
3. Go to Application (Chrome) or Storage (Firefox).
4. Click Cookies → select https://www.notion.so.
5. Find the cookie named token_v2.
6. Copy the full value (it’s long — copy all of it).
7. Paste it into N2O Settings → Enhanced Metadata → Session Token.

Note

The token_v2 value may contain URL-encoded characters (e.g. %3A for :). Paste it as-is — N2O handles decoding.

---

Risks and transparency

This API is unofficial and undocumented. Notion does not support or guarantee its stability. It could change or stop working at any time without warning. When that happens, N2O falls back to the official API automatically — nothing breaks, you just lose the enrichments above.

N2O includes a circuit breaker. If the unofficial API fails 3 times in a sync cycle, it disables itself automatically for the rest of that cycle. This prevents cascading failures from slowing down your sync.

What N2O sends to the unofficial API:

• Your token_v2 session cookie (as an HTTP cookie header)
• Page IDs of the pages you’re syncing
• Block IDs needed for enrichment

What N2O does NOT do:

• Send your token_v2 to N2O’s servers
• Write anything via the unofficial API (it’s read-only)
• Use the unofficial API for authentication (that’s the official token)

Notion’s stance: Notion hasn’t officially permitted or prohibited third-party use of their internal API. Use of it is at your own risk. If Notion changes or locks down this API, N2O will update accordingly.

---

What to expect

When the unofficial API is working, you’ll see richer .base files — filters that match your Notion views, the correct default view pre-selected, and typed embeds. When it’s not (token expired, API changed, network issue), sync continues normally without those enrichments. N2O logs failures at debug level but doesn’t surface them as errors to keep the sync experience clean.

Tokens expire when you log out of Notion in your browser. If enrichment stops working, re-grab the token in settings.