Skip to content

Notion: Update a database

Notion databases.updateDatabase: arguments, response, policy and SDK examples.

← Databases operations · Get started

Operation notion.update_database

Provider route: PATCH /v1/databases/{database_id}. Alter supplies the connection’s credentials and routing.

Install @alter-ai/sdk @alter-ai/notion with npm, or alter-sdk-notion with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { NotionIntegration } from "@alter-ai/notion";
async function execute(input: Parameters<NotionIntegration["databases"]["updateDatabase"]>[0]) {
const app = new App({ apiKey: process.env.ALTER_API_KEY! });
try {
const provider = new NotionIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
const call = await provider.databases.updateDatabase(input);
const result = await call.wait();
return result.bodyJson();
} finally {
await app.close();
}
}
import os
from alter_sdk import App
from alter_sdk_notion import NotionIntegration
async def execute(arguments):
async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
provider = NotionIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
call = await provider.databases.update_database(arguments)
result = await call.wait()
return result.body_json()
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
pathobjectRequired within parentAdditional keys: not allowed
path.database_idstringRequired within parentID of a Notion database, a container for one or more data sources.
bodyobjectRequired within parent
body.coverModelOptionalExpand Create a database — request body — body cover
The updated cover image for the database, if any. If not provided, the cover will not be updated.
body.descriptionarrayOptionalThe updated description of the database, if any. If not provided, the description will not be updated.
Maximum items: 100
body.description[]ModelEach itemExpand Create a database — request body — body title item
body.iconModelOptionalExpand Create a database — request body — body icon
The updated icon for the database, if any. If not provided, the icon will not be updated.
body.in_trashbooleanOptionalWhether the database should be moved to or from the trash. If not provided, the trash status will not be updated.
body.is_inlinebooleanOptionalWhether the database should be displayed inline in the parent page. If not provided, the inline status will not be updated.
body.is_lockedbooleanOptionalWhether the database should be locked from editing in the Notion app UI. If not provided, the locked state will not be updated.
body.parentJSONOptionalThe parent page or workspace to move the database to. If not provided, the database will not be moved.
body.parent (allOf 1)objectAll variants apply
body.parent (allOf 1).typestringRequired within parentThe type of parent.
One of: page_id, workspace
body.parent (allOf 2)JSONAll variants apply
body.parent (allOf 2) (oneOf 1)objectAlternative
body.parent (allOf 2) (oneOf 1).page_idstringRequired within parent
body.parent (allOf 2) (oneOf 1).typestringRequired within parentAlways `page_id`
Must equal: page_id
body.parent (allOf 2) (oneOf 2)objectAlternative
body.parent (allOf 2) (oneOf 2).typestringRequired within parentAlways `workspace`
Must equal: workspace
body.parent (allOf 2) (oneOf 2).workspacebooleanRequired within parentAlways `true`
Must equal: true
body.show_data_source_titlebooleanOptionalWhether to show the data source title above the database’s views. Matches the Show data source title toggle in the Notion app. If not provided, the setting will not be updated.
body.titlearrayOptionalThe updated title of the database, if any. If not provided, the title will not be updated.
Maximum items: 100
body.title[]ModelEach itemExpand Create a database — request body — body title item

Referenced models: Create a database — request body — body cover, Create a database — request body — body icon, Create a database — request body — body title item

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

FieldTypePresenceDescription and constraints
$JSONRoot
$ (anyOf 1)ModelAlternativeExpand Create a database — response body — object database — partial Database Object Response
$ (anyOf 2)ModelAlternativeExpand Create a database — response body — object database — database Object Response

Referenced models: Create a database — response body — object database — database Object Response, Create a database — response body — object database — partial Database Object Response

53 more schemas are linked from the tables above, on the schema pages.

