Notion: Databases schemas
23 Notion schemas with complete fields and constraints.
← Databases operations · All schemas
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 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 |
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 icon Custom Emoji
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
custom_emoji | object | Required within parent | |
custom_emoji.id | string | Required within parent | The ID of the custom emoji. |
custom_emoji.name | string | Optional | The name of the custom emoji. |
custom_emoji.url | string | Optional | The URL of the custom emoji. |
type | string | Optional | Always `custom_emoji` Must equal: custom_emoji |
Create a database — request body — body icon Emoji
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
emoji | string | Required within parent | An emoji character. |
type | string | Optional | Always `emoji` Must equal: emoji |
Create a database — request body — body icon External
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
external | object | Required within parent | |
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 icon File Upload
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
file_upload | object | Required within parent | |
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 |
Create a database — request body — body icon Icon
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
icon | object | Required within parent | A Notion native icon, specified by name and optional color. |
icon.color | string | Optional | One of: `gray`, `lightgray`, `brown`, `yellow`, `orange`, `green`, `blue`, `purple`, `pink`, `red` The color variant of the icon. Defaults to gray if not specified. Valid values: gray, lightgray, brown, yellow, orange, green, blue, purple, pink, red. One of: gray, lightgray, brown, yellow, orange, green, blue, purple, pink, red |
icon.name | string | Required within parent | The name of the Notion icon (e.g. pizza, meeting, home). See the Notion icon picker for valid names. |
type | string | Optional | Always `icon` Must equal: icon |
Create a database — request body — body initial data source
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
properties | object | Optional | Property schema for the initial data source, if you'd like to create one. Additional keys: see wildcard field |
properties.* | Model | Additional keys | Expand Create a data source — request body — body properties value |
Referenced models: Create a data source — request body — body properties value
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
Create a database — request body — body title item annotations
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
annotations | Model | Optional | Expand Create a database — request body — body title item annotations annotations All rich text objects contain an annotations object that sets the styling for the rich text. |
Referenced models: Create a database — request body — body title item annotations annotations
Create a database — request body — body title item annotations annotations
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
bold | boolean | Optional | Whether the text is formatted as bold. |
code | boolean | Optional | Whether the text is formatted as code. |
color | Model | Optional | Expand Update a block — request body — body value type quote quote color The color of the text. |
italic | boolean | Optional | Whether the text is formatted as italic. |
strikethrough | boolean | Optional | Whether the text is formatted with a strikethrough. |
underline | boolean | Optional | Whether the text is formatted with an underline. |
Referenced models: Update a block — request body — body value type quote quote color
Create a database — request body — body title item value Equation
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
equation | object | Required within parent | Notion supports inline LaTeX equations as rich text objects with a type value of `equation`. |
equation.expression | string | Required within parent | A KaTeX compatible string. |
type | string | Optional | Always `equation` Must equal: equation |
Create a database — request body — body title item value Mention
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
mention | JSON | Required within parent | Mention objects represent an inline mention of a database, date, link preview mention, page, template mention, or user. A mention is created in the Notion UI when a user types `@` followed by the name of the reference. |
mention (oneOf 1) | object | Alternative | |
mention (oneOf 1).type | string | Optional | Always `user` Must equal: user |
mention (oneOf 1).user | Model | Required within parent | Expand Update page — request body — body properties value type people people item object user Details of the user mention. |
mention (oneOf 2) | object | Alternative | |
mention (oneOf 2).date | Model | Required within parent | Expand Update page — request body — body properties value type date date end, start, time zone Details of the date mention. |
mention (oneOf 2).type | string | Optional | Always `date` Must equal: date |
mention (oneOf 3) | object | Alternative | |
mention (oneOf 3).page | object | Required within parent | Details of the page mention. |
mention (oneOf 3).page.id | string | Required within parent | The ID of the page in the mention. |
mention (oneOf 3).type | string | Optional | Always `page` Must equal: page |
mention (oneOf 4) | object | Alternative | |
mention (oneOf 4).database | object | Required within parent | Details of the database mention. |
mention (oneOf 4).database.id | string | Required within parent | The ID of the database in the mention. |
mention (oneOf 4).type | string | Optional | Always `database` Must equal: database |
mention (oneOf 5) | object | Alternative | |
mention (oneOf 5).template_mention | Model | Required within parent | Expand Create a database — request body — body title item value Mention mention type template mention template mention Details of the template mention. |
mention (oneOf 5).type | string | Optional | Always `template_mention` Must equal: template_mention |
mention (oneOf 6) | object | Alternative | |
mention (oneOf 6).custom_emoji | object | Required within parent | Details of the custom emoji mention. |
mention (oneOf 6).custom_emoji.id | string | Required within parent | The ID of the custom emoji. |
mention (oneOf 6).custom_emoji.name | string | Optional | The name of the custom emoji. |
mention (oneOf 6).custom_emoji.url | string | Optional | The URL of the custom emoji. |
mention (oneOf 6).type | string | Optional | Always `custom_emoji` Must equal: custom_emoji |
type | string | Optional | Always `mention` Must equal: mention |
Referenced models: Update page — request body — body properties value type date date end, start, time zone, Update page — request body — body properties value type people people item object user, Create a database — request body — body title item value Mention mention type template mention template mention
Create a database — request body — body title item value Mention mention type template mention template mention
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | |
$ (oneOf 1) | Model | Alternative | Expand Create a database — request body — body title item value Mention mention type template mention template mention Template Mention Date |
$ (oneOf 2) | Model | Alternative | Expand Create a database — request body — body title item value Mention mention type template mention template mention Template Mention User |
Referenced models: Create a database — request body — body title item value Mention mention type template mention template mention Template Mention Date, Create a database — request body — body title item value Mention mention type template mention template mention Template Mention User
Create a database — request body — body title item value Mention mention type template mention template mention Template Mention Date
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
template_mention_date | string | Required within parent | The date of the template mention. One of: today, now |
type | string | Optional | Always `template_mention_date` Must equal: template_mention_date |
Create a database — request body — body title item value Mention mention type template mention template mention Template Mention User
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
template_mention_user | string | Required within parent | The user of the template mention. Must equal: me |
type | string | Optional | Always `template_mention_user` Must equal: template_mention_user |
Create a database — request body — body title item value Text
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
text | object | Required within parent | If a rich text object's type value is `text`, then the corresponding text field contains an object including the text content and any inline link. Additional keys: not allowed |
text.content | string | Required within parent | The actual text content of the text. Maximum length: 2000 |
text.link | JSON | Optional | An object with information about any inline link in this text, if included. |
text.link (oneOf 1) | object | Alternative | |
text.link (oneOf 1).url | string | Required within parent | The URL of the link. |
text.link (oneOf 2) | null | Alternative | |
type | string | Optional | Always `text` Must equal: text |
Create a database — response body — object database data sources item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: allowed |
id | string | Required within parent | The ID of the data source. Format: uuid |
name | string | Required within parent | The name of the data source. |
sync_metadata | object | Optional | Sync identity and available health, included when retrieving a database. Additional keys: allowed |
sync_metadata.external_collection_type | string | Optional | The provider of a legacy synced data source: Jira or Salesforce. Values are case-sensitive. Known values: Jira, Salesforce |
sync_metadata.external_database_sync | object | Optional | Stored identity of an external database sync. Additional keys: allowed |
sync_metadata.external_database_sync.provider | string | Required within parent | The sync provider: github (GitHub), jira (Jira), or salesforce (Salesforce). Known values: github, jira, salesforce |
sync_metadata.external_database_sync.sync_id | string | Required within parent | The stored sync ID. This is not a credential. Format: uuid |
sync_metadata.health | JSON | Optional | Live collection sync health. Null means unavailable, not unhealthy. Missing timestamps are unknown. |
sync_metadata.health (anyOf 1) | null | Alternative | |
sync_metadata.health (anyOf 2) | Model | Alternative | Expand Create a data source — response body — object data_source / sync_metadata / health / ok False, stage: backfilling, initializing, steady |
sync_metadata.health (anyOf 3) | Model | Alternative | Expand Create a data source — response body — object data_source / sync_metadata / health / ok True, stage: backfilling, initializing, steady |
sync_metadata.health (anyOf 4) | object | Alternative | Additional keys: allowed |
sync_metadata.health (anyOf 4).paused | boolean | Required within parent | Must equal: true |
sync_metadata.owner_user_id | string | Optional | Notion user who owns the sync credential, included when health is available. Format: uuid |
sync_metadata.resource | string | Optional | Provider resource synced to this data source, when available. |
sync_metadata.sync_id | string | Optional | The stored sync ID when provider details are unavailable. This is not a credential. Format: uuid |
sync_metadata.sync_state | Model | Optional | Expand Create a data source — response body — object data source sync metadata sync state |
sync_metadata.synced_collection_key | string | Optional | Opaque, developer-defined collection key for a worker sync. It is not a globally unique ID or a credential. Worker status is not included. |
Referenced models: Create a data source — response body — object data_source / sync_metadata / health / ok False, stage: backfilling, initializing, steady, Create a data source — response body — object data_source / sync_metadata / health / ok True, stage: backfilling, initializing, steady, Create a data source — response body — object data source sync metadata sync state
Create a database — response body — object database parent
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | |
$ (anyOf 1) | Model | Alternative | Expand Update page — response body — object page parent type page id |
$ (anyOf 2) | Model | Alternative | Expand Update page — response body — object page parent type workspace, workspace True |
$ (anyOf 3) | Model | Alternative | Expand Delete a view — response body — parent |
$ (anyOf 4) | Model | Alternative | Expand Update page — response body — object page parent type block id |
Referenced models: Update page — response body — object page parent type block id, Delete a view — response body — parent, Update page — response body — object page parent type page id, Update page — response body — object page parent type workspace, workspace True
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 |