--- title: "Create a comment" method: POST path: "/v1/comments" tags: ["Comments"] --- # Create a comment `POST /v1/comments` ## Headers - `Notion-Version` '2026-03-11', required ## Request body - union - object - `attachments` object[] — An array of files to attach to the comment. Maximum of 3 allowed. - `file_upload_id` string, required — ID of a FileUpload object that has the status `uploaded`. - `type` 'file_upload' — Always `file_upload` - `display_name` union — Display name for the comment. - object - `type` 'integration', required — Always `integration` - object - `type` 'user', required — Always `user` - object - `type` 'custom', required — Always `custom` - `custom` object, required - `name` string, required — The custom display name to use - `parent` union, required — The parent of the comment. This can be a page or a block. - object - `page_id` string, required - `type` 'page_id' — Always `page_id` - object - `block_id` string, required - `type` 'block_id' — Always `block_id` - `rich_text` RichTextItemRequest[], required — An array of rich text objects that represent the content of the comment. - union - object - `annotations` AnnotationRequest - `bold` boolean — Whether the text is formatted as bold. - `italic` boolean — Whether the text is formatted as italic. - `strikethrough` boolean — Whether the text is formatted with a strikethrough. - `underline` boolean — Whether the text is formatted with an underline. - `code` boolean — Whether the text is formatted as code. - `color` 'default' | 'gray' | 'brown' | 'orange' | 'yellow' | 'green' | 'blue' | 'purple' | 'pink' | 'red' | 'default_background' | 'gray_background' | 'brown_background' | 'orange_background' | 'yellow_background' | 'green_background' | 'blue_background' | 'purple_background' | 'pink_background' | 'red_background' — One of: `default`, `gray`, `brown`, `orange`, `yellow`, `green`, `blue`, `purple`, `pink`, `red`, `default_background`, `gray_background`, `brown_background`, `orange_background`, `yellow_background`, `green_background`, `blue_background`, `purple_background`, `pink_background`, `red_background` - `type` 'text' — Always `text` - `text` object, required — 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. - `content` string, required — The actual text content of the text. - `link` object, nullable — An object with information about any inline link in this text, if included. - … - object - `annotations` AnnotationRequest - `bold` boolean — Whether the text is formatted as bold. - `italic` boolean — Whether the text is formatted as italic. - `strikethrough` boolean — Whether the text is formatted with a strikethrough. - `underline` boolean — Whether the text is formatted with an underline. - `code` boolean — Whether the text is formatted as code. - `color` 'default' | 'gray' | 'brown' | 'orange' | 'yellow' | 'green' | 'blue' | 'purple' | 'pink' | 'red' | 'default_background' | 'gray_background' | 'brown_background' | 'orange_background' | 'yellow_background' | 'green_background' | 'blue_background' | 'purple_background' | 'pink_background' | 'red_background' — One of: `default`, `gray`, `brown`, `orange`, `yellow`, `green`, `blue`, `purple`, `pink`, `red`, `default_background`, `gray_background`, `brown_background`, `orange_background`, `yellow_background`, `green_background`, `blue_background`, `purple_background`, `pink_background`, `red_background` - `type` 'mention' — Always `mention` - `mention` union, required — 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. - object - … - object - … - object - … - object - … - object - … - object - … - object - `annotations` AnnotationRequest - `bold` boolean — Whether the text is formatted as bold. - `italic` boolean — Whether the text is formatted as italic. - `strikethrough` boolean — Whether the text is formatted with a strikethrough. - `underline` boolean — Whether the text is formatted with an underline. - `code` boolean — Whether the text is formatted as code. - `color` 'default' | 'gray' | 'brown' | 'orange' | 'yellow' | 'green' | 'blue' | 'purple' | 'pink' | 'red' | 'default_background' | 'gray_background' | 'brown_background' | 'orange_background' | 'yellow_background' | 'green_background' | 'blue_background' | 'purple_background' | 'pink_background' | 'red_background' — One of: `default`, `gray`, `brown`, `orange`, `yellow`, `green`, `blue`, `purple`, `pink`, `red`, `default_background`, `gray_background`, `brown_background`, `orange_background`, `yellow_background`, `green_background`, `blue_background`, `purple_background`, `pink_background`, `red_background` - `type` 'equation' — Always `equation` - `equation` object, required — Notion supports inline LaTeX equations as rich text objects with a type value of `equation`. - `expression` string, required — A KaTeX compatible string. - object - `attachments` object[] — An array of files to attach to the comment. Maximum of 3 allowed. - `file_upload_id` string, required — ID of a FileUpload object that has the status `uploaded`. - `type` 'file_upload' — Always `file_upload` - `display_name` union — Display name for the comment. - object - `type` 'integration', required — Always `integration` - object - `type` 'user', required — Always `user` - object - `type` 'custom', required — Always `custom` - `custom` object, required - `name` string, required — The custom display name to use - `parent` union, required — The parent of the comment. This can be a page or a block. - object - `page_id` string, required - `type` 'page_id' — Always `page_id` - object - `block_id` string, required - `type` 'block_id' — Always `block_id` - `markdown` string, required — The content of the comment as a Markdown string. Comment Markdown supports inline formatting only (bold, italic, strikethrough, code, links), inline equations ($expression$), and mentions. Block-level Markdown such as fenced code blocks, headings, lists, tables, and blockquotes does not render as structured blocks in comments. - object - `attachments` object[] — An array of files to attach to the comment. Maximum of 3 allowed. - `file_upload_id` string, required — ID of a FileUpload object that has the status `uploaded`. - `type` 'file_upload' — Always `file_upload` - `display_name` union — Display name for the comment. - object - `type` 'integration', required — Always `integration` - object - `type` 'user', required — Always `user` - object - `type` 'custom', required — Always `custom` - `custom` object, required - `name` string, required — The custom display name to use - `discussion_id` string, required - `rich_text` RichTextItemRequest[], required — An array of rich text objects that represent the content of the comment. - union - object - `annotations` AnnotationRequest - `bold` boolean — Whether the text is formatted as bold. - `italic` boolean — Whether the text is formatted as italic. - `strikethrough` boolean — Whether the text is formatted with a strikethrough. - `underline` boolean — Whether the text is formatted with an underline. - `code` boolean — Whether the text is formatted as code. - `color` 'default' | 'gray' | 'brown' | 'orange' | 'yellow' | 'green' | 'blue' | 'purple' | 'pink' | 'red' | 'default_background' | 'gray_background' | 'brown_background' | 'orange_background' | 'yellow_background' | 'green_background' | 'blue_background' | 'purple_background' | 'pink_background' | 'red_background' — One of: `default`, `gray`, `brown`, `orange`, `yellow`, `green`, `blue`, `purple`, `pink`, `red`, `default_background`, `gray_background`, `brown_background`, `orange_background`, `yellow_background`, `green_background`, `blue_background`, `purple_background`, `pink_background`, `red_background` - `type` 'text' — Always `text` - `text` object, required — 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. - `content` string, required — The actual text content of the text. - `link` object, nullable — An object with information about any inline link in this text, if included. - … - object - `annotations` AnnotationRequest - `bold` boolean — Whether the text is formatted as bold. - `italic` boolean — Whether the text is formatted as italic. - `strikethrough` boolean — Whether the text is formatted with a strikethrough. - `underline` boolean — Whether the text is formatted with an underline. - `code` boolean — Whether the text is formatted as code. - `color` 'default' | 'gray' | 'brown' | 'orange' | 'yellow' | 'green' | 'blue' | 'purple' | 'pink' | 'red' | 'default_background' | 'gray_background' | 'brown_background' | 'orange_background' | 'yellow_background' | 'green_background' | 'blue_background' | 'purple_background' | 'pink_background' | 'red_background' — One of: `default`, `gray`, `brown`, `orange`, `yellow`, `green`, `blue`, `purple`, `pink`, `red`, `default_background`, `gray_background`, `brown_background`, `orange_background`, `yellow_background`, `green_background`, `blue_background`, `purple_background`, `pink_background`, `red_background` - `type` 'mention' — Always `mention` - `mention` union, required — 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. - object - … - object - … - object - … - object - … - object - … - object - … - object - `annotations` AnnotationRequest - `bold` boolean — Whether the text is formatted as bold. - `italic` boolean — Whether the text is formatted as italic. - `strikethrough` boolean — Whether the text is formatted with a strikethrough. - `underline` boolean — Whether the text is formatted with an underline. - `code` boolean — Whether the text is formatted as code. - `color` 'default' | 'gray' | 'brown' | 'orange' | 'yellow' | 'green' | 'blue' | 'purple' | 'pink' | 'red' | 'default_background' | 'gray_background' | 'brown_background' | 'orange_background' | 'yellow_background' | 'green_background' | 'blue_background' | 'purple_background' | 'pink_background' | 'red_background' — One of: `default`, `gray`, `brown`, `orange`, `yellow`, `green`, `blue`, `purple`, `pink`, `red`, `default_background`, `gray_background`, `brown_background`, `orange_background`, `yellow_background`, `green_background`, `blue_background`, `purple_background`, `pink_background`, `red_background` - `type` 'equation' — Always `equation` - `equation` object, required — Notion supports inline LaTeX equations as rich text objects with a type value of `equation`. - `expression` string, required — A KaTeX compatible string. - object - `attachments` object[] — An array of files to attach to the comment. Maximum of 3 allowed. - `file_upload_id` string, required — ID of a FileUpload object that has the status `uploaded`. - `type` 'file_upload' — Always `file_upload` - `display_name` union — Display name for the comment. - object - `type` 'integration', required — Always `integration` - object - `type` 'user', required — Always `user` - object - `type` 'custom', required — Always `custom` - `custom` object, required - `name` string, required — The custom display name to use - `discussion_id` string, required - `markdown` string, required — The content of the comment as a Markdown string. Comment Markdown supports inline formatting only (bold, italic, strikethrough, code, links), inline equations ($expression$), and mentions. Block-level Markdown such as fenced code blocks, headings, lists, tables, and blockquotes does not render as structured blocks in comments. ## Response `200` - union - PartialCommentObjectResponse - `object` 'comment', required — The comment object type name. - `id` string, uuid, required - CommentObjectResponse - `object` 'comment', required — The comment object type name. - `id` string, uuid, required - `parent` union, required - PageIdCommentParentResponse - `type` 'page_id', required — Always `page_id` - `page_id` string, uuid, required - BlockIdCommentParentResponse - `type` 'block_id', required — Always `block_id` - `block_id` string, uuid, required - `discussion_id` string, uuid, required - `created_time` string, date-time, required — The time when the comment was created. - `last_edited_time` string, date-time, required — The time when the comment was last edited. - `created_by` PartialUserObjectResponse, required - `id` string, uuid, required - `object` 'user', required — Always `user` - `rich_text` RichTextItemResponse[], required — The rich text content of the comment. - union - object - `plain_text` string, required — The plain text content of the rich text object, without any styling. - `href` string, nullable, required — A URL that the rich text object links to or mentions. - `annotations` AnnotationResponse, required - `bold` boolean, required - `italic` boolean, required - `strikethrough` boolean, required - `underline` boolean, required - `code` boolean, required - `color` 'default' | 'gray' | 'brown' | 'orange' | 'yellow' | 'green' | 'blue' | 'purple' | 'pink' | 'red' | 'default_background' | 'gray_background' | 'brown_background' | 'orange_background' | 'yellow_background' | 'green_background' | 'blue_background' | 'purple_background' | 'pink_background' | 'red_background', required — One of: `default`, `gray`, `brown`, `orange`, `yellow`, `green`, `blue`, `purple`, `pink`, `red`, `default_background`, `gray_background`, `brown_background`, `orange_background`, `yellow_background`, `green_background`, `blue_background`, `purple_background`, `pink_background`, `red_background` - `type` 'text', required — Always `text` - `text` object, required — 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. - `content` string, required — The actual text content of the text. - `link` object, nullable, required — An object with information about any inline link in this text, if included. - … - object - `plain_text` string, required — The plain text content of the rich text object, without any styling. - `href` string, nullable, required — A URL that the rich text object links to or mentions. - `annotations` AnnotationResponse, required - `bold` boolean, required - `italic` boolean, required - `strikethrough` boolean, required - `underline` boolean, required - `code` boolean, required - `color` 'default' | 'gray' | 'brown' | 'orange' | 'yellow' | 'green' | 'blue' | 'purple' | 'pink' | 'red' | 'default_background' | 'gray_background' | 'brown_background' | 'orange_background' | 'yellow_background' | 'green_background' | 'blue_background' | 'purple_background' | 'pink_background' | 'red_background', required — One of: `default`, `gray`, `brown`, `orange`, `yellow`, `green`, `blue`, `purple`, `pink`, `red`, `default_background`, `gray_background`, `brown_background`, `orange_background`, `yellow_background`, `green_background`, `blue_background`, `purple_background`, `pink_background`, `red_background` - `type` 'mention', required — Always `mention` - `mention` union, required — 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. - object - … - object - … - object - … - object - … - object - … - object - … - object - … - object - … - object - `plain_text` string, required — The plain text content of the rich text object, without any styling. - `href` string, nullable, required — A URL that the rich text object links to or mentions. - `annotations` AnnotationResponse, required - `bold` boolean, required - `italic` boolean, required - `strikethrough` boolean, required - `underline` boolean, required - `code` boolean, required - `color` 'default' | 'gray' | 'brown' | 'orange' | 'yellow' | 'green' | 'blue' | 'purple' | 'pink' | 'red' | 'default_background' | 'gray_background' | 'brown_background' | 'orange_background' | 'yellow_background' | 'green_background' | 'blue_background' | 'purple_background' | 'pink_background' | 'red_background', required — One of: `default`, `gray`, `brown`, `orange`, `yellow`, `green`, `blue`, `purple`, `pink`, `red`, `default_background`, `gray_background`, `brown_background`, `orange_background`, `yellow_background`, `green_background`, `blue_background`, `purple_background`, `pink_background`, `red_background` - `type` 'equation', required — Always `equation` - `equation` object, required — Notion supports inline LaTeX equations as rich text objects with a type value of `equation`. - `expression` string, required — A KaTeX compatible string. - `display_name` object, required — The display name of the comment. - `type` 'custom' | 'user' | 'integration', required — One of: `custom`, `user`, `integration` - `resolved_name` string, nullable, required - `original_content_deleted` boolean, required — Whether this comment's original content was deleted. - `attachments` object[] — Any file attachments associated with the comment. - `category` 'audio' | 'image' | 'pdf' | 'productivity' | 'video', required — One of: `audio`, `image`, `pdf`, `productivity`, `video` - `file` InternalFileResponse, required - `url` string, required — The URL of the file. - `expiry_time` string, date-time, required — The time when the URL will expire. ## Other responses - `400` - `401` - `403` - `404` - `406` - `409` - `429` - `500` - `503` - `504` - `529` --- [API](https://skmtc.net/notion/apis/notion-api.md) · [All operations](https://skmtc.net/notion/apis/notion-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/notion/notion-api/versions/551da43bb186/schema)