Create a database — response body — object database — database Object Response
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: allowed
coverJSONRequired within parentThe cover of the database.
cover (anyOf 1)ModelAlternativeExpand Update page — response body — object page cover value
cover (anyOf 2)nullAlternative
created_timestringRequired within parentThe time when the database was created.
Format: date-time
data_sourcesarrayRequired within parentThe data sources of the database.
Maximum items: 100
data_sources[]ModelEach itemExpand Create a database — response body — object database data sources item
database_typeJSONRequired within parentThe type of typed database, such as `tasks`, `projects`, or `skills`, or `null` for a regular database. Create a database accepts `tasks`, `projects`, and `skills`.
database_type (anyOf 1)stringAlternativeOne of: `tasks`, `projects`, `sprints`, `docs`, `wiki`, `meetings`, `meeting_notes`, `skills`, `github_prs`
Known values: tasks, projects, sprints, docs, wiki, meetings, meeting_notes, skills, github_prs
database_type (anyOf 2)nullAlternative
descriptionarrayRequired within parentThe description of the database.
Maximum items: 100
description[]ModelEach itemExpand Retrieve a page property item — response body — value Title title
iconJSONRequired within parentThe icon of the database.
icon (anyOf 1)ModelAlternativeExpand Get agent — response body — icon value
icon (anyOf 2)nullAlternative
idstringRequired within parentThe ID of the database.
Format: uuid
in_trashbooleanRequired within parentWhether the database is in the trash.
is_inlinebooleanRequired within parentWhether the database is inline.
is_lockedbooleanRequired within parentWhether the database is locked from editing in the Notion app UI.
last_edited_timestringRequired within parentThe time when the database was last edited.
Format: date-time
objectstringRequired within parentThe database object type name.
Must equal: database
parentModelRequired within parentExpand Create a database — response body — object database parent
The parent of the database. This is typically a page, block, or workspace, but can be another database in the case of wikis.
public_urlJSONRequired within parentThe public URL of the database if it is publicly accessible.
public_url (anyOf 1)stringAlternative
public_url (anyOf 2)nullAlternative
show_data_source_titlebooleanRequired within parentWhether the data source title is shown above the database's views, matching the Show data source title toggle in the Notion app. Full-page databases with one data source don't show this title even when this is `true`.
titlearrayRequired within parentThe title of the database.
Maximum items: 100
title[]ModelEach itemExpand Retrieve a page property item — response body — value Title title
urlstringRequired within parentThe URL of the database.

Referenced models: Create a database — response body — object database data sources item, Update page — response body — object page cover value, Get agent — response body — icon value, Create a database — response body — object database parent, Retrieve a page property item — response body — value Title title

Create a database — response body — object database — partial Database Object Response
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: allowed
idstringRequired within parentThe ID of the database.
Format: uuid
objectstringRequired within parentThe database object type name.
Must equal: database
Create a database — request body — body cover
FieldTypePresenceDescription and constraints
$JSONRoot
$ (oneOf 1)ModelAlternativeExpand Create a database — request body — body cover File Upload
$ (oneOf 2)ModelAlternativeExpand Create a database — request body — body cover External

Referenced models: Create a database — request body — body cover External, Create a database — request body — body cover File Upload

Create a database — request body — body icon
FieldTypePresenceDescription and constraints
$JSONRoot
$ (oneOf 1)ModelAlternativeExpand Create a database — request body — body icon File Upload
$ (oneOf 2)ModelAlternativeExpand Create a database — request body — body icon Emoji
$ (oneOf 3)ModelAlternativeExpand Create a database — request body — body icon External
$ (oneOf 4)ModelAlternativeExpand Create a database — request body — body icon Custom Emoji
$ (oneOf 5)ModelAlternativeExpand Create a database — request body — body icon Icon

Referenced models: Create a database — request body — body icon Custom Emoji, Create a database — request body — body icon Emoji, Create a database — request body — body icon External, Create a database — request body — body icon File Upload, Create a database — request body — body icon Icon

Create a database — request body — body title item
FieldTypePresenceDescription and constraints
$JSONRoot
$ (allOf 1)ModelAll variants applyExpand Create a database — request body — body title item annotations
$ (allOf 2)JSONAll variants apply
$ (allOf 2) (oneOf 1)ModelAlternativeExpand Create a database — request body — body title item value Text
$ (allOf 2) (oneOf 2)ModelAlternativeExpand Create a database — request body — body title item value Mention
$ (allOf 2) (oneOf 3)ModelAlternativeExpand Create a database — request body — body title item value Equation

Referenced models: Create a database — request body — body title item value Equation, Create a database — request body — body title item value Mention, Create a database — request body — body title item annotations, Create a database — request body — body title item value Text

Update page — response body — object page cover value
FieldTypePresenceDescription and constraints
$JSONRoot
$ (anyOf 1)ModelAlternativeExpand Update page — response body — object page cover value File
$ (anyOf 2)ModelAlternativeExpand Update page — response body — object page cover value External

Referenced models: Update page — response body — object page cover value External, Update page — response body — object page cover value File

Create a database — request body — body cover External
FieldTypePresenceDescription and constraints
$objectRoot
externalobjectRequired within parentExternal URL for the cover.
external.urlstringRequired within parentThe URL of the external file.
typestringOptionalAlways `external`
Must equal: external
Create a database — request body — body cover File Upload
FieldTypePresenceDescription and constraints
$objectRoot
file_uploadobjectRequired within parentThe file upload for the cover.
file_upload.idstringRequired within parentID of a FileUpload object that has the status `uploaded`.
typestringOptionalAlways `file_upload`
Must equal: file_upload
List views — response body — view
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: allowed

SDK function policy ID: notion.update_database. Catalog operation: update_database. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Pinned headers: {"Notion-Version": "2026-03-11"}

Official provider source

Report an issue with this page

Necessary

Required for sign-in, security, authorization, and remembering your choices.

Always active

Analytics

Helps us understand which product and documentation features are useful.

Performance diagnostics

Uses performance tracing and privacy-masked session replay to diagnose problems.

You can change these choices at any time from Cookie settings.