> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://notion.ferndocs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://notion.ferndocs.com/_mcp/server. # Historical changelog > **Warning** > > View the current [Changelog](/page/changelog) for the newest updates > This page is a historical archive of updates older than September 2023. This is kept separate from the current changelog to keep page navigation faster while retaining older updates. ## September 5, 2023 # August 23 - September 5, 2023 - The [Working with databases guide](/docs/working-with-databases) was revised to improve its readability and to make additional resources easier to find. - Notion's [Postman collection](https://www.postman.com/notionhq/workspace/notion-s-api-workspace/collection/15568543-d990f9b7-98d3-47d3-9131-4866ab9c6df2) for the API was updated. Be sure to pull recent changes into your forked version. - A reminder was added to the [Comments endpoints](/reference/create-a-comment) to update [integration capabilities](/reference/capabilities) for comments prior to using the endpoints. (Read/write comment capabilities are off by default and can be turned on in the [integration dashboard](https://www.notion.so/my-integrations).) - General clean-up and improvements, including code formatting. ## August 22, 2023 # August 8 - August 22, 2023 - The [Build your first integration](/docs/create-a-notion-integration) guide was rewritten with new demo code to help developers learn how to use Notion's API even faster. - A new [sample app](https://github.com/makenotion/notion-sdk-js/tree/main/examples/web-form-with-express) was added to the [Notion SDK for JavaScript](https://github.com/makenotion/notion-sdk-js/tree/main) `/examples` directory. This completed sample app is referenced in the new [Build your first integration](/docs/create-a-notion-integration) guide. - The description for the `block_id` path parameter was updated for the [Append block children](/reference/patch-block-children) endpoint to indicate that a block ID or page ID can be used. - A clarification was added to [documentation](/reference/retrieve-a-database) for retrieving/updating database properties: If a property is based on a relation to another database, the related database also needs to be shared with the integration. - A clarification was added to documentation for [querying databases](/reference/post-database-query-filter#multi-select). When filtering a multi-select property, the `contains` field will filter for exact matches for the string provided. - The [Working with comments](/docs/working-with-comments) guide was updated with additional examples to distinguish between creating page comments and inline discussion comments. - The [Create a comment](/reference/create-a-comment) endpoint description now links to the Working with comments guide to help developers find additional resources faster. - If you haven't already, join our [Notion Devs Slack group](https://join.slack.com/t/notiondevs/shared_invite/zt-20b5996xv-DzJdLiympy6jP0GGzu3AMg) to learn from other developers building with the public API. ## Notice for an upcoming Public API change ### We will soon be rolling out changes to the Formulas property (Formulas 2.0), and as such, we will be making a change to the Notion Public API This is a non-versioned change and is expected to be in effect in the next couple weeks. **tl;dr:** As part of the Formulas 2.0 rollout, the Public API's format of the string value for [`formula.expression`](/reference/property-object#formula) will be changing. Public API calls with formula inputs in the old format will still succeed. On write operations, the old format will be supported indefinitely, but on read, only the new format will be returned. This change is being made to improve the formulas experience and ensure parity with the Notion app. No action is required for creating or updating database formulas. Reading database [`formula.expression`](/reference/property-object#formula) values may require developer changes. ### What do you need to know? **The string value of `formula.expression` is changing; the schema is not.** - **On write** via the Public API ([create](/reference/create-a-database) or [update](/reference/update-a-database) database endpoints), Notion will support using the old format as a Public API input in the formula property schema indefinitely *and* will support writing in the **new** format. - Database objects returned via the Public API will have the new formulas 2.0 format. **`JavaScript`** ```JavaScript JavaScript // Old format "Updated price": { "id": "YU%7C%40", "name": "Updated price", "type": "formula", "formula": { "expression": "prop(\"Price\") * 2" } } // New format (upcoming) "Updated price": { "id": "YU%7C%40", "name": "Updated price", "type": "formula", "formula": { "expression": "{{notion:block_property:BtVS:00000000-0000-0000-0000-000000000000:8994905a-074a-415f-9bcf-d1f8b4fa38e4}}/2" } } ``` ### Why is this happening? Notion databases allow you to build a fully customizable system for you and your team – they provide a place where you can keep all your information in one place, with the ability to build views, filters, and workflows that can be adapted to your needs. The formula property helps you take that even further – allowing you to perform calculations, create specialized views, and provide an extra layer of insight based on information in other database properties. It helps expand what you can do in Notion databases. We are improving the formulas experience so that: 1. It's easier to write formulas. 2. Formula outputs look and feel more native to Notion. 3. The formula language can fulfill more specific needs. Changes being made to the API are to ensure parity with the Notion app. ### What do you need to do? This is a non-versioned change that will not affect most developers. As mentioned, the formula property format will still have the same schema in the Public API; only the value of the `formula.expression` field will change. Keep an eye on this changelog for when the update becomes available in the Public API. ## August 7, 2023 # July 25 - August 7, 2023 - Notion is excited to announce our [Technology Partnership Program](https://www.notion.so/technology-partner-program). 🎉 This program is open to companies who have built a public integration (including Link Previews) and are interested in improving and scaling their integration with Notion's support. If you think your integration and company could be a fit, [learn more and apply here](https://www.notion.so/technology-partner-program). - We've updated our API reference docs to include information on Notion's [wiki databases and verified pages](https://www.notion.so/help/wikis-and-verified-pages). Updates include: - An overview on wikis in the guide to [working with databases](/docs/working-with-databases#properties). - The [`verification`](/reference/page-property-values#verification) page property was added to the [Page properties](/reference/page-property-values) documentation. - The [Create a database](/reference/create-a-database) and [Query a database](/reference/post-database-query) endpoint documentation was updated to reflect API changes related to wikis. Namely, that querying wiki databases can return both [Page](/reference/page) and [Database](/reference/database) objects. - The [Error codes](/reference/status-codes#error-codes) section in the [Status code](/reference/status-codes) page was updated to include examples of the `"message"` returned with each type of API error, as well as descriptions of the issue each error code represents. - A number of sample cURL commands in our docs were still using an old [Notion Version](/reference/versioning) in their headers. These have all been updated. - A clarification was added to the [Authorization guide](/docs/authorization#making-api-requests-with-an-internal-integration) that the [Notion Version](/reference/versioning) is always required in public API request headers. ## December 5, 2022 # Changes for November 22 - December 5, 2022 We took advantage of the US Thanksgiving holiday to host a mini internal hackathon. Nothing to share from that, yet! It’s been a quiet few weeks. If you want something to read while you stay tuned for the next update, check out the revised [Get started](/docs/getting-started) guide. ## November 21, 2022 # Changes for November 8 - 21, 2022 Check out the latest updates from the Notion API team. - We added a `this_week` filter for database queries. You can now search for database entries where the `"date"`, `"created_time"`, or `"last_edited_time"` property value falls within the current week. Refer to the [date filter condition](/reference/post-database-query-filter#date-filter-condition) docs for details. ## November 7, 2022 # Changes for October 25 - November 7, 2022 Read on for the latest updates to the Notion API. - Number database properties now support the Singapore dollar as a currency format. To use it, set `"singapore_dollar"` as the value for a number’s `format` field when creating or updating a database [property](/reference/property-object#number-configuration) or [schema](/reference/property-schema-object#number-configuration). ## October 24, 2022 # Changes for October 11 - 24, 2022 Check out some new things that you can do with the Notion API. - You can now add a Notion template option to a public integration from the [integration’s settings page](https://www.notion.so/my-integrations). For details on what the permissions flow looks like for users who opt in to the template, refer to the [Authorization guide](/docs/authorization#permissions-flow-for-integrations-with-a-notion-template-option). ## October 11, 2022 # Changes for September 26 - October 10, 2022 Read on for our latest updates. - A [`relation`](/reference/property-value-object#relation-property-values) property value now includes a `has_more` property when returned by the [Retrieve a page endpoint](/reference/retrieve-a-page). `has_more` is `true` if the `relation` has more than 25 page references. Otherwise, `has_more` is `false`. - We added a `workspace_name` property to [bot user objects](/reference/user#bots). If the bot  `owner.type` is `"workspace"`, then `workspace.name` identifies the name of the workspace that owns the bot. If the `owner.type` is `"user"`, then `workspace.name` is `null`. ## September 27, 2022 # Changes for September 12 - 25, 2022 Started an experiment to improve [search endpoint](/reference/post-search) performance by tweaking how we call Elasticsearch under the hood. ## September 11, 2022 # Changes for August 29 - September 11, 2022 Read on for the latest bug fixes and performance improvements. * Fixed a bug where date mentions ended in a `→` character even if they only represented a single date, not a date range. * Added an `Authorization URL` field to the public integration form. You can now click to copy the URL that allows users to authorize your integration (read more in the [Authorization guide](/docs/authorization#prompting-users-to-add-an-integration)). * Corrected an error that caused the [`getProperty` endpoint](/reference/retrieve-a-page-property) to return only one item if the `property_id` belonged to a multi-item [`Files`](/reference/property-item-object#files-property-values) page property. ## August 31, 2022 # Version 2022-06-28 includes page property types and values Responses for page retrievals, database queries, and searches will again include page property types and values. This matches the behavior in version `2022-02-22` and takes effect on August 31, 2022. ## August 29, 2022 # Changes for August 15 - 28, 2022 Read about our new changes below. ### Features * The public API now supports the following functionality for `status` properties: * Reading and updating `status` properties on pages ([read more](/reference/property-value-object#status-property-values)) * Reading, but not updating, `status` property configuration on databases ([read more](/reference/property-object#status-configuration)) * Filtering or sorting by `status` properties when querying databases ([read more](/reference/post-database-query-filter#status-filter-condition)) * `header_1`, `header_2`, and `header_3` blocks now have an `is_toggleable` property, to better indicate whether they are heading toggle blocks. ([read more](/reference/block#heading-one-blocks)) * Headings can be togglified and un-togglified by setting `is_toggleable` to true or false, but note that all the children inside the toggle must be removed before it can be untogglified. ## August 15, 2022 # Changes for August 1 - 14, 2022 No updates for these past 2 weeks, but stay tuned for the next changelog! ## August 1, 2022 # Changes for July 18 - July 31, 2022 Read about our new changes below. ### Features * Added support for [reading](/reference/retrieve-a-comment) and [writing](/reference/create-a-comment) page-level comments in the API. ## July 21, 2022 # Changes for July 5 - 17, 2022 Read about our new changes below. ### Features * Released a new version of the API, `2022-06-28`. Previous versions of the API are still supported. Read more about the new version [here](/changelog/releasing-notion-version-2022-06-28). * Created a new template repository for getting started with the Notion API and the official SDK. [Find it here.](https://github.com/makenotion/notion-sdk-typescript-starter) ### Bug fixes and performance improvements * Exported many more named types for API response objects in the [official SDK](https://github.com/makenotion/notion-sdk-js). * Fixed a bug in the official SDK where some API requests would not work due a capitalization issue. (This was a community-submitted PR; thank you @dvanoni!) ## July 19, 2022 # Comments API Today we're launching a brand new set of APIs for interacting with Notion comments. This includes the ability to: - Read comments from a page or block. - Add a comment to a page. - Add a comment to an existing discussion thread on a block. For more information, check out the new [guide](/docs/working-with-comments) or dive straight into the [API reference](/reference/create-a-comment). ## July 6, 2022 # Releasing Notion-Version 2022-06-28 **Update from August 31, 2022**: Page properties can now be retrieved using the page, query database, and search endpoints, in addition to the page properties endpoint. Today we’re releasing Notion-Version `2022-06-28` with the following backwards incompatible changes: * Page properties must be retrieved using the page properties endpoint. * Parents are now always direct parents; a parent field has been added to block. * Database relations have a type of `single_property` and `dual_property`. Read more about each of these changes below. ### Page properties must be retrieved using the page properties endpoint Previously, the [page object](/reference/page) returned from page endpoints, as well as the query database and search endpoint, returned a `properties` field that contained all the page’s properties along with its value: **`JSON`** ```json JSON "properties": { "Name": { "id": "title", "type": "title", "title": [ { "type": "text", "text": { "content": "Avocado", "link": null }, "annotations": { "bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default" }, "plain_text": "Avocado", "href": null } ] } } ``` While convenient, returning accurate results for all properties resulted in bad performance and timeouts for larger databases or pages with lots of mentions. To combat performance, on March 1st, we [added a disclaimer](/reference/property-value-object) that page objects stopped returning accurate results for pages with more than 25 mentions to other objects (which affected properties of type `title`, `rich_text`, `relation`, `people`, `rollup`, and `formula`). In October 2021, [we introduced](/changelog/retrieve-page-property-values) a way to more accurately retrieve individual page properties via the [retrieve a page property item endpoint](/reference/retrieve-a-page-property). With this endpoint, we’re able to paginate complex properties that involve additional look-ups. With version `2022-06-28`, the `type` and `property` value from page objects are removed. Thus moving forward, all property value retrieval must happen through the retrieve a page property item endpoint. **`JSON`** ```json JSON "properties": { "Name": { "id": "title" } } ``` For more examples of how to use the retrieve a page property item endpoint, our [SDK examples](/page/examples) have been updated to use the retrieve a page property item endpoint. For more details about why page properties are so complex, we wrote about it in our [“Creating the Notion API”](https://www.notion.so/blog/creating-the-notion-api) blog post. ### Parents are now always direct parents; a parent field has been added to block Previously, when accessing the parent of a database or page, that parent was always either a page, database, or workspace. This is un-faithful to the actual data model of Notion, where the parent may also be another block; for example, you can nest a page under a toggle block. The parent field for page and database has been changed so that it is now always the direct parent of that page or database, and a new parent type has been added: `block_id`. Additionally, a `parent` field has been added to the block object. Together, these changes allow you to fully traverse Notion’s tree. To emulate the previous behavior of retrieving the page, database, or space parent, you may traverse up the tree using the retrieve a block endpoint. If the parent ≠ one of those types, retrieve the parent block until it is. Read more about parent types [here](/reference/parent-object). ### Database relations have a type of `single_property` and `dual_property` Relation properties in databases objects now have a type of `single_property` or `dual_property`. These can be used to create one way relations between databases as well as two way relations within a database. ### New version of the JavaScript SDK Coinciding with all of these changes, we've released a new major version (v2.0.0) of the [Notion JavaScript SDK](https://github.com/makenotion/notion-sdk-js). To upgrade to this new version, run `npm install @notionhq/client@latest` or `yarn upgrade --latest @notionhq/client` from within your repository. ## June 23, 2022 # Changes for June 20 - July 4, 2022 Read about our new changes below. ### Features - Added limited readonly support for database status properties. Read more about status properties [here](https://www.notion.so/help/guides/status-property-gives-clarity-on-tasks). - Status property values are returned in the [Retrieve a page](/reference/retrieve-a-page) endpoint. See [Property values](/reference/property-value-object) for more information. - Status property configuration is not supported yet. See [Property object](/reference/property-object) for more information. ### Bug Fixes - Added a validation for adding new rollup properties that prevents creating a rollup of another rollup. ## June 22, 2022 # Changes for June 6 - June 19, 2022 Read about our new changes below. ### Features - Added support for creating inline databases with `is_inline`. Read more [here](/reference/database). - Added support for reading and writing database descriptions with the `description` field. Read more [here](/reference/database). ## June 7, 2022 # Changes for May 23 - June 5, 2022 Read about our new changes below. ### Bug fixes and performance improvements - The public API once again supports inline`mailto` links in rich text. _Showing the 20 most recent of 70 entries. Append `/llms.txt` to the changelog URL for the complete index._