Objects - Charter Docs

Model tree

PageCreateBody

The body of a create-page request.

Field	Type	Description
`parent` *	Parent	Where the page is created: `page_id` for a subpage, or `data_source_id` to add a row to a database.
`properties`	map of PagePropertyValue	The values of the page’s properties, keyed by property name or ID. A page whose parent is a data source must use that data source’s schema; a page whose parent is another page has only `title`.
`icon`	Icon	The page’s icon.
`cover`	Cover	The page’s cover image.
`markdown`	`string`	The content of the new page as Notion-flavored Markdown, which Notion parses into blocks. Newlines must be `\n`.
`template`	Template	A template to build the page from. Applying one is incompatible with supplying content directly.
`position`	Position	Where the content is placed within the page.
`allowAsync`	`boolean`	Whether a large `markdown` body may be parsed in the background. When true the call answers 202 with an async task to poll rather than the finished page.

Parent

What an object lives under.

Field	Type	Description
`type`	`string`	The type of the parent. One of `database_id`, `data_source_id`, `page_id`, `workspace`, `block_id`, `agent_id`.
`dataSourceId`	`string`	The ID of the data source this object belongs to. This is the parent a page in a database takes.
`databaseId`	`string`	The ID of the database. On a data source’s parent this is the database that contains it. As a page’s parent it is the pre-2025-09-03 spelling: prefer `data_source_id`, which names the table the page is a row of.
`pageId`	`string`	The ID of the parent page.
`blockId`	`string`	The ID of the parent block.

PagePropertyValue

One entry in a page’s properties map.

Field	Type	Description
`type`	`string`	The type of this property value. Returned on a read; on a write Notion infers it from whichever field below is set.
`title`	RichText[]	The page’s title, as rich text. Every page has exactly one title property, and it is the only property a page outside a database has. max 100 items
`richText`	RichText[]	A text property, as rich text. max 100 items
`number`	`number`	A number. Send null to clear it.
`select`	SelectValue	The chosen option of a select property. Send null to clear it.
`multiSelect`	SelectValue[]	The chosen options of a multi-select property. max 100 items
`status`	StatusValue	The current status of the page.
`date`	DateValue	A date or date range. Send null to clear it.
`people`	PartialUser[]	The users assigned to a people property. max 100 items
`files`	FileObject[]	The files attached to a files property. An `external` entry must carry a `name`. Sending this replaces the whole list rather than adding to it. max 100 items
`checkbox`	`boolean`	Whether a checkbox is checked.
`url`	`string`	A URL. Maximum 2000 characters. max length 2000
`email`	`string`	An email address. Maximum 200 characters. max length 200
`phoneNumber`	`string`	A phone number. No structure is enforced, so any string up to 200 characters is accepted. max length 200
`relation`	RelationRef[]	The related pages. At most 100 may be sent or read in one request; a relation holding more reports `has_more` and is read in full through the page property item endpoint. max 100 items
`verification`	VerificationValue	The verification state of a page in a wiki database.

RichText

One run of styled text.

Field	Type	Description
`type`	`"text" \| "mention" \| "equation"`	The type of this rich text object.
`text`	TextContent	The literal text, present when `type` is `text`.
`mention`	Mention	An inline mention of a user, page, database, date or link preview, present when `type` is `mention`.
`equation`	EquationContent	An inline LaTeX equation, present when `type` is `equation`.
`annotations`	Annotations	The styling applied to this run of text.

TextContent

A literal run of text.

Field	Type	Description
`content` *	`string`	The actual text content of the text. Maximum 2000 characters; longer text must be split across several rich text objects. max length 2000
`link`	TextLink	An object with information about any inline link in this text, if included. Null when the text is not a link.

TextLink

The link on a text run.

Field	Type	Description
`url` *	`string`	The URL this text links to. Maximum 2000 characters. max length 2000

Mention

An inline reference to something else in the workspace.

Field	Type	Description
`type`	`string`	The type of the inline mention. One of `user`, `page`, `database`, `date`, `link_preview`, `template_mention`.
`user`	PartialUser	The mentioned user.
`page`	PageRef	The mentioned page.
`database`	DatabaseRef	The mentioned database.
`date`	DateValue	The mentioned date.
`linkPreview`	LinkPreviewRef	The mentioned link preview.
`templateMention`	TemplateMention	The template placeholder being mentioned.

PartialUser

A user, referenced by ID.

Field	Type	Description
`object`	`string`	Always `user`. defaults to `"user"`
`id` *	`string`	The ID of the user.

