v4.0.1

What's Changed

• Support additional headers passed to notion.request()

Full Changelog: f7bfcfd...v4.0.1

View this version on NPM: https://www.npmjs.com/package/@notionhq/client/v/4.0.1

v4.0.0

What's Changed

• Remove no-op duplicates from union types across all endpoints by @ksinder in #579
• Remove legacy (<=2021) v1 API shape for page properties by @ksinder in #580
  • Removes support for the legacy (pre-Q3-2021) shape for page properties parameters from CreatePageBodyParameters and UpdatePageBodyParameters in src/api-endpoints.ts.
  • This collapses the union type of {old properties shape, new properties shape} down to the new shape only.
  • In the old shape, properties was a fairly ambiguous Record<string, ...> mapping each property key to the property value (a union type across all possible property types' values) e.g.

    {
      // ...
      "numberId": 24,
    }

  • In the new shape (the only one we want to support going forward), the value must be wrapped in an object that uses the polymorphic type pattern with the actual value defined in a sub-object to disambiguate:

    {
      // ...
      "numberId": {
        "type": "number",
        "number": 24
      }
    }

  • This matches up with our responses in the API read path so most, if not all, integrations are likely already using syntax compatible with the new shape
• chore: add JSDoc comments to API types by @julyou in #585
• Add support for attachments in Comment API by @julyou in #586
• CreatePage: support workspace-level private pages (+ misc param type refactors) by @ksinder in #587
  • No-op refactors/cleanups: extracting some components into separate type aliases, e.g. AnnotationRequest
  • Support the new mode in POST /v1/pages (CreatePage) API where:
    • parent can be omitted, or passed as {"workspace": true}, to create top-level private pages at the workspace level (for public integrations only)
    • properties is also optional. For standalone pages, this results in title defaulting to an empty string
• Sync API endpoints: add display_name to Comment, more extraction refactors and docstrings by @ksinder in #588
  • This includes miscellaneous extraction refactors for named subsets of parameters and other cleanups like new parameter docstrings.
  • The only functional change is adding the new display_name object to the CommentObjectResponse, and some fixes from previous PRs around parenthesizing a & (b | c) in allOf → oneOf OpenAPI types to get the correct result rather than defaulting to the incorrect interpretation (a & b) | c.
• Sync latest API endpoints schema as of 2025-06-30 by @ksinder in #590
  • Most of these are no-op re-ordering of type definitions.
  • Some added and edited comments/docstrings.
  • The only semantic change is adding support for the abc music language to LanguageRequest.

New Contributors

• @julyou made their first contribution in #585

Full Changelog: df95f35...v4.0.0

View this version on NPM: https://www.npmjs.com/package/@notionhq/client/v/4.0.0

v3.1.3

What's Changed

• Add comments and docstrings to several API endpoint schemas by @ksinder in #573
• fix(types): Support browser fetch and remove node-fetch types by @dvanoni in #574

Full Changelog: 0e38438...v3.1.3

View this version on NPM: https://www.npmjs.com/package/@notionhq/client/v/3.1.3

v3.1.2

What's Changed

• Add max_file_upload_size_in_bytes field to User response by @ksinder in #570

Full Changelog: 194f06d...v3.1.2

View this version on NPM: https://www.npmjs.com/package/@notionhq/client/v/3.1.2

v3.1.1

What's Changed

• Updates node/nvm version required by @typeoneerror in #568

New Contributors

• @typeoneerror made their first contribution in #568

Full Changelog: f8bb1d0...v3.1.1

View this version on NPM: https://www.npmjs.com/package/@notionhq/client/v/3.1.1

v3.1.0

What's Changed

• Add support for File Upload API endpoints by @ksinder in #565
  • Sync the latest OpenAPI schema for Notion's Public API to src/api-endpoints.ts
  • Introduce the /v1/file_uploads family of API endpoints (File Upload Create, Get, List, Send, Complete)
    • notion.fileUploads.send builds a FormData object to send fields via multipart/form-data
  • Add several refactors to extract common reused schema components, which drastically reduces the size of the file
• Add file upload API example and fix Blob send logic by @ksinder in #566
  • Fix the FormData parameter passing logic in src/Client.ts for the Send File Upload API
  • Add examples/intro-to-notion-api/intermediate/5-upload-file.js example of using the File Upload API to upload and attach a file

Full Changelog: f2e1665...v3.1.0

View this version on NPM: https://www.npmjs.com/package/@notionhq/client/v/3.1.0

v3.0.1

What's Changed

• Support width_ratio parameter and field on column Blocks by @ksinder in #561
• Export several common api-endpoints types from src/index.ts by @ksinder in #562

Full Changelog: 8b867fd...v3.0.1

View this version on NPM: https://www.npmjs.com/package/@notionhq/client/v/3.0.1

v3.0.0

What's Changed

This update, v2.3.0 → v3.0.0, is marked as a major version upgrade due to the Node minimum version increase to 18, as part of the change to use built-in fetch as the default in the Client constructor instead of node-fetch.

• Sync OpenAPI schema as of 2025-04-08 to src/api-endpoints.ts by @ksinder in #558
  • Refactor common parameter shapes into new types: InternalFileRequest, ExternalFileRequest, and InternalOrExternalFileWithNameRequest
  • Support commenting on a non-page block in the Create Comment API by accepting a parent type of block_id
• Use isomorphic fetch by @sv2dev in #506
  • This updates the minimum Node engine version from 12 to 18.
• Small typo fixes in docs and example files
  • docs: fix incorrect example path in README by @R-jisu in #556
  • Update .env.example by @jtsmith1287 in #532
  • Update README.md with correct cd command by @crosskayla in #493

Full Changelog: 650d23b...v3.0.0

View this version on NPM: https://www.npmjs.com/package/@notionhq/client/v/3.0.0

New Contributors

• @sv2dev made their first contribution in #506
• @R-jisu made their first contribution in #556
• @jtsmith1287 made their first contribution in #532
• @crosskayla made their first contribution in #493

v2.3.0

What's changed

• Introduce client methods and data types for the new oauth/revoke and oauth/introspect token endpoints
  by @ksinder in #552

Full Changelog: b7f3de8...v2.3.0

View this version on NPM: https://www.npmjs.com/package/@notionhq/client/v/2.3.0

v2.2.17

What's changed

• Added previously-missing optional fields to LinkMentionResponse by @ksinder in #550: title, description, link_author, link_provider, thumbnail_url, icon_url, iframe_url, height, padding, padding_top

Full Changelog: eed5803...v2.2.17

View this version on NPM: https://www.npmjs.com/package/@notionhq/client/v/2.2.17