Skip to main content
Create a new note on a commit. 
POST /api/v1/repos/notes
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "sha": "abc123def456789...",
  "action": "add",
  "note": "Build passed ✓ - deployed to staging",
  "author": {
    "name": "CI Bot",
    "email": "[email protected]"
  },
  "expected_ref_sha": "def789abc123..."
}

​
Request Body

ParameterTypeDescription
shaRequiredCommit SHA to attach the note to
actionOptionalSet to "add" to create a new note (default)
noteRequiredThe note content
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: "add" to create a new note (fails if note already exists)
  • Use the Append note endpoint to add to an existing note
  • The expected_ref_sha parameter enables optimistic concurrency control

​
Error Responses

StatusDescription
409 ConflictNote already exists for this commit, or expected_ref_sha doesn’t match
401 UnauthorizedInvalid JWT or missing git:write scope
400 Bad RequestMissing required fields