Skip to navigation
EndpointsDatabases

Update a database

Deprecated as of version 2025-09-03

This page describes the API for versions up to and including 2022-06-28. In the new 2025-09-03 version, the concepts of databases and data sources were split up, as described in Upgrading to 2025-09-03.

Refer to the new APIs instead:

Updates the database object — the title, description, or properties — of a specified database.

Returns the updated database object.

Database properties represent the columns (or schema) of a database. To update the properties of a database, use the properties body param with this endpoint. Learn more about database properties in the database properties and Update database properties docs.

To update a relation database property, share the related database with the integration. Learn more about relations in the database properties page.

For an overview of how to use the REST API with databases, refer to the Working with databases guide.

How database property type changes work

All properties in pages are stored as rich text. Notion will convert that rich text based on the types defined in a database’s schema. When a type is changed using the API, the data will continue to be available, it is just presented differently.

For example, a multi select property value is represented as a comma-separated list of strings (eg. “1, 2, 3”) and a people property value is represented as a comma-separated list of IDs. These are compatible and the type can be converted.

Note: Not all type changes work. In some cases data will no longer be returned, such as people type → file type.

Interacting with database rows

This endpoint cannot be used to update database rows.

To update the properties of a database row — rather than a column — use the Update page properties endpoint. To add a new row to a database, use the Create a page endpoint.

Developers are encouraged to keep their database schema size to a maximum of 50KB. To stay within this schema size limit, the number of properties (or columns) added to a database should be managed.

Database schema updates that are too large will be blocked by the REST API to help developers keep their database queries performant.

Errors

Each Public API endpoint can return several possible error codes. See the Error codes section of the Status codes documentation for more information.

The following database properties cannot be updated via the API
  • formula
  • select
  • status
  • Synced content
  • A multi_select database property’s options values. An option can be removed, but not updated.
Database relations must be shared with your integration

To update a database relation property, the related database must also be shared with your integration.

Path parameters

database_idstringRequired
identifier for a Notion database

Headers

Notion-VersionstringRequired

The API version to use for this request. The latest version is <<latestNotionVersion>>.

Request

This endpoint expects an object.
titlelist of anyOptional

An array of rich text objects that represents the title of the database that is displayed in the Notion UI. If omitted, then the database title remains unchanged.

descriptionlist of anyOptional

An array of rich text objects that represents the description of the database that is displayed in the Notion UI. If omitted, then the database description remains unchanged.

propertiesstringOptionalformat: "json"

The properties of a database to be changed in the request, in the form of a JSON object. If updating an existing property, then the keys are the names or IDs of the properties as they appear in Notion, and the values are property schema objects. If adding a new property, then the key is the name of the new database property and the value is a property schema object.

Response

200

Errors

400
Bad Request Error
404
Not Found Error
429
Too Many Requests Error