Create comment

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

curl --request POST \
  --url https://api.notion.com/v1/comments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Notion-Version: <notion-version>' \
  --data '
{
  "parent": {
    "page_id": "<string>",
    "type": "page_id"
  },
  "rich_text": [
    {
      "text": {
        "content": "<string>",
        "link": {
          "url": "https://www.notion.com"
        }
      },
      "annotations": {
        "bold": true,
        "italic": true,
        "strikethrough": true,
        "underline": true,
        "code": true
      },
      "type": "text"
    }
  ],
  "attachments": [
    {
      "file_upload_id": "<string>",
      "type": "file_upload"
    }
  ],
  "display_name": {
    "type": "integration"
  }
}
'

import requests

url = "https://api.notion.com/v1/comments"

payload = {
    "parent": {
        "page_id": "<string>",
        "type": "page_id"
    },
    "rich_text": [
        {
            "text": {
                "content": "<string>",
                "link": { "url": "https://www.notion.com" }
            },
            "annotations": {
                "bold": True,
                "italic": True,
                "strikethrough": True,
                "underline": True,
                "code": True
            },
            "type": "text"
        }
    ],
    "attachments": [
        {
            "file_upload_id": "<string>",
            "type": "file_upload"
        }
    ],
    "display_name": { "type": "integration" }
}
headers = {
    "Notion-Version": "<notion-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.notion.com/v1/comments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'parent' => [
        'page_id' => '<string>',
        'type' => 'page_id'
    ],
    'rich_text' => [
        [
                'text' => [
                                'content' => '<string>',
                                'link' => [
                                                                'url' => 'https://www.notion.com'
                                ]
                ],
                'annotations' => [
                                'bold' => true,
                                'italic' => true,
                                'strikethrough' => true,
                                'underline' => true,
                                'code' => true
                ],
                'type' => 'text'
        ]
    ],
    'attachments' => [
        [
                'file_upload_id' => '<string>',
                'type' => 'file_upload'
        ]
    ],
    'display_name' => [
        'type' => 'integration'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Notion-Version: <notion-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.notion.com/v1/comments"

	payload := strings.NewReader("{\n  \"parent\": {\n    \"page_id\": \"<string>\",\n    \"type\": \"page_id\"\n  },\n  \"rich_text\": [\n    {\n      \"text\": {\n        \"content\": \"<string>\",\n        \"link\": {\n          \"url\": \"https://www.notion.com\"\n        }\n      },\n      \"annotations\": {\n        \"bold\": true,\n        \"italic\": true,\n        \"strikethrough\": true,\n        \"underline\": true,\n        \"code\": true\n      },\n      \"type\": \"text\"\n    }\n  ],\n  \"attachments\": [\n    {\n      \"file_upload_id\": \"<string>\",\n      \"type\": \"file_upload\"\n    }\n  ],\n  \"display_name\": {\n    \"type\": \"integration\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Notion-Version", "<notion-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.notion.com/v1/comments")
  .header("Notion-Version", "<notion-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"parent\": {\n    \"page_id\": \"<string>\",\n    \"type\": \"page_id\"\n  },\n  \"rich_text\": [\n    {\n      \"text\": {\n        \"content\": \"<string>\",\n        \"link\": {\n          \"url\": \"https://www.notion.com\"\n        }\n      },\n      \"annotations\": {\n        \"bold\": true,\n        \"italic\": true,\n        \"strikethrough\": true,\n        \"underline\": true,\n        \"code\": true\n      },\n      \"type\": \"text\"\n    }\n  ],\n  \"attachments\": [\n    {\n      \"file_upload_id\": \"<string>\",\n      \"type\": \"file_upload\"\n    }\n  ],\n  \"display_name\": {\n    \"type\": \"integration\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.notion.com/v1/comments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Notion-Version"] = '<notion-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"parent\": {\n    \"page_id\": \"<string>\",\n    \"type\": \"page_id\"\n  },\n  \"rich_text\": [\n    {\n      \"text\": {\n        \"content\": \"<string>\",\n        \"link\": {\n          \"url\": \"https://www.notion.com\"\n        }\n      },\n      \"annotations\": {\n        \"bold\": true,\n        \"italic\": true,\n        \"strikethrough\": true,\n        \"underline\": true,\n        \"code\": true\n      },\n      \"type\": \"text\"\n    }\n  ],\n  \"attachments\": [\n    {\n      \"file_upload_id\": \"<string>\",\n      \"type\": \"file_upload\"\n    }\n  ],\n  \"display_name\": {\n    \"type\": \"integration\"\n  }\n}"

response = http.request(request)
puts response.read_body

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

{
  "object": "error",
  "message": "<string>",
  "code": "invalid_json",
  "status": 400,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "unauthorized",
  "status": 401,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "restricted_resource",
  "status": 403,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "object_not_found",
  "status": 404,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "row_limit_exceeded",
  "status": 406,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "conflict_error",
  "status": 409,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "rate_limited",
  "status": 429,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "internal_server_error",
  "status": 500,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "service_unavailable",
  "status": 503,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "gateway_timeout",
  "status": 504,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "service_overload",
  "status": 529,
  "additional_data": {}
}

POST

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

curl --request POST \
  --url https://api.notion.com/v1/comments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Notion-Version: <notion-version>' \
  --data '
{
  "parent": {
    "page_id": "<string>",
    "type": "page_id"
  },
  "rich_text": [
    {
      "text": {
        "content": "<string>",
        "link": {
          "url": "https://www.notion.com"
        }
      },
      "annotations": {
        "bold": true,
        "italic": true,
        "strikethrough": true,
        "underline": true,
        "code": true
      },
      "type": "text"
    }
  ],
  "attachments": [
    {
      "file_upload_id": "<string>",
      "type": "file_upload"
    }
  ],
  "display_name": {
    "type": "integration"
  }
}
'

import requests

url = "https://api.notion.com/v1/comments"

payload = {
    "parent": {
        "page_id": "<string>",
        "type": "page_id"
    },
    "rich_text": [
        {
            "text": {
                "content": "<string>",
                "link": { "url": "https://www.notion.com" }
            },
            "annotations": {
                "bold": True,
                "italic": True,
                "strikethrough": True,
                "underline": True,
                "code": True
            },
            "type": "text"
        }
    ],
    "attachments": [
        {
            "file_upload_id": "<string>",
            "type": "file_upload"
        }
    ],
    "display_name": { "type": "integration" }
}
headers = {
    "Notion-Version": "<notion-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.notion.com/v1/comments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'parent' => [
        'page_id' => '<string>',
        'type' => 'page_id'
    ],
    'rich_text' => [
        [
                'text' => [
                                'content' => '<string>',
                                'link' => [
                                                                'url' => 'https://www.notion.com'
                                ]
                ],
                'annotations' => [
                                'bold' => true,
                                'italic' => true,
                                'strikethrough' => true,
                                'underline' => true,
                                'code' => true
                ],
                'type' => 'text'
        ]
    ],
    'attachments' => [
        [
                'file_upload_id' => '<string>',
                'type' => 'file_upload'
        ]
    ],
    'display_name' => [
        'type' => 'integration'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Notion-Version: <notion-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.notion.com/v1/comments"

	payload := strings.NewReader("{\n  \"parent\": {\n    \"page_id\": \"<string>\",\n    \"type\": \"page_id\"\n  },\n  \"rich_text\": [\n    {\n      \"text\": {\n        \"content\": \"<string>\",\n        \"link\": {\n          \"url\": \"https://www.notion.com\"\n        }\n      },\n      \"annotations\": {\n        \"bold\": true,\n        \"italic\": true,\n        \"strikethrough\": true,\n        \"underline\": true,\n        \"code\": true\n      },\n      \"type\": \"text\"\n    }\n  ],\n  \"attachments\": [\n    {\n      \"file_upload_id\": \"<string>\",\n      \"type\": \"file_upload\"\n    }\n  ],\n  \"display_name\": {\n    \"type\": \"integration\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Notion-Version", "<notion-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.notion.com/v1/comments")
  .header("Notion-Version", "<notion-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"parent\": {\n    \"page_id\": \"<string>\",\n    \"type\": \"page_id\"\n  },\n  \"rich_text\": [\n    {\n      \"text\": {\n        \"content\": \"<string>\",\n        \"link\": {\n          \"url\": \"https://www.notion.com\"\n        }\n      },\n      \"annotations\": {\n        \"bold\": true,\n        \"italic\": true,\n        \"strikethrough\": true,\n        \"underline\": true,\n        \"code\": true\n      },\n      \"type\": \"text\"\n    }\n  ],\n  \"attachments\": [\n    {\n      \"file_upload_id\": \"<string>\",\n      \"type\": \"file_upload\"\n    }\n  ],\n  \"display_name\": {\n    \"type\": \"integration\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.notion.com/v1/comments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Notion-Version"] = '<notion-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"parent\": {\n    \"page_id\": \"<string>\",\n    \"type\": \"page_id\"\n  },\n  \"rich_text\": [\n    {\n      \"text\": {\n        \"content\": \"<string>\",\n        \"link\": {\n          \"url\": \"https://www.notion.com\"\n        }\n      },\n      \"annotations\": {\n        \"bold\": true,\n        \"italic\": true,\n        \"strikethrough\": true,\n        \"underline\": true,\n        \"code\": true\n      },\n      \"type\": \"text\"\n    }\n  ],\n  \"attachments\": [\n    {\n      \"file_upload_id\": \"<string>\",\n      \"type\": \"file_upload\"\n    }\n  ],\n  \"display_name\": {\n    \"type\": \"integration\"\n  }\n}"

response = http.request(request)
puts response.read_body

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

{
  "object": "error",
  "message": "<string>",
  "code": "invalid_json",
  "status": 400,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "unauthorized",
  "status": 401,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "restricted_resource",
  "status": 403,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "object_not_found",
  "status": 404,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "row_limit_exceeded",
  "status": 406,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "conflict_error",
  "status": 409,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "rate_limited",
  "status": 429,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "internal_server_error",
  "status": 500,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "service_unavailable",
  "status": 503,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "gateway_timeout",
  "status": 504,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "service_overload",
  "status": 529,
  "additional_data": {}
}

Returns a comment object for the created comment. Choose exactly one target for the new comment:

Target	Body parameter	Use when
Page	`parent.page_id`	Creating a comment on a page.
Block	`parent.block_id`	Creating a comment attached to a specific block, such as a paragraph, heading, or to-do item.
Existing discussion thread	`discussion_id`	Replying to an existing page, block, or selected-text discussion.

The request body will differ slightly depending on which target is being used. To add a new comment to a page or block, provide a parent object with a page_id or block_id in the body params. For example, this request creates a comment attached to a block:

{
  "parent": {
    "block_id": "d40e767c-d7af-4b18-a86d-55c61f1e39a4"
  },
  "rich_text": [
    {
      "text": {
        "content": "This comment is attached to a block."
      }
    }
  ]
}

To add a new comment to an existing discussion thread, provide a discussion_id string in the body params.

The public API can create comments attached to whole blocks with parent.block_id. It does not support creating a new discussion anchored to a selected range of text inside a block. To reply to an existing selected-text discussion, use discussion_id.

Exactly one of parent.page_id, parent.block_id, or discussion_id must be provided.

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. With markdown, set markdown_version: "v2" to write Notion-flavored Markdown instead of enhanced markdown. v2 is recommended. v1 is deprecated. It’s the default on current Notion-Versions. Sending markdown_version with rich_text returns a 400 validation_error. See Markdown versions. To see additional examples of creating a page, inline, 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 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

markdown_version

enum<string>

The Markdown syntax to use. v2 is Notion-flavored Markdown and is recommended. v1 is enhanced markdown. It's deprecated. It's the default on current Notion-Versions. The next Notion-Version rejects v1 with a 400 validation_error.

Available options:

v1,

v2

Response

Option 1
Option 2

object

string

required

The comment object type name.

Allowed value: "comment"

string<uuid>

required

The ID of the comment.

Notion API

Objects

Endpoints

Webhook events

Comment body format

Errors

Authorizations

Headers

Body

Response

​Comment body format

​Errors

Authorizations

Headers

Body

Response

Comment body format

Errors