repos.notes.create

POST

api

repos

{repo_name}

notes

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: 'review@example.com', name: 'Review Bot' },
  note: 'Reviewed. Ready for production.',
  notes_ref: 'refs/notes/commits',
  object_ref: 'b003fc78805954584e1ee364a4ad39d7c79e819a',
});
console.log(note);

from pierre import Pierre

# The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.
pierre = Pierre()

note = pierre.repos.notes.create(
    repo_name="my-demo-repository",
    author={"email": "review@example.com", "name": "Review Bot"},
    note="Reviewed. Ready for production.",
    notes_ref="refs/notes/commits",
    object_ref="b003fc78805954584e1ee364a4ad39d7c79e819a",
)
print(note)

import (
	"context"
	"fmt"

	pierre "github.com/pierrecomputer/sdk/go"
)

ctx := context.Background()
// The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.
client, err := pierre.NewClient()
if err != nil {
	return err
}
note, err := client.Repos.Notes.Create(ctx, pierre.ReposNotesCreateParams{
	RepoName:  "my-demo-repository",
	Author:    pierre.Value(pierre.GitIdentity{Email: "review@example.com", Name: "Review Bot"}),
	Note:      pierre.String("Reviewed. Ready for production."),
	NotesRef:  pierre.String("refs/notes/commits"),
	ObjectRef: pierre.String("b003fc78805954584e1ee364a4ad39d7c79e819a"),
})
if err != nil {
	return err
}
fmt.Println(note)

pierre repos:notes create \
  --repo-name my-demo-repository \
  --author.email review@example.com \
  --author.name 'Review Bot' \
  --note 'Reviewed. Ready for production.' \
  --notes-ref refs/notes/commits \
  --object-ref b003fc78805954584e1ee364a4ad39d7c79e819a

curl -X POST \
  "https://api.{org}.code.storage/api/repos/my-demo-repository/notes" \
  -H "Authorization: Bearer $PIERRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "author": {
      "email": "review@example.com",
      "name": "Review Bot"
    },
    "note": "Reviewed. Ready for production.",
    "notes_ref": "refs/notes/commits",
    "object_ref": "b003fc78805954584e1ee364a4ad39d7c79e819a"
  }'

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

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>",
  "invalid_params": [
    {
      "name": "deployment.production_branch",
      "reason": "exceeds 255 characters"
    }
  ]
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

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.

Scopes

git:write

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

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"

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: 'review@example.com', name: 'Review Bot' },
  note: 'Reviewed. Ready for production.',
  notes_ref: 'refs/notes/commits',
  object_ref: 'b003fc78805954584e1ee364a4ad39d7c79e819a',
});
console.log(note);

from pierre import Pierre

# The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.
pierre = Pierre()

note = pierre.repos.notes.create(
    repo_name="my-demo-repository",
    author={"email": "review@example.com", "name": "Review Bot"},
    note="Reviewed. Ready for production.",
    notes_ref="refs/notes/commits",
    object_ref="b003fc78805954584e1ee364a4ad39d7c79e819a",
)
print(note)

import (
	"context"
	"fmt"

	pierre "github.com/pierrecomputer/sdk/go"
)

ctx := context.Background()
// The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.
client, err := pierre.NewClient()
if err != nil {
	return err
}
note, err := client.Repos.Notes.Create(ctx, pierre.ReposNotesCreateParams{
	RepoName:  "my-demo-repository",
	Author:    pierre.Value(pierre.GitIdentity{Email: "review@example.com", Name: "Review Bot"}),
	Note:      pierre.String("Reviewed. Ready for production."),
	NotesRef:  pierre.String("refs/notes/commits"),
	ObjectRef: pierre.String("b003fc78805954584e1ee364a4ad39d7c79e819a"),
})
if err != nil {
	return err
}
fmt.Println(note)

pierre repos:notes create \
  --repo-name my-demo-repository \
  --author.email review@example.com \
  --author.name 'Review Bot' \
  --note 'Reviewed. Ready for production.' \
  --notes-ref refs/notes/commits \
  --object-ref b003fc78805954584e1ee364a4ad39d7c79e819a

curl -X POST \
  "https://api.{org}.code.storage/api/repos/my-demo-repository/notes" \
  -H "Authorization: Bearer $PIERRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "author": {
      "email": "review@example.com",
      "name": "Review Bot"
    },
    "note": "Reviewed. Ready for production.",
    "notes_ref": "refs/notes/commits",
    "object_ref": "b003fc78805954584e1ee364a4ad39d7c79e819a"
  }'

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

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>",
  "invalid_params": [
    {
      "name": "deployment.production_branch",
      "reason": "exceeds 255 characters"
    }
  ]
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

Getting Started

Platform

Workflows

Libraries

API Reference

Authorizations

Scopes

Path Parameters

Body

Response