> 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. # Releasing Notion-Version 2021-08-16 We're releasing Notion-Version `2021-08-16` with the following *backwards incompatible* changes: * [Unknown Keys Will Fail Validation](#unknown-keys-will-fail-validation) * [Rollup Property Types](#changes-to-array-rollup-property-types) * [Append Block Children](#append-block-children-returns-a-list-of-blocks) * [URL Safe Property IDs](#property-ids-are-now-url-safe) * [Empty Properties Are Now Returned](#empty-database-properties-are-now-returned-as-null) # Unknown Keys Will Fail Validation Previously, our endpoints used to only validate against the expected keys in both request body parameters as well as query parameters resulting in some ambiguity between incorrect behavior and invalid inputs. Going forward, to improve the developer experience we will be raising validation errors if keys that are not supported by our API are passed in to requests. To safely migrate to `2021-08-16`, we recommend thoroughly testing your API calls against the `2021-08-16` version, to see if you get any validation errors due to this change. If you do, remove any parameters that are rejected due to unknown keys. # Changes to Array Rollup Property Types Starting with the Notion-Version header `2021-08-16`, we are introducing a change to the response for rollup properties on a page which are arrays. Number and date rollups are unaffected. Specifically, the `type` of elements within an array rollup has been made consistent with property types across other API endpoints: > **Parameters**: *See API reference documentation for detailed parameters.* An example rollup property value for an array of rich text values, using Notion-Version `2021-08-16`: **`JSON`** ```json JSON { "properties": { "sample text array rollup": { "id": "NXTh", "type": "rollup", "rollup": { "type": "array", "array": [ { "type": "rich_text", "rich_text": [ { "type": "text", "text": { "content": "hello world!", "link": null }, "annotations": { "bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default" }, "plain_text": "hello world!", "href": null } ] }, { "type": "rich_text", "rich_text": [ { "type": "text", "text": { "content": "foo bar", "link": null }, "annotations": { "bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default" }, "plain_text": "foo bar", "href": null } ] } ] } }, } } ``` # Append Block Children returns a list of blocks The [Append Block Children](/reference/patch-block-children) endpoint will now return a list of the newly created [Block object](/reference/block) children. Previously the endpoint returned the block object of the parent block. Developers can instead use the [Retrieve a block](/reference/retrieve-a-block) endpoint to get the full block object for a specified `block_id`. This change allows developers to get `block_id`'s and additional information of the new blocks right after they're created. Note: only the first level block children are returned. To get sub-children, use the [Retrieve block children](/reference/get-block-children) endpoint. **`JSON`** ```json JSON { "object": "list", "results": [ { "object": "block", "id": "9bc30ad4-9373-46a5-84ab-0a7845ee52e6", "created_time": "2021-03-16T16:31:00.000Z", "last_edited_time": "2021-03-16T16:32:00.000Z", "has_children": false, "type": "heading_2", "heading_2": { "text": [ { "type": "text", "text": { "content": "Lacinato kale", "link": null }, "annotations": { "bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default" }, "plain_text": "Lacinato kale", "href": null } ] } }, { "object": "block", "id": "7face6fd-3ef4-4b38-b1dc-c5044988eec0", "created_time": "2021-03-16T16:34:00.000Z", "last_edited_time": "2021-03-16T16:36:00.000Z", "has_children": false, "type": "paragraph", "paragraph": { "text": [ { "type": "text", "text": { "content": "Lacinato kale", "link": { "url": "https://en.wikipedia.org/wiki/Lacinato_kale" } }, "annotations": { "bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default" }, "plain_text": "Lacinato kale", "href": "https://en.wikipedia.org/wiki/Lacinato_kale" }, { "type": "text", "text": { "content": " is a variety of kale with a long tradition in Italian cuisine, especially that of Tuscany. It is also known as Tuscan kale, Italian kale, dinosaur kale, kale, flat back kale, palm tree kale, or black Tuscan palm.", "link": null }, "annotations": { "bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default" }, "plain_text": " is a variety of kale with a long tradition in Italian cuisine, especially that of Tuscany. It is also known as Tuscan kale, Italian kale, dinosaur kale, kale, flat back kale, palm tree kale, or black Tuscan palm.", "href": null } ] } } ], "next_cursor": null, "has_more": false } ``` # Property IDs are now URL Safe Endpoints that return property IDs as part of the response body will now return new URL safe encoded property IDs. Any request that uses property IDs (such as [Update a database](/reference/update-a-database) or [Update a page](/reference/patch-page)) should use the new URL safe ID. This ensures all property IDs can be referenced in the URL of any new endpoints moving forward. > **Parameters**: *See API reference documentation for detailed parameters.* # Empty database properties are now returned as `null` Previously, empty properties of date, email, number, and rollup types were omitted from the page response. Now, these empty properties are returned with `null` values. **`JSON`** ```json JSON { "object": "page", "id": "a8b7e96d-22ce-44d8-991f-6c4535af6608", "created_time": "2021-05-12T06:16:00.000Z", "last_edited_time": "2021-08-12T21:36:00.000Z", "cover": null, "icon": null, "parent": { "type": "database_id", "database_id": "70ff0393-6b40-4e76-afc4-4a26a9aa1606" }, "archived": false, "properties": { "MyDate": { "id": "GZT~", "type": "date", "date": null }, "Description": { "id": "RPld", "type": "rich_text", "rich_text": [] }, "Food group": { "id": "W_iA", "type": "select", "select": null }, "myRollup": { "id": "%5Eu%3EC", "type": "rollup", "rollup": { "type": "array", "array": [] } }, "MyRelation": { "id": "_pL%3A", "type": "relation", "relation": [] }, "Price": { "id": "dPVb", "type": "number", "number": null }, "MyMultiSelect": { "id": "%7B%40%5Co", "type": "multi_select", "multi_select": null }, }, "url": "https://notion.so/a8b7e96d22ce44d8991f6c4535af6608" } ```