PageRef

A reference to a page by ID.

Field	Type	Description
`id` *	`string`	The ID of the page.

DatabaseRef

A reference to a database by ID.

Field	Type	Description
`id` *	`string`	The ID of the database.

DateValue

A date, or a date range, with an optional time zone.

Field	Type	Description
`start` *	`string`	An ISO 8601 format date, with optional time. A date without a time (`2024-05-01`) and a datetime (`2024-05-01T10:00:00-04:00`) are both accepted.
`end`	`string`	An ISO 8601 formatted date, with optional time. Null if this is not a range.
`timeZone`	`string`	Time zone information for `start` and `end`, as an IANA database name such as `America/New_York`. When set, `start` and `end` must not carry their own UTC offset. Null when the dates carry their own offsets.

LinkPreviewRef

A mention of a third-party URL that Notion renders as a preview.

Field	Type	Description
`url` *	`string`	The URL of the link preview. max length 2000

TemplateMention

A placeholder that resolves when a template is instantiated.

Field	Type	Description
`type`	`"template_mention_date" \| "template_mention_user"`	The type of the template mention.
`templateMentionDate`	`"today" \| "now"`	Resolves to the date the template is used.
`templateMentionUser`	`string`	Resolves to the user who uses the template.

EquationContent

An inline LaTeX equation.

Field	Type	Description
`expression` *	`string`	The LaTeX string representing the inline equation. Maximum 1000 characters. max length 1000

Annotations

The styling applied to one run of rich text.

Field	Type	Description
`bold`	`boolean`	Whether the text is bolded.
`italic`	`boolean`	Whether the text is italicized.
`strikethrough`	`boolean`	Whether the text is struck through.
`underline`	`boolean`	Whether the text is underlined.
`code`	`boolean`	Whether the text is code style.
`color`	NotionColor	Color of the text. Possible values include the ten hues as text colors and again as `_background` highlights, plus `default`.

SelectValue

One chosen option of a select or multi-select property.

Field	Type	Description
`id`	`string`	The ID of the option. Use this or `name`, not both.
`name`	`string`	The name of the option as it appears in Notion. Commas are not valid in a select value. An option that does not exist yet is created.

StatusValue

The current status of a page in a status property.

Field	Type	Description
`id`	`string`	The ID of the status option. Use this or `name`, not both.
`name`	`string`	The name of the status option. It must already exist on the database’s status property.

FileObject

A file, either linked externally or hosted by Notion.

Field	Type	Description
`type`	`"external" \| "file" \| "file_upload"`	The type of this file object.
`external`	ExternalFileData	A file hosted somewhere else, referenced by URL.
`fileUpload`	FileUploadRef	A completed file upload to attach, referenced by its ID.
`name`	`string`	The name of the file, as shown in Notion. Required for an `external` entry in a files property; optional for a `file_upload`, which carries the name it was uploaded with.

ExternalFileData

A file Notion links to but does not host.

Field	Type	Description
`url` *	`string`	A link to the externally hosted content. Maximum 2000 characters. Notion does not copy the file, so the link must stay reachable. max length 2000

FileUploadRef

A completed file upload, by ID.

Field	Type	Description
`id` *	`string`	The ID of a completed File Upload object.

RelationRef

One related page, referenced by ID.

Field	Type	Description
`id` *	`string`	The ID of the related page.

VerificationValue

The verification state of a page in a wiki database.

Field	Type	Description
`state` *	`"verified" \| "unverified" \| "expired"`	The verification state of the page. `expired` is a state Notion moves a page into when its verification lapses; set `verified` or `unverified`.
`date`	DateValue	The date the page was verified and the date the verification expires. Only meaningful when `state` is `verified`.

Icon

A page, database or callout icon.

Field	Type	Description
`type`	`string`	The type of this icon. One of `emoji`, `external`, `file_upload`, `custom_emoji`, `icon`.
`emoji`	`string`	A standard emoji character, for example `🥬`.
`external`	ExternalFileData	An externally hosted image, referenced by URL.
`fileUpload`	FileUploadRef	A completed file upload to use as the icon.
`customEmoji`	CustomEmojiData	One of the workspace’s own uploaded emoji.
`icon`	NotionIconData	One of Notion’s own built-in icons.

CustomEmojiData

A workspace’s own uploaded emoji.

Field	Type	Description
`id` *	`string`	The ID of the custom emoji.

NotionIconData

One of Notion’s own built-in icons.

Field	Type	Description
`name` *	`string`	The name of the built-in Notion icon.
`color`	`string`	The color applied to the icon.

