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.
Call through Alter
Section titled “Call through Alter”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 osfrom alter_sdk import Appfrom 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()| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
path | object | Required within parent | Additional keys: not allowed |
path.database_id | string | Required within parent | ID of a Notion database, a container for one or more data sources. |
body | object | Required within parent | |
body.cover | Model | Optional | Expand 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.description | array | Optional | The updated description of the database, if any. If not provided, the description will not be updated. Maximum items: 100 |
body.description[] | Model | Each item | Expand Create a database — request body — body title item |
body.icon | Model | Optional | Expand 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_trash | boolean | Optional | Whether the database should be moved to or from the trash. If not provided, the trash status will not be updated. |
body.is_inline | boolean | Optional | Whether the database should be displayed inline in the parent page. If not provided, the inline status will not be updated. |
body.is_locked | boolean | Optional | Whether the database should be locked from editing in the Notion app UI. If not provided, the locked state will not be updated. |
body.parent | JSON | Optional | The parent page or workspace to move the database to. If not provided, the database will not be moved. |
body.parent (allOf 1) | object | All variants apply | |
body.parent (allOf 1).type | string | Required within parent | The type of parent. One of: page_id, workspace |
body.parent (allOf 2) | JSON | All variants apply | |
body.parent (allOf 2) (oneOf 1) | object | Alternative | |
body.parent (allOf 2) (oneOf 1).page_id | string | Required within parent | |
body.parent (allOf 2) (oneOf 1).type | string | Required within parent | Always `page_id` Must equal: page_id |
body.parent (allOf 2) (oneOf 2) | object | Alternative | |
body.parent (allOf 2) (oneOf 2).type | string | Required within parent | Always `workspace` Must equal: workspace |
body.parent (allOf 2) (oneOf 2).workspace | boolean | Required within parent | Always `true` Must equal: true |
body.show_data_source_title | boolean | Optional | Whether 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.title | array | Optional | The updated title of the database, if any. If not provided, the title will not be updated. Maximum items: 100 |
body.title[] | Model | Each item | Expand 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
Section titled “Response”Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | |
$ (anyOf 1) | Model | Alternative | Expand Create a database — response body — object database — partial Database Object Response |
$ (anyOf 2) | Model | Alternative | Expand 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
Schemas
Section titled “Schemas”53 more schemas are linked from the tables above, on the schema pages.
Create a database — response body — object database — database Object Response
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: allowed |
cover | JSON | Required within parent | The cover of the database. |
cover (anyOf 1) | Model | Alternative | Expand Update page — response body — object page cover value |
cover (anyOf 2) | null | Alternative | |
created_time | string | Required within parent | The time when the database was created. Format: date-time |
data_sources | array | Required within parent | The data sources of the database. Maximum items: 100 |
data_sources[] | Model | Each item | Expand Create a database — response body — object database data sources item |
database_type | JSON | Required within parent | The 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) | string | Alternative | One 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) | null | Alternative | |
description | array | Required within parent | The description of the database. Maximum items: 100 |
description[] | Model | Each item | Expand Retrieve a page property item — response body — value Title title |
icon | JSON | Required within parent | The icon of the database. |
icon (anyOf 1) | Model | Alternative | Expand Get agent — response body — icon value |
icon (anyOf 2) | null | Alternative | |
id | string | Required within parent | The ID of the database. Format: uuid |
in_trash | boolean | Required within parent | Whether the database is in the trash. |
is_inline | boolean | Required within parent | Whether the database is inline. |
is_locked | boolean | Required within parent | Whether the database is locked from editing in the Notion app UI. |
last_edited_time | string | Required within parent | The time when the database was last edited. Format: date-time |
object | string | Required within parent | The database object type name. Must equal: database |
parent | Model | Required within parent | Expand 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_url | JSON | Required within parent | The public URL of the database if it is publicly accessible. |
public_url (anyOf 1) | string | Alternative | |
public_url (anyOf 2) | null | Alternative | |
show_data_source_title | boolean | Required within parent | Whether 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`. |
title | array | Required within parent | The title of the database. Maximum items: 100 |
title[] | Model | Each item | Expand Retrieve a page property item — response body — value Title title |
url | string | Required within parent | The 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
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: allowed |
id | string | Required within parent | The ID of the database. Format: uuid |
object | string | Required within parent | The database object type name. Must equal: database |
Create a database — request body — body cover
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | |
$ (oneOf 1) | Model | Alternative | Expand Create a database — request body — body cover File Upload |
$ (oneOf 2) | Model | Alternative | Expand 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
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | |
$ (oneOf 1) | Model | Alternative | Expand Create a database — request body — body icon File Upload |
$ (oneOf 2) | Model | Alternative | Expand Create a database — request body — body icon Emoji |
$ (oneOf 3) | Model | Alternative | Expand Create a database — request body — body icon External |
$ (oneOf 4) | Model | Alternative | Expand Create a database — request body — body icon Custom Emoji |
$ (oneOf 5) | Model | Alternative | Expand 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
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | |
$ (allOf 1) | Model | All variants apply | Expand Create a database — request body — body title item annotations |
$ (allOf 2) | JSON | All variants apply | |
$ (allOf 2) (oneOf 1) | Model | Alternative | Expand Create a database — request body — body title item value Text |
$ (allOf 2) (oneOf 2) | Model | Alternative | Expand Create a database — request body — body title item value Mention |
$ (allOf 2) (oneOf 3) | Model | Alternative | Expand 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
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | |
$ (anyOf 1) | Model | Alternative | Expand Update page — response body — object page cover value File |
$ (anyOf 2) | Model | Alternative | Expand 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
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
external | object | Required within parent | External URL for the cover. |
external.url | string | Required within parent | The URL of the external file. |
type | string | Optional | Always `external` Must equal: external |
Create a database — request body — body cover File Upload
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
file_upload | object | Required within parent | The file upload for the cover. |
file_upload.id | string | Required within parent | ID of a FileUpload object that has the status `uploaded`. |
type | string | Optional | Always `file_upload` Must equal: file_upload |
List views — response body — view
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: allowed |
Policy, approvals and errors
Section titled “Policy, approvals and errors”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"}