Skip to main content
POST
/
v1
/
comments
TypeScript SDK
import { Client } from "@notionhq/client"

const notion = new Client({ auth: process.env.NOTION_API_KEY })

const response = await notion.comments.create({
  parent: { page_id: "b55c9c91-384d-452b-81db-d1ef79372b75" },
  rich_text: [{ text: { content: "This is a comment" } }]
})
{
  "object": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

Documentation Index

Fetch the complete documentation index at: https://developers.notion.com/llms.txt

Use this file to discover all available pages before exploring further.

Returns a comment object for the created comment. There are three locations where a new comment can be added with the public API:
  1. A page
  2. A block
  3. An existing discussion thread
The request body will differ slightly depending on which type of comment is being added with this endpoint. To add a new comment to a page or block, a parent object with a page_id or block_id must be provided in the body params. To add a new comment to an existing discussion thread, a discussion_id string must be provided in the body params. (Inline comments to start a new discussion thread cannot be created via the public API.) Either the parent.page_id , parent.block_id or discussion_id parameter must be provided — ONLY one can be specified.

​
Comment body format

The comment body can be provided in one of two formats:
  • rich_text: An array of rich text objects that represent the content of the comment.
  • markdown: A Markdown string. Comment Markdown supports inline formatting only (bold, italic, strikethrough, inline code, links), inline equations, and mentions. Block-level Markdown such as fenced code blocks, headings, lists, tables, and blockquotes does not render as structured blocks in comments.
Exactly one of rich_text or markdown must be provided. Providing both or neither will return a validation error. To see additional examples of creating a page or discussion comment and to learn more about comments in Notion, see the Working with comments guide.

​
Errors

Each Public API endpoint can return several possible error codes. See the Error codes section of the Status codes documentation for more information.
Reminder: Turn on connection comment capabilitiesConnection capabilities for reading and inserting comments are off by default.This endpoint requires a connection to have insert comment capabilities. Attempting to call this endpoint without insert comment capabilities will return an HTTP response with a 403 status code.For more information on connection capabilities, see the capabilities guide. To update your connection settings, visit the Creator dashboard.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
Notion-Version
enum<string>
required

The API version to use for this request. The latest version is 2026-03-11.

Available options:
2026-03-11

Body

application/json
​
parent
object
required

The parent of the comment. This can be a page or a block.

​
rich_text
(Text · object | Mention · object | Equation · object)[]
required

An array of rich text objects that represent the content of the comment.

Maximum array length: 100
​
attachments
object[]

An array of files to attach to the comment. Maximum of 3 allowed.

Maximum array length: 3
​
display_name
Integration · object

Display name for the comment.

Response

​
object
string
required

The comment object type name.

Allowed value: "comment"
​
id
string<uuid>
required

The ID of the comment.