Skip to main content
This page applies to API versions through 2022-06-28. For 2025-09-03 and later, use Update data source properties. See the upgrade guide for the database and data source split.
Retrieve the legacy database to get its property IDs. Send the operation’s JSON body to Update a database, at PATCH /v1/databases/{database_id}. Your connection needs access and update content capabilities. The operations below use the same properties format as data source updates. For legacy relation settings, use database_id instead of data_source_id to identify the target.

​
Add a property

Add a new key to properties and provide the type’s settings. This example adds a number and a date property. Existing properties that you omit stay unchanged.
Request body
See Property schemas for every type and its settings.

​
Remove a property

Set the property entry to null. This removes the column for all pages in the data source. To clear a value on one page instead, use Update page.

​
Rename a property

Set name on the existing entry. Its ID stays the same. Prefer the ID if another user might rename the property while your connection is running.
To update a property’s description, include it beside the type’s settings. Repeat the current description when changing settings if you want to keep it. A rename that sends only name preserves the description.

​
Update property type

Supply the new type’s settings under the existing name or ID.
Change Estimate to a number
Changing a type can make existing values unreadable in the new type. Check the change on a test data source first. The Name property (title) cannot be removed or converted. Other properties cannot become title. Place properties cannot be converted to or from another type.

​
Select configuration updates

Set select.options to the complete list of options you want to keep. Omitted options are removed. New names add options. Omitting options keeps the current list.
When updating select or multi_select settings, include the current property-level description to keep it. Omitting it clears it. This is separate from each option’s description. The examples below assume the property descriptions shown; copy yours from the retrieved schema.
Keep High and add Medium

​
Existing select options

Use an existing option’s id or name to retain it. You can update its description. The API does not rename existing options or change their colors; make those changes in Notion. New options accept name, optional color, and optional description. See Option fields.

​
Multi-select configuration updates

Set multi_select.options using the same rules as select. Include every option to retain. This changes the available tags, not the tags selected on one page.
Keep High and add Launch

​
Existing multi-select options

Existing options follow the same ID, name, color, and description rules.

​
Status configuration updates

Set status.options to the complete list to retain. Use group to place an option in To-do, In progress, or Complete.
Keep In progress and add Shipped

​
Existing status options

Existing options follow the same ID, name, color, and description rules. When you omit group, an existing option keeps its group. A new option uses To-do if that group exists, or the first existing group otherwise. Removed options are also removed from their groups. To rename, reorder, or change the groups themselves, use Notion. To select an option on a page, write the page’s status value.

​
Limitations

Keep schema changes within the schema size limit. Changes to synced data sources are restricted. Share related databases with the connection before configuring relations or rollups. After a change, retrieve the data source again and check the returned names, IDs, and settings. Read a sample page if you changed a property’s type.