Create note

POST /api/v1/repos/notes

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": "[e-mail]"
  },
  "expected_ref_sha": "def789abc123..."
}

Request Body

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

Field	Type	Description
sha	String	The commit SHA the note is attached to
target_ref	String	The notes reference (refs/notes/commits)
base_commit	Optional	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

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