Skip to main content
Append content to an existing note (creates if it doesn’t exist). 
POST /api/v1/repos/notes
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "sha": "abc123def456789...",
  "action": "append",
  "note": "\n---\nReviewed by @alice - LGTM",
  "author": {
    "name": "Review Bot",
    "email": "[email protected]"
  }
}

​
Request Body

ParameterTypeDescription
shaRequiredCommit SHA to attach the note to
actionRequiredSet to "append" to append to an existing note
noteRequiredThe note content to append
authorOptionalObject with name and email for the notes commit
expected_ref_shaOptionalExpected notes ref SHA for optimistic concurrency control

​
JWT Requirements

  • The JWT must include the repository in the repo claim
  • Requires git:write scope

​
Response

{
  "sha": "abc123def456789...",
  "target_ref": "refs/notes/commits",
  "base_commit": "previous123...",
  "new_ref_sha": "newref456...",
  "result": {
    "success": true,
    "status": "ok",
    "message": ""
  }
}

​
Response Fields

FieldTypeDescription
shaStringThe commit SHA the note is attached to
target_refStringThe notes reference (refs/notes/commits)
base_commitOptionalPrevious notes ref commit SHA
new_ref_shaStringNew notes ref SHA after the operation
resultObjectOperation result with success, status, and optional message

​
Notes

  • Use action: "append" to add content to an existing note
  • If no note exists, one will be created
  • Useful for accumulating multiple annotations on the same commit (e.g., multiple CI results)

​
Error Responses

StatusDescription
409 Conflictexpected_ref_sha doesn’t match current notes ref
401 UnauthorizedInvalid JWT or missing git:write scope
400 Bad RequestMissing required fields