Major changes and highlights from v4.0.2 to v5.0.0.
2025-09-03, introducing notion.dataSources.* endpoints to manage databases at the data source level and repurposing notion.databases.* endpoints for the database container. #600 #601 #602 #603 #607 #6092022-02-22, and v5 of the SDK is tailored toward 2025-09-03 #600queryDataSources API shape #604additional_data field in API error responses for better diagnostics. #603DataSourceObjectResponse["parent"] now supports the data_source_id variant.page | database to page | data_source.examples/ projects in CI. #602examples/ to TypeScript and committed missing build files. #603 #600[!NOTE] v5.0.0 and
2025-09-03bring fairly major changes to the SDK and to the API schema!You can help us by tracking any friction as you upgrade, as well as any issues or improvement opportunities with the JavaScript → TypeScript changes in the
examples/projects, and filing an issue or opening a pull request for each.
Notion-Version to 2025-09-03 by @ksinder in https://github.com/makenotion/notion-sdk-js/pull/605Full Changelog: https://github.com/makenotion/notion-sdk-js/compare/178b3c083520fbadacb76799a0745a9f44e73a16...v5.0.0-rc.1
NPM link: https://www.npmjs.com/package/@notionhq/client/v/5.0.0-rc.1
Major changes and highlights from v4.0.2 to v5.0.0-rc.0.
2025-09-03, introducing notion.dataSources.* endpoints to manage databases at the data source level and repurposing notion.databases.* endpoints for the database container. #600 #601 #602 #603v5.0.0-rc.0 to reflect breaking and additive changes. #6002022-02-22, and v5 of the SDK is tailored toward 2025-09-03 #600additional_data field in API error responses for better diagnostics. #603DataSourceObjectResponse["parent"] now supports the data_source_id variant.page | database to page | data_source.examples/ projects in CI. #602examples/ to TypeScript and committed missing build files. #603 #600Full Changelog: https://github.com/makenotion/notion-sdk-js/compare/f12b584f8a71ed9c6ad5d73efa3e792bd83c99c0...178b3c083520fbadacb76799a0745a9f44e73a16
Upgrade Guide: https://developers.notion.com/docs/upgrade-guide-2025-09-03
notion.comments.retrieve({...}) endpoint to fetch a comment by its ID; this was previously a hidden and un-documented endpointgrant_type: "refresh_token" with a refresh_token to notion.oauth.token(...)Full Changelog: https://github.com/makenotion/notion-sdk-js/compare/f84957479f2b8d6f17b52972879f3c330c8ae7c0...v4.0.2
View this version on NPM: https://www.npmjs.com/package/@notionhq/client/v/4.0.2
notion.request()Full Changelog: https://github.com/makenotion/notion-sdk-js/compare/f7bfcfd1bc0504022e76751908928f847345dc59...v4.0.1
View this version on NPM: https://www.npmjs.com/package/@notionhq/client/v/4.0.1
properties parameters from CreatePageBodyParameters and UpdatePageBodyParameters in src/api-endpoints.ts.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,
}type pattern with the actual value defined in a sub-object to disambiguate:
{
// ...
"numberId": {
"type": "number",
"number": 24
}
}AnnotationRequestPOST /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 stringdisplay_name to Comment, more extraction refactors and docstrings by @ksinder in https://github.com/makenotion/notion-sdk-js/pull/588
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.abc music language to LanguageRequest.Full Changelog: https://github.com/makenotion/notion-sdk-js/compare/df95f350ce31c198b74e4d19dcfb02405004ec4f...v4.0.0
View this version on NPM: https://www.npmjs.com/package/@notionhq/client/v/4.0.0
Full Changelog: https://github.com/makenotion/notion-sdk-js/compare/0e38438c35307f0dc24ad465038fbaca8e8123b3...v3.1.3
View this version on NPM: https://www.npmjs.com/package/@notionhq/client/v/3.1.3
max_file_upload_size_in_bytes field to User response by @ksinder in https://github.com/makenotion/notion-sdk-js/pull/570Full Changelog: https://github.com/makenotion/notion-sdk-js/compare/194f06ddc3e520b1ac42268456aa9cad42e8a4c8...v3.1.2
View this version on NPM: https://www.npmjs.com/package/@notionhq/client/v/3.1.2
Full Changelog: https://github.com/makenotion/notion-sdk-js/compare/f8bb1d0c9b9087c9e7c12d993320035084d030db...v3.1.1
View this version on NPM: https://www.npmjs.com/package/@notionhq/client/v/3.1.1
src/api-endpoints.ts/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-dataFormData parameter passing logic in src/Client.ts for the Send File Upload APIexamples/intro-to-notion-api/intermediate/5-upload-file.js example of using the File Upload API to upload and attach a fileFull Changelog: https://github.com/makenotion/notion-sdk-js/compare/f2e166522a1df34fce8075299a09a6c500e25f4a...v3.1.0
View this version on NPM: https://www.npmjs.com/package/@notionhq/client/v/3.1.0
width_ratio parameter and field on column Blocks by @ksinder in https://github.com/makenotion/notion-sdk-js/pull/561api-endpoints types from src/index.ts by @ksinder in https://github.com/makenotion/notion-sdk-js/pull/562Full Changelog: https://github.com/makenotion/notion-sdk-js/compare/8b867fdc7058e015ceef30c1986b61476bd86280...v3.0.1
View this version on NPM: https://www.npmjs.com/package/@notionhq/client/v/3.0.1
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.
src/api-endpoints.ts by @ksinder in https://github.com/makenotion/notion-sdk-js/pull/558
InternalFileRequest, ExternalFileRequest, and InternalOrExternalFileWithNameRequestblock_idcd command by @crosskayla in https://github.com/makenotion/notion-sdk-js/pull/493Full Changelog: https://github.com/makenotion/notion-sdk-js/compare/650d23bd94c1cd9a4179fcbea25be617e2f5a7e5...v3.0.0
View this version on NPM: https://www.npmjs.com/package/@notionhq/client/v/3.0.0
oauth/revoke and oauth/introspect token endpoints
by @ksinder in https://github.com/makenotion/notion-sdk-js/pull/552Full Changelog: https://github.com/makenotion/notion-sdk-js/compare/b7f3de8563bd566cb3a0cea421aa1a82f2be9e46...v2.3.0
View this version on NPM: https://www.npmjs.com/package/@notionhq/client/v/2.3.0
LinkMentionResponse by @ksinder in https://github.com/makenotion/notion-sdk-js/pull/550: title, description, link_author, link_provider, thumbnail_url, icon_url, iframe_url, height, padding, padding_topFull Changelog: https://github.com/makenotion/notion-sdk-js/compare/eed58030649895b95ab9b97e2959f77bab19cd62...v2.2.17
View this version on NPM: https://www.npmjs.com/package/@notionhq/client/v/2.2.17
link_mention and custom_emoji types, which are surfaced in various places (page, database, mention rich text item responses; block object requests)ApiColor of default_background"ascii art", "hcl", and "smalltalk" to LanguageRequestFull Changelog: https://github.com/makenotion/notion-sdk-js/compare/7950edc034d3007b0612b80d3f424baef89746d9...v2.2.16
in_trash field to request and response bodydescription field to database propertiesPartialSelectResponse to be used for select propertiesNow createDatabase and updateDatabase allow creating unique ID properties and getDatabase will now return unique ID properties.
Support querying databases by unique ID.