makenotion /notion-sdk-js

Official Notion JavaScript Client

★ 5,688⑂ 715👁 108⑃ 527● 294▤ 99
TypeScriptMITCreated 2021-04-18developers.notion.com/
下载:v5.31.1v5.31.1 ↓5.31.12026-11-06
+0
日增长
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_TO

Top issues

Latest release

v5.31.1 v5.31.1 2026-11-06
What’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

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON