Skip to main content
POST/pending-approvals/{pendingId}/comments

Add 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:

  • everyone reaches everyone who can read the change.
  • approvers_only reaches 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.

Parameters
pendingId *path

The pending change's id (apr_...).

projectSlug *path

The project's slug: the path segment after @.

It is unique within the org.

Request body
body *string

Plain text, 1 to 4,000 characters.

visibility *"everyone" | "approvers_only"

Required. everyone: everyone who can read the case. approvers_only: only people eligible to decide it; the person who asked for the change can't post or see these.

Responses
HTTPK9O CodeDescription
201Created
400K9O_INVALID_FIELD_VALUEThe 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.
401K9O_SESSION_EXPIREDThe caller's session token is expired or invalid; re-authenticate to continue.
403K9O_RBAC_DENYA 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`.
403K9O_APPROVAL_COMMENT_NOT_ELIGIBLEThe 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.
404K9O_NOT_FOUNDNo pending change with this id exists in this project.
409K9O_APPROVAL_COMMENT_CLOSEDThe case is decided, expired or cancelled, so it takes no new comments; existing comments stay readable.
Response body (201)
data *object

A comment on an approval case.

id *string

The comment's id (acm_...).

caseId *string

The id of the pending change or gate the comment is on (apr_...).

authorId *string

The author's opaque user id.

visibility *"everyone" | "approvers_only"

Fixed when posted. approvers_only comments are returned only to people eligible to decide the case, never to the person who asked for it.

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
projectIdstring
warningsobject[]
code *string
message *string
TypeScript
// 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

Request example
{
  "body": "The refund amount doesn't match the order total. Can you check the line items?",
  "visibility": "everyone"
}
Response example (201)
{
  "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"
      }
    ]
  }
}

More in Policy & Approvals