/pending-approvals/{pendingId}/commentsAdd Comment
Adds a comment to a pending change.
A comment is never a decision: it changes no status, counts toward no approval rule, and doesn't extend the expiry.
visibility is required and fixed once posted:
everyonereaches everyone who can read the change.approvers_onlyreaches only people eligible to decide it, never the person who asked for it or anyone acting for them.
Someone eligible to decide the change may post either kind; the person who asked for it may post everyone comments only. body is plain text of 1 to 4,000 characters; there's no edit or delete, so a correction is a new comment.
Requires a session: a personal access token alone, or a service, workload or extension token, is refused.
Returns K9O_APPROVAL_COMMENT_NOT_ELIGIBLE (403) when the caller may not post this comment, and K9O_APPROVAL_COMMENT_CLOSED (409) once the change is decided, expired or cancelled.
The audit event approval.comment_added carries the comment id, the change id, the visibility and the author's id, never the text.
| pendingId * | path | The pending change's id ( |
| projectSlug * | path | The project's slug: the path segment after It is unique within the org. |
| body * | string | Plain text, 1 to 4,000 characters. |
| visibility * | "everyone" | "approvers_only" | Required. |
| HTTP | K9O Code | Description |
|---|---|---|
| 201 | Created | |
| 400 | K9O_INVALID_FIELD_VALUE | The body is malformed: `visibility` is missing or not `everyone` or `approvers_only`, `body` is missing, blank, longer than 4,000 characters or holds a NUL character, or an unknown field is present. |
| 401 | K9O_SESSION_EXPIRED | The caller's session token is expired or invalid; re-authenticate to continue. |
| 403 | K9O_RBAC_DENY | A session is required to comment: a personal access token alone is refused with `context.reason` `session_required`, and a service, workload or extension token with `human_only`. |
| 403 | K9O_APPROVAL_COMMENT_NOT_ELIGIBLE | The caller may not post this comment: only someone eligible to decide the case may post, and the person who asked for it may post `everyone` comments only. |
| 404 | K9O_NOT_FOUND | No pending change with this id exists in this project. |
| 409 | K9O_APPROVAL_COMMENT_CLOSED | The case is decided, expired or cancelled, so it takes no new comments; existing comments stay readable. |
| data * | object | A comment on an approval case. |
| id * | string | The comment's id ( |
| caseId * | string | The id of the pending change or gate the comment is on ( |
| authorId * | string | The author's opaque user id. |
| visibility * | "everyone" | "approvers_only" | Fixed when posted. |
| body * | string | Plain text. Render it as text, never as HTML. |
| createdAt * | string <date-time> | When the comment was posted. |
| meta * | object | Request metadata: cost, timing and correlation ids. |
| cost * | object | Metered usage for this request; empty when nothing was metered. |
| timing * | object | |
| gatewayMs * | number | |
| totalMs * | number | |
| context * | object | |
| requestId * | string | |
| traceId * | string | |
| projectId | string | |
| warnings | object[] | |
| code * | string | |
| message * | string |
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.approvals.comments.add('apr_3Lq9Wx2Km7Rp5Tz8', {
body: 'The refund amount doesn\'t match the order total. Can you check the line items?',
visibility: 'everyone'
})Showing example in TypeScript
{
"body": "The refund amount doesn't match the order total. Can you check the line items?",
"visibility": "everyone"
}{
"data": {
"id": "string",
"caseId": "string",
"authorId": "string",
"visibility": "everyone",
"body": "string",
"createdAt": "string"
},
"meta": {
"timing": {
"gatewayMs": 0,
"totalMs": 0
},
"context": {
"requestId": "string",
"traceId": "string",
"projectId": "string"
},
"warnings": [
{
"code": "string",
"message": "string"
}
]
}
}