> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://notion.ferndocs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://notion.ferndocs.com/_mcp/server. # Create comment POST https://api.notion.com/v1/comments Content-Type: application/json Creates a comment in a page, block or existing discussion thread. Returns a [comment object](https://developers.notion.com/reference/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**. To see additional examples of creating a [page](https://developers.notion.com/docs/working-with-comments#adding-a-comment-to-a-page) or [discussion](https://developers.notion.com/docs/working-with-comments#responding-to-a-discussion-thread) comment and to learn more about comments in Notion, see the [Working with comments](https://developers.notion.com/docs/working-with-comments) guide. ### Errors Each Public API endpoint can return several possible error codes. See the [Error codes section](https://developers.notion.com/reference/status-codes#error-codes) of the Status codes documentation for more information. Integration capabilities for reading and inserting comments are off by default. This endpoint requires an integration 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 integration capabilities, see the [capabilities guide](https://developers.notion.com/reference/capabilities). To update your integration settings, visit the [integration dashboard](https://www.notion.so/my-integrations). Reference: https://notion.ferndocs.com/reference/create-a-comment ## Request ### Headers - `Notion-Version` (string, required) — The [API version](/reference/versioning) to use for this request. The latest version is `<>`. ### Body (application/json) This endpoint expects an object. - `rich_text` (string, required) — A [rich text object](ref:rich-text) - `parent` (string, optional) — A [page parent](/reference/database#page-parent) or block parent. Either this or a discussion_id is required (not both) - `discussion_id` (string, optional) — A UUID identifier for a discussion thread. Either this or a parent object is required (not both) - `attachments` (string, optional) — An array of [comment attachment requests](ref:comment-attachment#request-format-input) - `display_name` (string, optional) — Custom display name of a comment ## Response ### 200 200 - `object` (string, optional) - `id` (string, optional) - `parent` (V1CommentsPostResponsesContentApplicationJsonSchemaParent, optional) - `discussion_id` (string, optional) - `created_time` (string, optional) - `last_edited_time` (string, optional) - `created_by` (V1CommentsPostResponsesContentApplicationJsonSchemaCreatedBy, optional) - `rich_text` (list of V1CommentsPostResponsesContentApplicationJsonSchemaRichTextItems, optional) - `attachments` (list of V1CommentsPostResponsesContentApplicationJsonSchemaAttachmentsItems, optional) - `display_name` (V1CommentsPostResponsesContentApplicationJsonSchemaDisplayName, optional) ## Errors ### 403 Forbidden Error 403 - `object` (string, optional) - `status` (integer, optional, default: 0) - `code` (string, optional) - `message` (string, optional) ## Types ### V1CommentsPostResponsesContentApplicationJsonSchemaParent - `type` (string, optional) - `page_id` (string, optional) ### V1CommentsPostResponsesContentApplicationJsonSchemaCreatedBy - `object` (string, optional) - `id` (string, optional) ### V1CommentsPostResponsesContentApplicationJsonSchemaRichTextItems - `type` (string, optional) - `text` (V1CommentsPostResponsesContentApplicationJsonSchemaRichTextItemsText, optional) - `annotations` (V1CommentsPostResponsesContentApplicationJsonSchemaRichTextItemsAnnotations, optional) - `plain_text` (string, optional) - `href` (any, optional) ### V1CommentsPostResponsesContentApplicationJsonSchemaAttachmentsItems - `category` (string, optional) - `file` (V1CommentsPostResponsesContentApplicationJsonSchemaAttachmentsItemsFile, optional) ### V1CommentsPostResponsesContentApplicationJsonSchemaDisplayName - `type` (string, optional) - `resolved_name` (string, optional) ### V1CommentsPostResponsesContentApplicationJsonSchemaRichTextItemsText - `content` (string, optional) - `link` (any, optional) ### V1CommentsPostResponsesContentApplicationJsonSchemaRichTextItemsAnnotations - `bold` (boolean, optional, default: true) - `italic` (boolean, optional, default: true) - `strikethrough` (boolean, optional, default: true) - `underline` (boolean, optional, default: true) - `code` (boolean, optional, default: true) - `color` (string, optional) ### V1CommentsPostResponsesContentApplicationJsonSchemaAttachmentsItemsFile - `url` (string, optional) - `expiry_time` (string, optional) ## Examples **Request** ```json { "rich_text": "string" } ``` **Response** ```json { "Result": { "value": "{\n \"object\": \"comment\",\n \"id\": \"b52b8ed6-e029-4707-a671-832549c09de3\",\n \"parent\": {\n \"type\": \"page_id\",\n \"page_id\": \"5c6a2821-6bb1-4a7e-b6e1-c50111515c3d\"\n },\n \"discussion_id\": \"f1407351-36f5-4c49-a13c-49f8ba11776d\",\n \"created_time\": \"2022-07-15T20:53:00.000Z\",\n \"last_edited_time\": \"2022-07-15T20:53:00.000Z\",\n \"created_by\": {\n \"object\": \"user\",\n \"id\": \"067dee40-6ebd-496f-b446-093c715fb5ec\"\n },\n \"rich_text\": [\n {\n \"type\": \"text\",\n \"text\": {\n \"content\": \"Hello world\",\n \"link\": null\n },\n \"annotations\": {\n \"bold\": false,\n \"italic\": false,\n \"strikethrough\": false,\n \"underline\": false,\n \"code\": false,\n \"color\": \"default\"\n },\n \"plain_text\": \"Hello world\",\n \"href\": null\n }\n ],\n \"attachments\": [\n {\n \"category\": \"image\",\n \"file\": {\n \"url\": \"https://s3.us-west-2.amazonaws.com/...\",\n \"expiry_time\": \"2025-06-10T21:58:51.599Z\"\n }\n }\n ],\n\t\"display_name\": {\n\t\t\"type\": \"integration\",\n\t\t\"resolved_name\": \"Public Integration\"\n\t}\n}" } } ``` **SDK Code** ```javascript Notion SDK for JavaScript const { Client } = require('@notionhq/client'); const notion = new Client({ auth: process.env.NOTION_API_KEY }); (async () => { const response = await notion.comments.create({ parent: { page_id: "5c6a28216bb14a7eb6e1c50111515c3d" }, rich_text: [ { type: "text", text: { content: "Hello world" } } ], attachments: [ { file_upload_id: "48656c6c-6f20-576f-726c-64212048692e" } ], display_name: { type: "integration" } }); console.log(response); })(); ``` ```python import requests url = "https://api.notion.com/v1/comments" payload = { "rich_text": "string" } headers = { "Notion-Version": "Notion-Version", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.notion.com/v1/comments" payload := strings.NewReader("{\n \"rich_text\": \"string\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Notion-Version", "Notion-Version") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby 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["Content-Type"] = 'application/json' request.body = "{\n \"rich_text\": \"string\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.notion.com/v1/comments") .header("Notion-Version", "Notion-Version") .header("Content-Type", "application/json") .body("{\n \"rich_text\": \"string\"\n}") .asString(); ``` ```php request('POST', 'https://api.notion.com/v1/comments', [ 'body' => '{ "rich_text": "string" }', 'headers' => [ 'Content-Type' => 'application/json', 'Notion-Version' => 'Notion-Version', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.notion.com/v1/comments"); var request = new RestRequest(Method.POST); request.AddHeader("Notion-Version", "Notion-Version"); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"rich_text\": \"string\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Notion-Version": "Notion-Version", "Content-Type": "application/json" ] let parameters = ["rich_text": "string"] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.notion.com/v1/comments")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```