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

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