repos.notes.create

Attach text to a Git object without changing the repository contents. Use notes for review markers, internal decisions, or other lightweight context. To add text to a note, use POST /notes/append.

Scope: git:write on the repository.

POST /api/repos/{repo_name}/notes

TypeScript

TypeScript

import { Pierre } from '@pierre/sdk';

// The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.
const pierre = new Pierre();

const note = await pierre.repos.notes.create({
  repo_name: 'my-demo-repository',
  author: { email: '[e-mail]', name: 'Review Bot' },
  note: 'Reviewed. Ready for production.',
  notes_ref: 'refs/notes/commits',
  object_ref: 'b003fc78805954584e1ee364a4ad39d7c79e819a',
});
console.log(note);

201

{
  "base_commit": "0c8b5bb9d550d58fcfd651a4fdce8024ef7f1492",
  "new_ref_sha": "3a1d9f7d6b6d482c970554e2a6ef980ecf4f1d55",
  "notes_ref": "refs/notes/commits",
  "result": {
    "status": "ok",
    "success": true
  },
  "sha": "b003fc78805954584e1ee364a4ad39d7c79e819a"
}

Authorizations

Authorization · string · header · required

JWT bearer token signed with your organization's registered signing key. There is no OAuth authorization server; you mint tokens yourself and the token's scopes claim carries the granted permission scopes. Public scopes: git:read (read repository contents), git:write (write branches, commits, tags, and notes), repo:write (create and manage repositories), org:read (list an organization's repositories). Each operation's security requirement names the scopes it requires. See https://code.storage/docs/getting-started/authentication for how to mint tokens.

Path Parameters

repo_name · string · required

The repository name, for example acme/web.

Body

application/json

Create a Git note for the supplied object_ref. The request fails with 409 if the object already has a note. Set notes_ref to target a notes ref other than refs/notes/commits; a bare name like reviews is accepted and placed under refs/notes/. The deprecated action: append appends, as POST /notes/append does.

Create-note request describing the Git object, the note content, and the optional notes ref guard.

action · string · default: add · deprecated

Deprecated: use POST /notes/append to append. add creates a note and fails if one already exists. append adds text to the note, and creates the note if none exists.

author · object

Author object with name and email for the notes commit.

Show child attributes

expected_notes_ref_sha · string

Optional compare-and-swap guard for the notes ref. Provide expected_notes_ref_sha or the deprecated expected_ref_sha.

expected_ref_sha · string · deprecated

Deprecated: use expected_notes_ref_sha. Optional compare-and-swap guard for the notes ref.

note · string

Plain-text note content. Required.

Example:

"Reviewed. Ready for production."

notes_ref · string

Optional notes ref to target. A bare name like reviews is placed under refs/notes/; a fully-qualified refs/notes/* ref is also accepted. Defaults to refs/notes/commits. Provide notes_ref or the deprecated ref.

Example:

"refs/notes/commits"

object_ref · string

Git object the note attaches to: a full object SHA (a commit, tree, blob, or annotated tag), or a branch, tag, or other revision that resolves to a commit. Provide object_ref or the deprecated sha.

Example:

"b003fc78805954584e1ee364a4ad39d7c79e819a"

ref · string · deprecated

Deprecated: use notes_ref. Optional notes ref to target.

Example:

"refs/notes/commits"

sha · string · deprecated

Deprecated: use object_ref. Git object SHA to attach the note to.

Example:

"b003fc78805954584e1ee364a4ad39d7c79e819a"

Response

201

application/json

Note update applied to the notes ref.

Result of a notes write operation, including the resulting notes ref state.

new_ref_sha · string · required

New notes ref SHA after the operation.

Example:

"3a1d9f7d6b6d482c970554e2a6ef980ecf4f1d55"

notes_ref · string · required

The notes ref the operation updates.

Example:

"refs/notes/commits"

result · object · required

Operation result with success, status, and optional message.

Show child attributes

sha · string · required

The commit SHA the note is attached to.

Example:

"b003fc78805954584e1ee364a4ad39d7c79e819a"

target_ref · string · required · deprecated

Deprecated: use notes_ref. The notes ref the operation updates.

Example:

"refs/notes/commits"

base_commit · string

Previous notes ref commit SHA.

Example:

"0c8b5bb9d550d58fcfd651a4fdce8024ef7f1492"