View my integrations
Back to All
improved

Releasing Notion-Version 2022-02-22

about 2 years ago by Christine Wang

📘

Notion's API versions

As a reminder, we only version backwards incompatible changes, so generally, you still get access to new features we release on the API without needing to upgrade. You can use different version headers for each request, so you can upgrade incrementally to get to the latest version.

We're releasing Notion-Version 2022-02-22 with the following backwards incompatible changes:

  • text in blocks has been renamed to rich_text, to be consistent with the database property type.
  • Query database filter changes:
    • phone and text are no longer supported in query database filters when filtering by phone_number and rich_text properties. Use phone_number and rich_text instead.
    • rollup query database filters no longer accept the text keyword. Use rich_text instead.
    • formula query database filters no longer accept the text keyword. Use string instead.
  • property_item objects now return a type, next_url, and id.
  • Deprecated the List Databases API endpoint.

The text property in content blocks has been renamed to rich_text

To be consistent with the database property type, we have renamed the text property to rich_text. This affects the following block types: paragraph, heading_1, heading_2, heading_3, callout, quote, bulleted_list_item, numbered_list_item, to_do ,toggle, code ,template.

Here is an example of the previous text property:

{
  "type": "paragraph",
  //...other keys excluded
  "paragraph": {
    "text": [{
      "type": "text",
      "text": {
        "content": "Lacinato kale",
        "link": null
      }
    }]
  }
}

Here is an example of the updated rich_text property:

{
  "type": "paragraph",
  //...other keys excluded
  "paragraph": {
    "rich_text": [{
      "type": "text",
      "text": {
        "content": "Lacinato kale",
        "link": null
      }
    }]
  }
}

Query database filter changes

phone and text no longer supported

Version 2022-02-22 no longer supports phone and text property filters in the query database endpoint. For consistency with the database property types, use phone_number and rich_text instead when filtering on phone_number and rich_text properties.

More concretely, this query database filter will throw a validation error:

{
	"filter": {
		"and": [
			{
				"property": "Phone number",
				"phone": {
					"equals": "1112223333"
				}
			}
		]
	}
}

This query database filter will succeed:

{
	"filter": {
		"and": [
			{
				"property": "Phone number",
				"phone_number": {
					"equals": "1112223333"
				}
			}
		]
	}
}

rollup property filters accept rich_text instead of text

Rollup property filters must now be constructed with the rich_text keyword instead of the text keyword if the value of the rollup is an array of rich_text. Put concretely, if a page's rollup property is rendered like so:

"rollup property": {
	"id": "~%5Bw%5C",
	"type": "rollup",
	"rollup": {
		"type": "array",
		"array": [
			{
				"type": "rich_text",
				"rich_text": [
					{
						"type": "text",
						"text": {
							"content": "update text 2",
							"link": null
						},
						"annotations": {
							"bold": true,
							"italic": false,
							"strikethrough": false,
							"underline": false,
							"code": false,
							"color": "red"
						},
						"plain_text": "update text 2",
						"href": null
					}
				]
			},
			{
				"type": "rich_text",
				"rich_text": [
					{
						"type": "text",
						"text": {
							"content": "another text",
							"link": null
						},
						"annotations": {
							"bold": false,
							"italic": false,
							"strikethrough": false,
							"underline": false,
							"code": false,
							"color": "default"
						},
						"plain_text": "another text",
						"href": null
					}
				]
			}
		],
		"function": "show_original"
	}
}

This filter will no longer work in version 2022-02-22:

{
	"filter": {
		"property": "rollup property",
		"rollup": {
			"any": {
				"text": {
					"contains": "update text"
				}
			}
		}
	}
}

Instead, write:

{
	"filter": {
		"property": "rollup property",
		"rollup": {
			"any": {
				"rich_text": {
					"contains": "update text"
				}
			}
		}
	}
}

formula property filters accept string instead of text

Rollup property filters must now be constructed with the string keyword instead of the text keyword if the value of the formula is a string. Put concretely, if a page's formula property is rendered like so:

"formula property": {
	"id": "m%5D%3F%5C",
	"type": "formula",
	"formula": {
		"type": "string",
		"string": "update text 2,another text"
	}
}

This filter will no longer work in version 2022-02-22:

{
	"filter": {
		"property": "formula property",
		"formula": {
			"text": {
				"contains": "update text"
			}
		}
	}
}

Instead, write this:

{
	"filter": {
		"property": "formula property",
		"formula": {
			"string": {
				"contains": "update text"
			}
		}
	}
}

Property list items now have types

Property item lists now always have type property_item. Rollup aggregations are now returned inside that type.

We've also added the property id field and the next_url to fetch the next set of property items.

Here is an example of a previous rollup property_item list:

{
  "object": "list",
  "results": [
    {
      "object": "property_item",
      "type": "relation",
      "relation": {
        "id": "83f92c9d-523d-466e-8c1f-9bc2c25a99fe"
      }
    },
 		...
  ],
  "next_cursor": "some-next-cursor-value",
  "has_more": true,
  "rollup": {
    "type": "date",
    "date": {
      "start": "2021-10-07T14:42:00.000+00:00",
      "end": null
    },
    "function": "latest_date"
  },
  "type": "rollup"
}

Here is an example of the updated rollup property_item list:

{
  "object": "list",
  "results": [
    {
      "object": "property_item",
      "id": "xYz890",
      "type": "relation",
      "relation": {
        "id": "83f92c9d-523d-466e-8c1f-9bc2c25a99fe"
      }
    },
 		...
  ],
  "next_cursor": "some-next-cursor-value",
  "has_more": true,
  "type": "property_item",
  "property_item": {
    "id": "aBcD123"
    "next_url": "https://api.notion.com/v1/pages/b55c9c91-384d-452b-81db-d1ef79372b75/properties/aBcD123?start_cursor=some-next-cursor-value",
    "type": "rollup",
    "rollup": {
    	"type": "date",
    	"date": {
      	"start": "2021-10-07T14:42:00.000+00:00",
      	"end": null
    	},
    	"function": "latest_date"
		}
  },
  
}

Deprecated the List Databases endpoint

List all Databases endpoint is removed starting in this version. You can use the Search API for this functionality instead. The List Databases endpoint only returns explicitly shared databases, while search will also return child pages and databases within explicitly shared pages.