The Comments API lets external tools take part in the review conversation on a deployment request. A CI pipeline, static analysis tool, or bot can read the discussion, post findings as comments, point at specific lines of the diff, reply to threads, and resolve them when the issue is fixed.

Comments posted through the API appear in the deployment request's discussion in the app, exactly like comments written by a teammate.

Who the comment is from

Every comment is authored as the user that owns the OAuth client making the request. If you want comments to be clearly attributed to an automation, create the OAuth client under a dedicated user, such as "CI Bot".

Top-level and inline comments

There are two kinds of comments:

• Top-level comments are posted on the deployment request as a whole. Send only a body. They cannot be replied to or resolved, and their resolvable field is false.
• Inline comments are attached to a line of the deployment's diff. Send a path and a newLine (a line in the new version of the file) and/or an oldLine (a line in the old version). Each inline comment starts a thread: its resolvable field is true, and it can be replied to and resolved.

Comment bodies are Markdown.

Anchoring inline comments to the diff

An inline comment is pinned to a specific diff, identified by a base and head commit. By default the comment uses the deployment's current diff: the targetCommit and mergeCommit returned by Get a deployment by number. You can pass baseSha and headSha yourself to pin the comment to the exact commits your tool analyzed. You must pass both or neither.

Both commits are null until the deployment's diff has been computed. Posting an inline comment without baseSha/headSha before then returns 409.

Threads

Each comment has a discussionId that identifies its thread. Replies share the discussionId of the comment they reply to. Use this value with the discussion endpoints:

• POST /deployments/{deploymentNumber}/discussions/{discussionId}/comments adds a reply.
• PUT /deployments/{deploymentNumber}/discussions/{discussionId} with {"resolved": true} resolves the thread, and {"resolved": false} reopens it.

Only inline comment threads accept replies and can be resolved. Using a top-level comment's discussionId returns 400.

Example: report a finding and resolve it later

1. Post an inline comment on the offending line:

curl -X POST "https://COMPANY.my.bluecanvas.io/apis/rest/v1/deployments/154/comments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body": "Coverage dropped below 75% in this class.", "path": "src/classes/Invoice.cls", "newLine": 42}'

2. Save the id and discussionId from the response.

3. On a later run, once the issue is fixed, resolve the thread:

curl -X PUT "https://COMPANY.my.bluecanvas.io/apis/rest/v1/deployments/154/discussions/6a9c41d2e8b0f3a7c5e1d9b2a4f6c8e0d1b3a5c7" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"resolved": true}'

To avoid posting duplicate findings on every run, list the comments first and skip any your client already posted.

When comments become available

The discussion behind a deployment request is created asynchronously, a few moments after the deployment request itself, and never for drafts. Until then:

• Listing comments returns an empty list.
• Posting, replying, resolving, or deleting returns 409 with "Deployment has no merge request yet. Retry shortly". Retry after a short delay.

Deleting comments

Delete a comment removes a single comment by its id. Only the comment's author can delete it, so a client can delete its own comments but not those of other users (403).

Errors

Errors return a JSON body with an error message:

{
  "error": "Discussion not found"
}