Skip to content

Notion: Databases schemas

23 Notion schemas with complete fields and constraints.

← Databases operations · All schemas

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 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

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 icon Custom Emoji

FieldTypePresenceDescription and constraints
$objectRoot
custom_emojiobjectRequired within parent
custom_emoji.idstringRequired within parentThe ID of the custom emoji.
custom_emoji.namestringOptionalThe name of the custom emoji.
custom_emoji.urlstringOptionalThe URL of the custom emoji.
typestringOptionalAlways `custom_emoji`
Must equal: custom_emoji

Create a database — request body — body icon Emoji

FieldTypePresenceDescription and constraints
$objectRoot
emojistringRequired within parentAn emoji character.
typestringOptionalAlways `emoji`
Must equal: emoji

Create a database — request body — body icon External

FieldTypePresenceDescription and constraints
$objectRoot
externalobjectRequired within parent
external.urlstringRequired within parentThe URL of the external file.
typestringOptionalAlways `external`
Must equal: external

Create a database — request body — body icon File Upload

FieldTypePresenceDescription and constraints
$objectRoot
file_uploadobjectRequired within parent
file_upload.idstringRequired within parentID of a FileUpload object that has the status `uploaded`.
typestringOptionalAlways `file_upload`
Must equal: file_upload

Create a database — request body — body icon Icon

FieldTypePresenceDescription and constraints
$objectRoot
iconobjectRequired within parentA Notion native icon, specified by name and optional color.
icon.colorstringOptionalOne 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.namestringRequired within parentThe name of the Notion icon (e.g. pizza, meeting, home). See the Notion icon picker for valid names.
typestringOptionalAlways `icon`
Must equal: icon

Create a database — request body — body initial data source

FieldTypePresenceDescription and constraints
$objectRoot
propertiesobjectOptionalProperty schema for the initial data source, if you'd like to create one.
Additional keys: see wildcard field
properties.*ModelAdditional keysExpand 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

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

Create a database — request body — body title item annotations

FieldTypePresenceDescription and constraints
$objectRoot
annotationsModelOptionalExpand 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

FieldTypePresenceDescription and constraints
$objectRoot
boldbooleanOptionalWhether the text is formatted as bold.
codebooleanOptionalWhether the text is formatted as code.
colorModelOptionalExpand Update a block — request body — body value type quote quote color
The color of the text.
italicbooleanOptionalWhether the text is formatted as italic.
strikethroughbooleanOptionalWhether the text is formatted with a strikethrough.
underlinebooleanOptionalWhether 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

FieldTypePresenceDescription and constraints
$objectRoot
equationobjectRequired within parentNotion supports inline LaTeX equations as rich text objects with a type value of `equation`.
equation.expressionstringRequired within parentA KaTeX compatible string.
typestringOptionalAlways `equation`
Must equal: equation

Create a database — request body — body title item value Mention

FieldTypePresenceDescription and constraints
$objectRoot
mentionJSONRequired within parentMention 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)objectAlternative
mention (oneOf 1).typestringOptionalAlways `user`
Must equal: user
mention (oneOf 1).userModelRequired within parentExpand Update page — request body — body properties value type people people item object user
Details of the user mention.
mention (oneOf 2)objectAlternative
mention (oneOf 2).dateModelRequired within parentExpand Update page — request body — body properties value type date date end, start, time zone
Details of the date mention.
mention (oneOf 2).typestringOptionalAlways `date`
Must equal: date
mention (oneOf 3)objectAlternative
mention (oneOf 3).pageobjectRequired within parentDetails of the page mention.
mention (oneOf 3).page.idstringRequired within parentThe ID of the page in the mention.
mention (oneOf 3).typestringOptionalAlways `page`
Must equal: page
mention (oneOf 4)objectAlternative
mention (oneOf 4).databaseobjectRequired within parentDetails of the database mention.
mention (oneOf 4).database.idstringRequired within parentThe ID of the database in the mention.
mention (oneOf 4).typestringOptionalAlways `database`
Must equal: database
mention (oneOf 5)objectAlternative
mention (oneOf 5).template_mentionModelRequired within parentExpand Create a database — request body — body title item value Mention mention type template mention template mention
Details of the template mention.
mention (oneOf 5).typestringOptionalAlways `template_mention`
Must equal: template_mention
mention (oneOf 6)objectAlternative
mention (oneOf 6).custom_emojiobjectRequired within parentDetails of the custom emoji mention.
mention (oneOf 6).custom_emoji.idstringRequired within parentThe ID of the custom emoji.
mention (oneOf 6).custom_emoji.namestringOptionalThe name of the custom emoji.
mention (oneOf 6).custom_emoji.urlstringOptionalThe URL of the custom emoji.
mention (oneOf 6).typestringOptionalAlways `custom_emoji`
Must equal: custom_emoji
typestringOptionalAlways `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

FieldTypePresenceDescription and constraints
$JSONRoot
$ (oneOf 1)ModelAlternativeExpand Create a database — request body — body title item value Mention mention type template mention template mention Template Mention Date
$ (oneOf 2)ModelAlternativeExpand 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

FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
template_mention_datestringRequired within parentThe date of the template mention.
One of: today, now
typestringOptionalAlways `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

FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
template_mention_userstringRequired within parentThe user of the template mention.
Must equal: me
typestringOptionalAlways `template_mention_user`
Must equal: template_mention_user

Create a database — request body — body title item value Text

FieldTypePresenceDescription and constraints
$objectRoot
textobjectRequired within parentIf 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.contentstringRequired within parentThe actual text content of the text.
Maximum length: 2000
text.linkJSONOptionalAn object with information about any inline link in this text, if included.
text.link (oneOf 1)objectAlternative
text.link (oneOf 1).urlstringRequired within parentThe URL of the link.
text.link (oneOf 2)nullAlternative
typestringOptionalAlways `text`
Must equal: text

Create a database — response body — object database data sources item

FieldTypePresenceDescription and constraints
$objectRootAdditional keys: allowed
idstringRequired within parentThe ID of the data source.
Format: uuid
namestringRequired within parentThe name of the data source.
sync_metadataobjectOptionalSync identity and available health, included when retrieving a database.
Additional keys: allowed
sync_metadata.external_collection_typestringOptionalThe provider of a legacy synced data source: Jira or Salesforce. Values are case-sensitive.
Known values: Jira, Salesforce
sync_metadata.external_database_syncobjectOptionalStored identity of an external database sync.
Additional keys: allowed
sync_metadata.external_database_sync.providerstringRequired within parentThe sync provider: github (GitHub), jira (Jira), or salesforce (Salesforce).
Known values: github, jira, salesforce
sync_metadata.external_database_sync.sync_idstringRequired within parentThe stored sync ID. This is not a credential.
Format: uuid
sync_metadata.healthJSONOptionalLive collection sync health. Null means unavailable, not unhealthy. Missing timestamps are unknown.
sync_metadata.health (anyOf 1)nullAlternative
sync_metadata.health (anyOf 2)ModelAlternativeExpand Create a data source — response body — object data_source / sync_metadata / health / ok False, stage: backfilling, initializing, steady
sync_metadata.health (anyOf 3)ModelAlternativeExpand Create a data source — response body — object data_source / sync_metadata / health / ok True, stage: backfilling, initializing, steady
sync_metadata.health (anyOf 4)objectAlternativeAdditional keys: allowed
sync_metadata.health (anyOf 4).pausedbooleanRequired within parentMust equal: true
sync_metadata.owner_user_idstringOptionalNotion user who owns the sync credential, included when health is available.
Format: uuid
sync_metadata.resourcestringOptionalProvider resource synced to this data source, when available.
sync_metadata.sync_idstringOptionalThe stored sync ID when provider details are unavailable. This is not a credential.
Format: uuid
sync_metadata.sync_stateModelOptionalExpand Create a data source — response body — object data source sync metadata sync state
sync_metadata.synced_collection_keystringOptionalOpaque, 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

FieldTypePresenceDescription and constraints
$JSONRoot
$ (anyOf 1)ModelAlternativeExpand Update page — response body — object page parent type page id
$ (anyOf 2)ModelAlternativeExpand Update page — response body — object page parent type workspace, workspace True
$ (anyOf 3)ModelAlternativeExpand Delete a view — response body — parent
$ (anyOf 4)ModelAlternativeExpand 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

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

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.