notion-client requests now 403 (Cloudflare) because no User-Agent is sent — workaround: pass one via ofetchOptions

[danielrose7]

Summary

As of early August 2026, Cloudflare in front of www.notion.so rejects api/v3 requests that carry no User-Agent header with a 403 (Cloudflare HTML block page). notion-client's fetch sets only Content-Type, and Node's undici adds no default UA, so every server-side call from Node fails.

This silently breaks any SSR/SSG/CI usage of notion-client — the same code that worked for years starts returning 403 with no library change.

Environment

• notion-client 7.10.0 (latest)
• Node 24 (undici fetch), reproduced both locally and on Vercel serverless

Reproduction

Same page ID, same endpoint, same request body — the UA header is the only variable:

Request	Result
notion-client as-is (no User-Agent)	403, Cloudflare HTML block page (~95ms)
Same payload + curl/8.7.1 UA	200
Same payload + browser UA	200

Minimal repro without the library:

// 403:
await fetch('https://www.notion.so/api/v3/loadPageChunk', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ pageId, limit: 100, cursor: { stack: [] }, chunkNumber: 0, verticalColumns: false }),
})

// 200 — identical except for the UA header:
await fetch('https://www.notion.so/api/v3/loadPageChunk', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'User-Agent': 'Mozilla/5.0 ...' },
  body: /* same */,
})

Notion's status page shows no incident — this is bot protection on the unofficial private API, not an outage.

Workaround

ofetchOptions on the constructor merges into every request the client makes, so no library change is needed to unblock:

const notion = new NotionAPI({
  ofetchOptions: {
    headers: {
      'User-Agent':
        'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36',
    },
  },
})

Any non-empty realistic UA works (curl's does too).

Proposed fix

Have notion-client send a default User-Agent (overridable via ofetchOptions) so requests work out of the box again. Happy to send a PR if maintainers agree with the approach.

Possibly related

• Pre-rendering pages on Github Actions causes 403 Error #487 "Pre-rendering pages on Github Actions causes 403" (2023) — CI runners also use UA-less Node fetch, so it's plausibly the same root cause; the workaround above may fix it too.

[danielrose7]

Addendum — the rule isn't "empty UA" alone, it's client fingerprint + UA:

While testing UA variants, I found that curl with its User-Agent stripped entirely (-H 'User-Agent:') consistently gets a 200 — while Node's undici fetch without a UA consistently gets the 403, same payload, same machine, run back-to-back (3 rounds each):

Client	User-Agent	Result
Node (undici)	none	403 Cloudflare block, every time
Node (undici)	NotionX	200, real recordMap
Node (undici)	browser string	200, real recordMap
curl	none	200 (6/6 attempts)

So Cloudflare appears to be targeting Node's TLS/client fingerprint combined with a missing User-Agent, not the missing header by itself. For notion-client's purposes the conclusion is unchanged — within Node the UA header is exactly the switch — but it strengthens the proposed fix: any non-empty UA works, including a library-identifying one (e.g. notion-client/7.10.0), so a default UA wouldn't need to impersonate a browser.

[mfts]

Thanks for the quick write-up. I noticed it as well.

[cmdli]

Hey, Notion engineer here. We've been decommissioning the www.notion.so domain used by this library in favor of the newer and official notion.com domain. I would recommend updating to use the new notion.com domain since we can't guarantee how long www.notion.so will keep working.

[Souler]

Following up on @cmdli suggestion, another workaround that did it for us was passing a apiBaseUrl when initializing NotionAPI:

const notion = new NotionAPI({
  apiBaseUrl: 'https://app.notion.com/api/v3',
})

However, I do also believe notion-client should pass a recognizable UA by default (which could be overriden via ofetchOptions.headers if needed).

Edit: I have decided to open two PRs with the mentioned changes #711 and #712.