Cover

A page or database cover image.

Field	Type	Description
`type`	`"external" \| "file_upload"`	The type of this cover.
`external`	ExternalFileData	An externally hosted image, referenced by URL.
`fileUpload`	FileUploadRef	A completed file upload to use as the cover.

Template

The template a new or updated page is built from.

Field	Type	Description
`type` *	`"none" \| "default" \| "template_id"`	Which template to apply: `none` for an empty page, `default` for the parent database’s default template, or `template_id` for a specific one.
`templateId`	`string`	The ID of the template page to apply, when `type` is `template_id`.
`timezone`	`string`	An IANA time zone name, for example `America/New_York`, used to resolve date placeholders in the template.

Position

Where new blocks are placed among a parent’s existing children.

Field	Type	Description
`type`	`"after_block" \| "page_start" \| "page_end"`	Where to insert the new content.
`afterBlock`	AfterBlockRef	The existing block to insert after, when `type` is `after_block`.

AfterBlockRef

The block that new content is inserted after.

Field	Type	Description
`id` *	`string`	The ID of the existing block to insert after.

PageUpdateBody

The body of an update-page request.

Field	Type	Description
`properties`	map of PagePropertyValue	The values of the page’s properties, keyed by property name or ID. A page whose parent is a data source must use that data source’s schema; a page whose parent is another page has only `title`. Set a value to null to clear it. Leave the computed types out of the map entirely rather than sending them as null.
`icon`	Icon	The page’s icon. Null removes it.
`cover`	Cover	The page’s cover image. Null removes it.
`inTrash`	`boolean`	Whether the page is in the trash. False restores it.
`isArchived`	`boolean`	Whether the page is archived. `in_trash` is the field to reach for; this is the older spelling and the API still accepts it.
`isLocked`	`boolean`	Whether the page is locked against editing in the Notion app. It does not block writes through the API.
`template`	Template	A template to apply to the page.
`eraseContent`	`boolean`	Whether to delete every block on the page.

PageMoveBody

The body of a move-page request.

Field	Type	Description
`parent` *	Parent	Where to move the page to.

PageMarkdownUpdateBody

The body of an update-page-markdown request.

Field	Type	Description
`type`	`"update_content" \| "replace_content" \| "insert_content" \| "replace_content_range"`	Which operation to perform.
`updateContent`	UpdateContentOp	Edit parts of the page by search and replace.
`replaceContent`	ReplaceContentOp	Replace the whole of the page’s content.
`allowAsync`	`boolean`	Whether a large edit may run in the background, answering 202 with an async task to poll rather than the finished page.

UpdateContentOp

Edit parts of a page, leaving the rest alone.

Field	Type	Description
`contentUpdates` *	ContentUpdate[]	The search-and-replace operations to apply, in order.
`allowDeletingContent`	`boolean`	Whether an edit may delete child pages or databases. Refused when absent, so a replacement that would remove one fails rather than doing it quietly.

ContentUpdate

One search-and-replace over a page’s Markdown.

Field	Type	Description
`oldStr` *	`string`	The existing content to find. It must match a unique stretch of the page, or the operation cannot tell which one you meant.
`newStr` *	`string`	What to put in its place.

ReplaceContentOp

Replace a page’s entire content.

Field	Type	Description
`newStr` *	`string`	The Markdown that becomes the whole of the page’s content.
`allowDeletingContent`	`boolean`	Whether the replacement may delete child pages or databases. Refused when absent.

NotionColor

Value
`default`
`default_background`
`blue`
`blue_background`
`brown`
`brown_background`
`gray`
`gray_background`
`green`
`green_background`
`orange`
`orange_background`
`pink`
`pink_background`
`purple`
`purple_background`
`red`
`red_background`
`yellow`
`yellow_background`

​Model tree

​PageCreateBody

​Parent

​PagePropertyValue

​RichText

​TextContent

​TextLink

​Mention

​PartialUser

​PageRef

​DatabaseRef

​DateValue

​LinkPreviewRef

​TemplateMention

​EquationContent

​Annotations

​SelectValue

​StatusValue

​FileObject

​ExternalFileData

​FileUploadRef

​RelationRef

​VerificationValue

​Icon

​CustomEmojiData

​NotionIconData

​Cover

​Template

​Position

​AfterBlockRef

​PageUpdateBody

​PageMoveBody

​PageMarkdownUpdateBody

​UpdateContentOp

​ContentUpdate

​ReplaceContentOp

​NotionColor