Historical changelog

• The Build your first integration guide was rewritten with new demo code to help developers learn how to use Notion’s API even faster.
  • A new sample app was added to the Notion SDK for JavaScript /examples directory. This completed sample app is referenced in the new Build your first integration guide.
• The description for the block_id path parameter was updated for the Append block children endpoint to indicate that a block ID or page ID can be used.
• A clarification was added to documentation 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. When filtering a multi-select property, the contains field will filter for exact matches for the string provided.
• The Working with comments guide was updated with additional examples to distinguish between creating page comments and inline discussion comments.
  • The 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 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 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 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 or update 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.

// 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.