+0
Daily
5,688
stars
715
forks
108
watchers
527
prs
294
issues
99
releases
README
Notion SDK for JavaScript
A JavaScript and TypeScript client for the Notion API. This reference covers the SDK's methods, options, and helpers.
!Build status
Installation
bash
npm install @notionhq/client
Usage
[!NOTE]
For setup steps, see Notion's getting started guide.
Client accepts an integration token or an OAuth access token.
js
const { Client } = require("@notionhq/client")
const notion = new Client({
auth: process.env.NOTION_TOKEN,
})
Make a request to any Notion API endpoint.
js
;(async () = {
const listUsersResponse = await notion.users.list({})
console.log(listUsersResponse)
})()
[!NOTE]
See the complete list of endpoints in the API reference.
Request methods return a Promise with the response. For example:
ts
{
results: [
{
object: "user",
id: "d40e767c-d7af-4b18-a86d-55c61f1e39a4",
type: "person",
person: {
email: "[email protected]",
},
name: "Avocado Lovelace",
avatar_url:
"https://secure.notion-static.com/e6a352a8-8381-44d0-a1dc-9ed80e62b53d.jpg",
},
// ...
]
}
Endpoint parameters are grouped into a single object. You don't need to remember which parameters go in the path, query, or body.
js
const myPage = await notion.dataSources.query({
data_source_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
filter: {
property: "Landmark",
rich_text: {
contains: "Bridge",
},
},
})
Markdown versions
Enhanced Markdown (v1) is deprecated. API versions through 2026-03-11 still default to v1. The next API version will default to v2 and reject requests that specify v1. Notion plans to retire v1 on older API versions about three months after that release.
Set markdown_version: "v2" on Markdown reads and writes now to test your integration before you upgrade. Migrate to Notion-flavored Markdown
js
const { markdown } = await notion.pages.retrieveMarkdown({
page_id: pageId,
markdown_version: "v2",
})
Per-request beta flags
Pass betas to a typed endpoint to opt that call into one or more API betas. The SDK sends the flags in one comma-separated Notion-Beta header. Omitting betas or passing an empty array sends no beta header.
js
await notion.dataSources.query({
data_source_id: dataSourceId,
betas: ["status-group-filters-2026-10-06"],
filter: { property: "Status", status: { group_equals: "In progress" } },
})
This query matches every status option in the “In progress” group. Status group filters beta
TypeScript suggests the current flags known to this SDK. You can also pass a newer flag by its full name and revision date. The API checks whether each flag is valid. Beta versions
Handling errors
Notion API errors reject the request with an APIResponseError. The code property identifies the error. APIErrorCode contains the known server error codes.
js
const {
Client,
APIErrorCode,
isNotionClientError,
} = require("@notionhq/client")
try {
const notion = new Client({ auth: process.env.NOTION_TOTop issues
#457UnknownHTTPResponseError: Request to Notion API failed with status: 50223 comments · 2023-09-26#294Publish Open API spec to allow generation of SDKs for other languages9 comments · 2022-04-28#524No way to query archived/in_trash items5 comments · 2024-08-18#517Image alt text missing from SDK5 comments · 2024-06-15#496I found the Mar 22, 2024 bug. I caused the problem 5 comments · 2024-03-22#478Reading a "Person" property from a database entry returns only the first result4 comments · 2023-12-04#459Remove dependency on node-fetch4 comments · 2023-09-29#425notionhq/client and Next.js 13.4.9 with server action4 comments · 2023-07-17
Latest release
v5.31.1 v5.31.1 2026-11-06What’s changed The SDK ships 1,712 fewer bytes of TypeScript declarations. Page creation and updates share one definition for page properties. Search and data source queries share one definition for list results. 843 Links - Full changelog from v5.31.0 to v5.31.1 - @notionhq/client v5.31.1 on npm