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": "ci@example.com"
  },
  "expected_ref_sha": "def789abc123..."
}

​
Request Body

​
sha
string
required
Commit SHA to attach the note to
​
action
string
Set to "add" to create a new note (default)
​
note
string
required
The note content
​
author
string
Object with name and email for the notes commit
​
expected_ref_sha
string
Expected 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

​
sha
string
The commit SHA the note is attached to
​
target_ref
string
The notes reference (refs/notes/commits)
​
base_commit
string
Previous notes ref commit SHA
​
new_ref_sha
string
New notes ref SHA after the operation
​
result
object
Operation 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

​
409 Conflict
string
Note already exists for this commit, or expected_ref_sha doesn’t match
​
401 Unauthorized
string
Invalid JWT or missing git:write scope
​
400 Bad Request
string
Missing required fields