Create comment

Creates a comment in a page, block or existing discussion thread.

POST /v1/comments

TypeScript SDK

JavaScript

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" } }]
})

200

{
  "object": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

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 capabilities

Connection 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 Developer portal.

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

Option 1

Option 2

Option 3

Option 4

parent · object · required

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

Option 1

Option 2

Show child attributes

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

Text

Mention

Equation

Show child attributes

attachments · object[]

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

Maximum array length: 3

Show child attributes

display_name · Integration · object

Display name for the comment.

Integration

User

Custom

Show child attributes

Response

200

application/json

Option 1

Option 2

object · string · required

The comment object type name.

Allowed value: "comment"

id · string<uuid> · required

The ID of the comment.