> ## Documentation Index > Fetch the complete documentation index at: https://code.storage/docs/llms.txt > Use this file to discover all available pages before exploring further. # repos.notes.delete > Remove the Git note attached to a commit or other Git object. Name the note with the query parameters of `GET /notes`. The notes commit of the delete has the default author. Scope: `git:write` on the repository. ## OpenAPI ````yaml openapi.json DELETE /api/repos/{repo_name}/notes openapi: 3.1.0 info: description: >- The Code Storage HTTP API exposes repository management, Git reads, and write workflows over plain HTTPS. ## Authentication Send a signed JWT in the `Authorization: Bearer ` header on every request. - Organisation-scoped endpoints such as `GET /api/repos` require organisation scopes like `org:read` - Repository-scoped endpoints require a JWT whose `repo` claim names the target repository - Write operations require the relevant scope such as `git:write` or `repo:write` ## Pagination List endpoints use cursor-based pagination. - `cursor` is an opaque token returned by the previous response - `limit` defaults to `20` and is capped per endpoint - `has_more` tells you whether another request is available - `next_cursor` becomes the next `cursor` value ## Paths Preferred routes use the shorter `/api/...` form. Legacy `/api/v1/...` aliases remain documented where they are still supported and are marked as deprecated when a preferred route exists. ## Repository names in paths - Names containing `/` (or any other character that is not safe in a URL path segment) **must** be URL encoded so the value occupies a single path segment. For example, `pierre/example` becomes `pierre%2Fexample` and the request URL is `/api/repos/pierre%2Fexample/...`. - Plain names that contain only URL-safe characters can be sent as-is: `/api/repos/dotfiles/...`. - The server URL-decodes the value before resolving the repository, so double-encoding is not required. ## Errors Most endpoints return RFC 9457-compatible problem details under `application/problem+json`, with a legacy `error` field mirrored from `detail`. Each problem body has a stable, snake_case `code`. Branch on `code`, not on `detail`. The Error codes section lists the values. A `400 Bad Request` response for a request body can name the invalid fields in `invalid_params`. Each item has the dotted path of the field in `name`, for example `deployment.production_branch`, and the rule that the value breaks in `reason`. A `429 Too Many Requests` response carries the current IETF `RateLimit` service-limit field and `Retry-After`. `RateLimit` reports immediately available quota (`r`) and its effective window in seconds (`t`); `Retry-After` is the minimum delay and takes precedence. The gateway's capacity is dynamic, so it does not advertise a fixed `RateLimit-Policy` on successful responses. Streaming commit and note workflows may return operation-specific failure bodies so callers can inspect partial results, branch state, or workflow status without parsing generic error strings. ## Error codes Each problem body has a stable `code`. Each status has a generic code. A specific code replaces it when the caller must take a different action. New codes can be added. Treat an unknown code as the generic code for its status. Generic codes: `bad_request` (400), `unauthorized` (401), `forbidden` (403), `not_found` (404), `method_not_allowed` (405), `request_timeout` (408), `conflict` (409), `precondition_failed` (412), `payload_too_large` (413), `unprocessable_entity` (422), `rate_limited` (429), `request_canceled` (499), `internal_error` (500), `not_implemented` (501), `bad_gateway` (502), `service_unavailable` (503), `gateway_timeout` (504). Any other status uses its status text in snake_case. Specific codes: - `authentication_unavailable` (403): the server cannot verify credentials now; retry. - `insufficient_scope` (403): the token does not have a scope that the operation requires. - `repo_claim_missing` (400): the token has no `repo` claim. - `repo_name_mismatch` (400): the request `repo_name` does not match the token `repo` claim. - `route_not_found` (404): no API route matches the path. - `repository_not_found` (404): the repository does not exist or the token cannot access it. - `repository_deleted` (409): the repository is already deleted. - `repository_thawing` (409): the repository is being restored from cold storage; retry after `Retry-After`. - `sync_in_progress` (409): an upstream sync is in progress; retry. - `upstream_already_configured` (409): the repository already has an upstream. - `branch_not_found` (404): the branch does not exist. - `ref_not_found` (404): the ref or revision does not exist. - `merge_conflict` (409): the merge has file conflicts. - `ref_guard_failed` (409): a ref guard such as `expected_target_sha` does not match the ref; `guard` names it and `current_sha` is the commit of the ref. - `credential_not_found` (404): the Git credential does not exist. - `credential_exists` (409): the repository already has a Git credential. - `github_app_not_configured` (412): no GitHub App is set up for the organization, or the GitHub App of the repository has no usable private key. - `github_repository_inaccessible` (412, or the 4xx status from the upstream): GitHub does not give access to the upstream repository. - `hosting_not_enabled` (403): hosting is not enabled for the organization. - `hosting_project_not_found` (404): the repository has no hosting project. - `deployment_not_found` (404): the deployment does not exist. - `deployment_project_name_in_use` (409): another repository uses the hosting project name. - `idempotency_key_reused` (422): the idempotency key belongs to a different request. title: code.storage version: 1.0.0 servers: - description: Code Storage API host for your organization url: https://api.{org}.code.storage variables: org: default: your-org description: >- The subdomain of your API host. It is usually your organization name. The organization settings page in the dashboard shows your exact API host. security: [] tags: - description: >- Create, inspect, update, delete, and synchronise repositories, including upstream pull-sync and generic HTTPS Git credentials for non-GitHub upstreams. name: Repositories - description: Create, delete, list, and compare branches. name: Branches - description: >- Read commit metadata and diffs, or create commits without a local Git client. name: Commits - description: >- Read repository trees, file contents, archives, and server-side search results. name: Files - description: List, create, and delete Git tags. name: Tags - description: Attach and retrieve Git notes for commits or other Git objects. name: Notes - description: >- Read metadata about the Code Storage cluster that serves your organisation, such as its cloud location and inbound IP addresses. name: Organization paths: /api/repos/{repo_name}/notes: delete: tags: - Notes summary: Delete Note description: >- Remove the Git note attached to a commit or other Git object. Name the note with the query parameters of `GET /notes`. The notes commit of the delete has the default author. Scope: `git:write` on the repository. operationId: repos-notes-delete parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string - description: >- Git object whose note should be deleted: a full object SHA (a commit, tree, blob, or annotated tag), or a branch, tag, or other revision that resolves to a commit. Required unless the deprecated body names the object. example: b003fc78805954584e1ee364a4ad39d7c79e819a in: query name: object_ref schema: type: string - description: >- Optional notes ref to delete from. A bare name like reviews is placed under refs/notes/; a fully-qualified refs/notes/* ref is also accepted. Defaults to refs/notes/commits. example: refs/notes/commits in: query name: notes_ref schema: type: string - description: >- Optional compare-and-swap guard: the notes ref SHA that you read before the delete. The delete fails with 409 when the notes ref has a different SHA. example: 0c8b5bb9d550d58fcfd651a4fdce8024ef7f1492 in: query name: expected_notes_ref_sha schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ReposNotesDeleteRequest' description: >- Deprecated: send the `object_ref`, `notes_ref`, and `expected_notes_ref_sha` query parameters, and no body. A query parameter wins over its body field. responses: '201': content: application/json: example: base_commit: 0c8b5bb9d550d58fcfd651a4fdce8024ef7f1492 new_ref_sha: 3a1d9f7d6b6d482c970554e2a6ef980ecf4f1d55 notes_ref: refs/notes/commits result: status: ok success: true sha: b003fc78805954584e1ee364a4ad39d7c79e819a schema: $ref: '#/components/schemas/NotesWriteResponse' description: Note removed from the notes ref. '400': content: application/json: schema: $ref: '#/components/schemas/ValidationProblemDetails' application/problem+json: schema: $ref: '#/components/schemas/ValidationProblemDetails' description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: Unauthorized '403': content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: Forbidden '404': content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: Not Found '409': content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' application/problem+json: example: type: about:blank title: Conflict status: 409 detail: >- notes ref mismatch: got c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2, expected d34db33fd34db33fd34db33fd34db33fd34db33f code: ref_guard_failed error: >- notes ref mismatch: got c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2, expected d34db33fd34db33fd34db33fd34db33fd34db33f guard: expected_notes_ref_sha current_sha: c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 sha: b003fc78805954584e1ee364a4ad39d7c79e819a notes_ref: refs/notes/commits target_ref: refs/notes/commits new_ref_sha: '' result: success: false status: conflict message: >- notes ref mismatch: got c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2, expected d34db33fd34db33fd34db33fd34db33fd34db33f schema: $ref: '#/components/schemas/NotesWriteRefGuardProblemDetails' description: >- Conflict. When `expected_notes_ref_sha` is not the SHA of the notes ref, the body is `application/problem+json` with the code `ref_guard_failed`: `guard` names the guard, and `current_sha` is the SHA of the notes ref, or 40 zeros when the notes ref does not exist. The body keeps the members of the failure body, and `result.status` is `conflict`. '429': content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: Too Many Requests headers: RateLimit: description: >- Current IETF service-limit field. `r=0` means no request is immediately available; `t` is the effective window in seconds before capacity is expected to return. schema: type: string Retry-After: description: >- Minimum delay before retrying, expressed as seconds or an HTTP date. This value takes precedence over the `RateLimit` effective window. schema: type: string '500': content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: Internal Server Error '503': content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: Service Unavailable headers: Retry-After: description: Minimum delay in seconds before retrying. schema: type: string security: - bearerAuth: - git:write x-codeSamples: - lang: typescript label: TypeScript source: |- import { Pierre } from '@pierre/sdk'; // The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY. const pierre = new Pierre(); const result = await pierre.repos.notes.delete({ repo_name: 'my-demo-repository', expected_notes_ref_sha: '0c8b5bb9d550d58fcfd651a4fdce8024ef7f1492', notes_ref: 'refs/notes/commits', object_ref: 'b003fc78805954584e1ee364a4ad39d7c79e819a', }); console.log(result); - lang: python label: Python source: |- from pierre import Pierre # The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY. pierre = Pierre() result = pierre.repos.notes.delete( repo_name="my-demo-repository", expected_notes_ref_sha="0c8b5bb9d550d58fcfd651a4fdce8024ef7f1492", notes_ref="refs/notes/commits", object_ref="b003fc78805954584e1ee364a4ad39d7c79e819a", ) print(result) - lang: go label: Go source: "import (\n\t\"context\"\n\t\"fmt\"\n\n\tpierre \"github.com/pierrecomputer/sdk/go\"\n)\n\nctx := context.Background()\n// The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.\nclient, err := pierre.NewClient()\nif err != nil {\n\treturn err\n}\nresult, err := client.Repos.Notes.Delete(ctx, pierre.ReposNotesDeleteParams{\n\tRepoName: \"my-demo-repository\",\n\tExpectedNotesRefSHA: pierre.String(\"0c8b5bb9d550d58fcfd651a4fdce8024ef7f1492\"),\n\tNotesRef: pierre.String(\"refs/notes/commits\"),\n\tObjectRef: pierre.String(\"b003fc78805954584e1ee364a4ad39d7c79e819a\"),\n})\nif err != nil {\n\treturn err\n}\nfmt.Println(result)" - lang: cli label: CLI source: |- pierre repos:notes delete \ --repo-name my-demo-repository \ --expected-notes-ref-sha 0c8b5bb9d550d58fcfd651a4fdce8024ef7f1492 \ --notes-ref refs/notes/commits \ --object-ref b003fc78805954584e1ee364a4ad39d7c79e819a - lang: bash label: cURL source: |- curl -X DELETE \ "https://api.{org}.code.storage/api/repos/my-demo-repository/notes?expected_notes_ref_sha=0c8b5bb9d550d58fcfd651a4fdce8024ef7f1492¬es_ref=refs/notes/commits&object_ref=b003fc78805954584e1ee364a4ad39d7c79e819a" \ -H "Authorization: Bearer $PIERRE_TOKEN" components: schemas: ReposNotesDeleteRequest: additionalProperties: false description: >- Deprecated delete-note body. Use the object_ref, notes_ref, and expected_notes_ref_sha query parameters. properties: action: deprecated: true description: 'Deprecated: a delete ignores action.' type: string author: $ref: '#/components/schemas/GitIdentity' deprecated: true description: >- Deprecated: no replacement. Without author, the notes commit of a delete has the default author. Author object with name and email for the notes commit. expected_notes_ref_sha: deprecated: true description: >- Deprecated: use the expected_notes_ref_sha query parameter. Optional compare-and-swap guard for the notes ref. type: string expected_ref_sha: deprecated: true description: >- Deprecated: use the expected_notes_ref_sha query parameter. Optional compare-and-swap guard for the notes ref. type: string note: deprecated: true description: 'Deprecated: a delete ignores note.' type: string notes_ref: deprecated: true description: >- Deprecated: use the notes_ref query parameter. Optional notes ref to target. examples: - refs/notes/commits type: string object_ref: deprecated: true description: >- Deprecated: use the object_ref query parameter. Git object the note attaches to. examples: - b003fc78805954584e1ee364a4ad39d7c79e819a type: string ref: deprecated: true description: >- Deprecated: use the notes_ref query parameter. Optional notes ref to target. examples: - refs/notes/commits type: string sha: deprecated: true description: >- Deprecated: use the object_ref query parameter. Git object SHA the note attaches to. examples: - b003fc78805954584e1ee364a4ad39d7c79e819a type: string type: object NotesWriteResponse: additionalProperties: false description: >- Result of a notes write operation, including the resulting notes ref state. properties: base_commit: description: Previous notes ref commit SHA. examples: - 0c8b5bb9d550d58fcfd651a4fdce8024ef7f1492 type: string new_ref_sha: description: New notes ref SHA after the operation. examples: - 3a1d9f7d6b6d482c970554e2a6ef980ecf4f1d55 type: string notes_ref: description: The notes ref the operation updates. examples: - refs/notes/commits type: string result: $ref: '#/components/schemas/NotesWriteResult' description: Operation result with success, status, and optional message. sha: description: The commit SHA the note is attached to. examples: - b003fc78805954584e1ee364a4ad39d7c79e819a type: string target_ref: deprecated: true description: 'Deprecated: use notes_ref. The notes ref the operation updates.' examples: - refs/notes/commits type: string required: - sha - notes_ref - target_ref - new_ref_sha - result type: object ValidationProblemDetails: allOf: - $ref: '#/components/schemas/ProblemDetails' - properties: invalid_params: description: >- The invalid fields of the request body, one item for each field. The response leaves it out when the server cannot name the field, for example when the body is not valid JSON. items: $ref: '#/components/schemas/InvalidParam' type: array type: object description: >- Problem details of a request body that is not valid. `invalid_params` names each invalid field. type: object ProblemDetails: description: >- RFC 9457-compatible problem details payload describing the error response. properties: code: description: >- A stable, machine-readable error code in snake_case. Branch on `code`, not on `detail`. The API description lists the codes. type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status - code type: object NotesWriteRefGuardProblemDetails: allOf: - $ref: '#/components/schemas/RefGuardProblemDetails' - properties: base_commit: description: Previous notes ref commit SHA. examples: - 0c8b5bb9d550d58fcfd651a4fdce8024ef7f1492 type: string new_ref_sha: description: New notes ref SHA after the operation. examples: - 3a1d9f7d6b6d482c970554e2a6ef980ecf4f1d55 type: string notes_ref: description: The notes ref the operation updates. examples: - refs/notes/commits type: string result: $ref: '#/components/schemas/NotesWriteResult' description: Operation result with success, status, and optional message. sha: description: The commit SHA the note is attached to. examples: - b003fc78805954584e1ee364a4ad39d7c79e819a type: string target_ref: deprecated: true description: 'Deprecated: use notes_ref. The notes ref the operation updates.' examples: - refs/notes/commits type: string required: - sha - notes_ref - target_ref - new_ref_sha - result type: object description: >- Problem details of a notes write whose `expected_notes_ref_sha` guard failed. The body keeps the members of the notes write body. type: object GitIdentity: additionalProperties: false description: Author or committer identity for a commit. properties: email: description: Email address. examples: - review@example.com type: string name: description: Display name. examples: - Review Bot type: string required: - name - email type: object NotesWriteResult: additionalProperties: false description: >- Result of a notes write: whether it succeeded, a status, and an optional message. properties: message: description: Optional human-readable message. type: string status: description: Status code (e.g. ok). examples: - ok type: string success: description: Whether the operation succeeded. examples: - true type: boolean required: - success - status type: object InvalidParam: additionalProperties: false description: One invalid field of the request body. properties: name: description: Dotted wire path of the field. examples: - deployment.production_branch type: string reason: description: The rule that the value breaks. examples: - exceeds 255 characters type: string required: - name - reason type: object RefGuardProblemDetails: allOf: - $ref: '#/components/schemas/ProblemDetails' - properties: current_sha: description: >- The commit of the guarded ref when the server checked the guard, or 40 zeros when the ref does not exist. Send it as the guard of the next attempt. A commit write to a new branch with `base_branch` compares the guard with the tip of `base_branch`, so `current_sha` is that tip. examples: - c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 type: string guard: description: >- The request field of the guard that failed. A request that sends a deprecated alias of the field gets the standard name. enum: - expected_target_sha - expected_source_sha - expected_notes_ref_sha type: string required: - guard - current_sha type: object description: >- Problem details of a failed ref guard, with the code `ref_guard_failed`. `guard` names the request field of the guard, and `current_sha` is the commit of the guarded ref. type: object securitySchemes: bearerAuth: bearerFormat: JWT description: >- 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. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.