Notion publishes an official OpenAPI spec, but not on GitHub — it's served directly from their developer docs at developers.notion.com/openapi.json, the same source that powers their own API reference pages. You can point a generator at it directly. Notion ships one official SDK — @notionhq/client for JavaScript/TypeScript — so a generated client is genuinely useful for any other language, since there's no official Python, Go, or Ruby equivalent.
Where the spec lives
| Fact | Value |
|---|---|
| Source | developers.notion.com/openapi.json — Notion's own docs domain, not GitHub |
| Spec version | OpenAPI 3.1.0, info.version: 1.0.0 |
| Size | ~1.26 MB (JSON) |
| Paths | 48 |
| License | Not stated — no repo, no separate license file |
| Last-Modified | Served with a live Last-Modified header; check it each time you fetch, since there's no git history to diff against |
Unlike every other API in this series, there's no repository to clone, no commit history, and no version tags to pin against — just a live JSON endpoint that Notion updates in place.
How to fetch it
curl -sL -o notion-openapi.json \
https://developers.notion.com/openapi.json
Check the Last-Modified response header if you want to detect when Notion has updated it since your last fetch:
curl -sI https://developers.notion.com/openapi.json | grep -i last-modified
The honest complication: it's 3.1, it's not versioned like the others, and auth needs a header you set yourself
Three things distinguish Notion's spec from every other one in this series:
It's OpenAPI 3.1, not 3.0. Plaid, SendGrid, Cloudflare, DigitalOcean, GitHub, and Stripe are all 3.0.x. Notion's is the only OpenAPI 3.1.0 document here, confirmed by the openapi: field itself. That means real JSON Schema 2020-12 semantics — most current generators handle this fine, but if you're on an older openapi-generator version, test 3.1-specific constructs (type: [string, "null"] unions) before trusting the output; see OpenAPI 3.1 vs 3.0 for what actually changed.
There's no git history to pin to. Every other spec in this series lives in a repo with commits, tags, or dated filenames you can reference. Notion's is a live endpoint — the only way to detect drift is to diff the JSON yourself or watch the Last-Modified header, since there's no changelog file shipped alongside it.
Every request needs a header the spec models but doesn't default. Notion versions its API with a required Notion-Version header on every call, modeled in the spec as a shared notionVersion parameter component referenced from all 48 operations:
grep -A2 "\"notionVersion\"" notion-openapi.json
A generated client will produce a parameter for this on every method, but won't set a default value — you have to pass a current API version string (e.g. 2026-09-03) on every call yourself, or wrap the generated client with one that injects it.
Generate a TypeScript client locally
npx @openapitools/openapi-generator-cli generate \
-i notion-openapi.json \
-g typescript-fetch \
-o ./generated/notion-client
For types only:
npx openapi-typescript notion-openapi.json -o ./src/notion-api.d.ts
Run the file through the free OpenAPI validator first — with a 3.1 spec, that's also the fastest way to confirm your toolchain actually understands the dialect before you commit to a generator.
The hosted path
Sourced takes the Notion spec directly — paste https://developers.notion.com/openapi.json or connect a repo if you've vendored a copy — and produces hosted docs, a TypeScript SDK preview, a Python SDK preview (genuinely useful here, since Notion has no official Python SDK), and an llms.txt file in one pass. Previews are free and unlimited, with up to two hosted noindex docs sites and one hosted MCP server, no credit card required.
When this actually makes sense
- Any language other than TypeScript/JavaScript. Notion's only official SDK is
@notionhq/client. Python, Go, Ruby, Rust — all of them are either community-maintained or nonexistent, making a generated client more central here than for vendors with broad official coverage. - Wrapping the
Notion-Versionheader centrally. Since generated clients don't default it, building a thin wrapper that pins the version once is close to mandatory regardless of language. - Agent tooling. A generated client, or an MCP server built from the spec — Notion also publishes its own official MCP server, worth checking before you build your own agent-facing layer.
- Tracking Notion's API surface over time, given there's no git history — a generated client's diffs between regenerations are your changelog.
If you're writing JavaScript or TypeScript against Notion, use @notionhq/client — it's official, handles pagination helpers, and already sets a sane default API version.
FAQ
Does Notion have an official OpenAPI spec?
Yes, though it's not on GitHub like most vendors in this series. Notion serves it live from developers.notion.com/openapi.json, the same source powering their own API reference documentation.
Is the Notion OpenAPI spec OpenAPI 3.0 or 3.1?
3.1.0 — the only spec in this series that isn't 3.0.x. See OpenAPI 3.1 vs 3.0 for what that changes in practice.
Why doesn't my generated Notion client set the API version automatically?
Notion requires a Notion-Version header on every request, modeled in the spec as a shared parameter rather than a fixed default. Generated clients will expose it as a parameter you must pass yourself — wrap the client to inject a pinned value if you don't want to pass it on every call.
Does Notion have official SDKs for languages other than JavaScript?
No — @notionhq/client is Notion's only official SDK. Python, Go, and other languages rely on community projects or generated clients.
How do I know if Notion has updated their OpenAPI spec?
There's no changelog or git history since it isn't hosted in a repo. Check the Last-Modified response header on each fetch, or diff the JSON against your last saved copy.
Can Sourced generate a Python SDK from the Notion spec even though Notion doesn't offer one officially?
Yes — Sourced generates TypeScript and Python SDK previews from any valid OpenAPI 3.0 or 3.1 spec, including Notion's, independent of what the vendor ships officially. Previews are free and unlimited.