mutatePackageReviewComment

POST /api/v1/review-packages/{packageId}/revisions/{revisionId}/comments

Normalized native package thread acknowledgement. Writes reuse app-native semantic threads on the exact current revision, require package read and comment write independently of publication write, and resolve/reopen/reattach additionally require commentary.comments.status. JSON bytes are capped at 256 KiB; native editing/repair permissions and licensing remain enforced. Agent edits cannot impersonate human or other Agent authors. No new comment CAS or retry ledger is introduced.

Access

Use a credential with commentary.review_packages.read, commentary.comments.write.

Provider access, workspace membership, and agent grants are enforced separately. A token does not expand access to a repository or resource. Set up developer access.

Parameters

Name	Location	Type	Required	Description
`packageId`	path	string	Yes
`revisionId`	path	string	Yes

Request body

Required. Supported content types: application/json.

Field	Type	Required	Description
`action`	`"create"` · `"reply"` · `"edit"` · `"resolve"` · `"reopen"` · `"reattach"`	Yes
`path`	string	No	Minimum length: 1. Maximum length: 1024.
`threadId`	string	No	Minimum length: 1. Maximum length: 512.
`commentId`	string	No	Minimum length: 1. Maximum length: 512.
`blockId`	string	No	Minimum length: 1. Maximum length: 512.
`documentVersionId`	string	No	Minimum length: 1. Maximum length: 512.
`nodeType`	string	No	Maximum length: 100.
`sourceLineStart`	integer	No
`sourceLineEnd`	integer	No
`bodyMarkdown`	string	No	Minimum length: 1. Maximum length: 20000.
`selectedText`	string	No	Maximum length: 4096.
`prefixText`	string	No	Maximum length: 4096.
`suffixText`	string	No	Maximum length: 4096.
`requestDecision`	boolean	No
`poll`	object	No

Call the endpoint

Replace path placeholders and your credential. For body operations, create request.json using the required fields above; this command does not invent resource identifiers or consent.

curl --request POST \
  'https://commentary.dev/api/v1/review-packages/<packageId>/revisions/<revisionId>/comments' \
  --header 'Authorization: Bearer <your-token>' \
  --header 'Content-Type: application/json' \
  --data-binary @request.json

Responses

Status	Meaning	Payload
`200`	Private upload status or immutable package revision result.	ProjectAgentmutatePackageReviewCommentOutput
`400`	Invalid manifest/chunk/checksum or missing retry key.	See response headers or body contract
`401`	Authentication required.	See response headers or body contract
`403`	Current actor/workspace/grant access denied.	See response headers or body contract
`409`	Expired/canceled upload, missing chunks, or conflicting retry.	See response headers or body contract
`413`	Actual request bytes exceed the bound.	See response headers or body contract
`429`	Rate limit exceeded.	See response headers or body contract

Successful response fields

Field	Type	Required	Description
`data`	object	Yes
`idempotencyReplayed`	boolean	No

Recover from errors

Use the returned status and error body. Correct invalid fields before retrying; reconnect or narrow the target for authentication and permission errors. For conditional writes, reload the latest version before preparing a new request. Respect rate-limit headers and retry only when the operation’s idempotency contract permits it.

Operation ID: mutatePackageReviewComment. Download the OpenAPI contract for complete constraints and code generation. Browse endpoints.