Skip to content

Notion: Update a comment

Notion comments.updateAComment: arguments, response, policy and SDK examples.

← Comments operations · Get started

Operation notion.update_a_comment

Provider route: PATCH /v1/comments/{comment_id}. Alter supplies the connection’s credentials and routing.

Install @alter-ai/sdk @alter-ai/notion with npm, or alter-sdk-notion with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { NotionIntegration } from "@alter-ai/notion";
async function execute(input: Parameters<NotionIntegration["comments"]["updateAComment"]>[0]) {
const app = new App({ apiKey: process.env.ALTER_API_KEY! });
try {
const provider = new NotionIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
const call = await provider.comments.updateAComment(input);
const result = await call.wait();
return result.bodyJson();
} finally {
await app.close();
}
}
import os
from alter_sdk import App
from alter_sdk_notion import NotionIntegration
async def execute(arguments):
async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
provider = NotionIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
call = await provider.comments.update_a_comment(arguments)
result = await call.wait()
return result.body_json()
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
pathobjectRequired within parentAdditional keys: not allowed
path.comment_idstringRequired within parentThe ID of the comment to update.
bodyJSONRequired within parent
body (allOf 1)objectAll variants apply
body (allOf 1).markdown_versionstringOptionalThe Markdown syntax to use. `v2` is [Notion-flavored Markdown](/guides/data-apis/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`.
One of: v1, v2
body (allOf 2)JSONAll variants apply
body (allOf 2) (oneOf 1)objectAlternative
body (allOf 2) (oneOf 1).rich_textarrayRequired within parentAn array of rich text objects that represent the updated content of the comment.
Maximum items: 100
body (allOf 2) (oneOf 1).rich_text[]ModelEach itemExpand Create a database — request body — body title item
body (allOf 2) (oneOf 2)objectAlternative
body (allOf 2) (oneOf 2).markdownstringRequired within parentThe updated 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.

Referenced models: Create a database — request body — body title item

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

FieldTypePresenceDescription and constraints
$JSONRoot
$ (anyOf 1)ModelAlternativeExpand Create a comment — response body — object comment — partial Comment Object Response
$ (anyOf 2)ModelAlternativeExpand Create a comment — response body — object comment — comment Object Response

Referenced models: Create a comment — response body — object comment — comment Object Response, Create a comment — response body — object comment — partial Comment Object Response

27 more schemas are linked from the tables above, on the schema pages.

Create a comment — response body — object comment — comment Object Response
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: allowed
attachmentsarrayOptionalAny file attachments associated with the comment.
Maximum items: 100
attachments[]objectEach itemAdditional keys: allowed
attachments[].categorystringRequired within parentOne of: `audio`, `image`, `pdf`, `productivity`, `video`
Known values: audio, image, pdf, productivity, video
attachments[].fileModelRequired within parentExpand Get agent — response body — icon value File file
created_byModelRequired within parentExpand Update page — response body — object page created by
The user who created the comment.
created_timestringRequired within parentThe time when the comment was created.
Format: date-time
discussion_idstringRequired within parentThe ID of the discussion thread this comment belongs to.
Format: uuid
display_nameobjectRequired within parentThe display name of the comment.
Additional keys: allowed
display_name.resolved_nameJSONRequired within parent
display_name.resolved_name (anyOf 1)stringAlternative
display_name.resolved_name (anyOf 2)nullAlternative
display_name.typestringRequired within parentOne of: `custom`, `user`, `integration`
Known values: custom, user, integration
has_pending_attachmentsbooleanRequired within parentWhether any file attachments on this comment are still uploading. Pending files are not listed in `attachments` yet. A `comment.updated` webhook is sent when each upload finishes.
idstringRequired within parentThe ID of the comment.
Format: uuid
last_edited_timestringRequired within parentThe time when the comment was last edited.
Format: date-time
objectstringRequired within parentThe comment object type name.
Must equal: comment
original_content_deletedbooleanRequired within parentWhether this comment's original content was deleted.
parentModelRequired within parentExpand Create a comment — response body — object comment parent
The parent of the comment.
property_idstringOptionalThe ID of the database property the comment is on, for comments on a page property. Matches the property's `id` in the page object. Omitted for other comments.
rich_textarrayRequired within parentThe rich text content of the comment.
Maximum items: 100
rich_text[]ModelEach itemExpand Retrieve a page property item — response body — value Title title

Referenced models: Create a comment — response body — object comment parent, Get agent — response body — icon value File file, Update page — response body — object page created by, Retrieve a page property item — response body — value Title title

Create a comment — response body — object comment — partial Comment Object Response
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: allowed
idstringRequired within parentThe ID of the comment.
Format: uuid
objectstringRequired within parentThe comment object type name.
Must equal: comment
Create a database — request body — body title item
FieldTypePresenceDescription and constraints
$JSONRoot
$ (allOf 1)ModelAll variants applyExpand Create a database — request body — body title item annotations
$ (allOf 2)JSONAll variants apply
$ (allOf 2) (oneOf 1)ModelAlternativeExpand Create a database — request body — body title item value Text
$ (allOf 2) (oneOf 2)ModelAlternativeExpand Create a database — request body — body title item value Mention
$ (allOf 2) (oneOf 3)ModelAlternativeExpand Create a database — request body — body title item value Equation

Referenced models: Create a database — request body — body title item value Equation, Create a database — request body — body title item value Mention, Create a database — request body — body title item annotations, Create a database — request body — body title item value Text

Create a comment — response body — object comment parent
FieldTypePresenceDescription and constraints
$JSONRoot
$ (anyOf 1)ModelAlternativeExpand Create a comment — response body — object comment parent Page Id
$ (anyOf 2)ModelAlternativeExpand Create a comment — response body — object comment parent Block Id

Referenced models: Create a comment — response body — object comment parent Block Id, Create a comment — response body — object comment parent Page Id

Get agent — response body — icon value File file
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: allowed
expiry_timestringRequired within parentThe time when the URL will expire.
Format: date-time
urlstringRequired within parentThe URL of the file.
Update page — response body — object page created by
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: allowed
idstringRequired within parentFormat: uuid
objectstringRequired within parentAlways `user`
Must equal: user
Retrieve a page property item — response body — value Title title
FieldTypePresenceDescription and constraints
$JSONRoot
$ (allOf 1)ModelAll variants applyExpand Retrieve a page property item — response body — value Title title annotations, href, plain text
$ (allOf 2)JSONAll variants apply
$ (allOf 2) (anyOf 1)ModelAlternativeExpand Retrieve a page property item — response body — value Title title value Text
$ (allOf 2) (anyOf 2)ModelAlternativeExpand Retrieve a page property item — response body — value Title title value Mention
$ (allOf 2) (anyOf 3)ModelAlternativeExpand Retrieve a page property item — response body — value Title title value Equation

Referenced models: Retrieve a page property item — response body — value Title title value Equation, Retrieve a page property item — response body — value Title title value Mention, Retrieve a page property item — response body — value Title title annotations, href, plain text, Retrieve a page property item — response body — value Title title value Text

Create a database — request body — body title item value Equation
FieldTypePresenceDescription and constraints
$objectRoot
equationobjectRequired within parentNotion supports inline LaTeX equations as rich text objects with a type value of `equation`.
equation.expressionstringRequired within parentA KaTeX compatible string.
typestringOptionalAlways `equation`
Must equal: equation
Create a database — request body — body title item annotations
FieldTypePresenceDescription and constraints
$objectRoot
annotationsModelOptionalExpand Create a database — request body — body title item annotations annotations
All rich text objects contain an annotations object that sets the styling for the rich text.

Referenced models: Create a database — request body — body title item annotations annotations

Create a database — request body — body title item value Text
FieldTypePresenceDescription and constraints
$objectRoot
textobjectRequired within parentIf 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.
Additional keys: not allowed
text.contentstringRequired within parentThe actual text content of the text.
Maximum length: 2000
text.linkJSONOptionalAn object with information about any inline link in this text, if included.
text.link (oneOf 1)objectAlternative
text.link (oneOf 1).urlstringRequired within parentThe URL of the link.
text.link (oneOf 2)nullAlternative
typestringOptionalAlways `text`
Must equal: text

SDK function policy ID: notion.update_a_comment. Catalog operation: update_a_comment. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Pinned headers: {"Notion-Version": "2026-03-11"}

Official provider source

Report an issue with this page

Necessary

Required for sign-in, security, authorization, and remembering your choices.

Always active

Analytics

Helps us understand which product and documentation features are useful.

Performance diagnostics

Uses performance tracing and privacy-masked session replay to diagnose problems.

You can change these choices at any time from Cookie settings.