Skip to main content
We’re releasing Notion-Version 2021-08-16 with the following backwards incompatible changes:

Unknown Keys Will Fail Validation

Rollup Property Types

Append Block Children

URL Safe Property IDs

Empty Properties Are Now Returned

​
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.
Migration TipTo 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:
BeforeAfter
type: "file"type: "files"
type: "text"type: "rich_text"
type: "person"type: "people"
An example rollup property value for an array of rich text values, using Notion-Version 2021-08-16:
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 endpoint will now return a list of the newly created Block object children. Previously the endpoint returned the block object of the parent block. Developers can instead use the 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 endpoint.
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 or Update a 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.
BeforeAfter
DoS\DoS%5C
titletitle
vEKnvEKn

​
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
{
    "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"
}