components: schemas: ArchiveOptions: additionalProperties: false description: Output settings for an archive, such as a prefix for every file path. properties: prefix: description: Prefix to add to every file path inside the archive. type: string type: object BaseRepo: additionalProperties: false description: Code Storage repository that a new repository copies once. The deprecated form, with provider and operation, also describes a sync or a fork. properties: auth: $ref: "#/components/schemas/BaseRepoAuth" description: Authentication for the source repository. A copy requires auth.token. default_branch: deprecated: true description: "Deprecated: use the top-level default_branch for a copy or a sync." type: string name: description: Name of the Code Storage repository to copy. In the deprecated form, the repository name on the provider. examples: - templates/starter type: string operation: default: sync deprecated: true description: "Deprecated: base_repo without provider is a copy, and upstream is a sync. In the deprecated form, sync (the default) or fork." enum: - sync - fork type: string owner: deprecated: true description: "Deprecated: omit it for a copy, and use upstream.owner for a sync." type: string provider: deprecated: true description: "Deprecated: omit it for a copy, and use upstream for a sync. In the deprecated form, the provider of the source." enum: - github - gitlab - bitbucket - gitea - forgejo - codeberg - sr.ht - sourcehut - code.storage type: string ref: description: Branch, tag, or commit SHA to copy. It defaults to the HEAD of the source repository. examples: - main type: string sha: deprecated: true description: "Deprecated: use ref, which accepts a commit SHA." type: string upstream_host: deprecated: true description: "Deprecated: use upstream.host." type: string required: - name type: object BaseRepoAuth: additionalProperties: false description: Authentication used to access the base repository for sync or fork operations. properties: auth_type: deprecated: true description: "Deprecated: use upstream.access for a public GitHub sync. A copy needs no auth_type." enum: - public - jwt type: string token: description: JWT with git:read on the source repository. A copy requires it. type: string type: object BlameLine: additionalProperties: false description: Single blame entry describing the commit and author responsible for a line. properties: author_email: description: Author email of the commit that last touched this line. examples: - jane@example.com type: string author_name: description: Author of the commit that last touched this line. examples: - Jane Doe type: string author_time: description: Author timestamp in RFC 3339 format. examples: - "2024-01-15T14:32:18Z" type: string commit_sha: description: Commit SHA that last touched this line. examples: - b003fc78805954584e1ee364a4ad39d7c79e819a type: string committer_email: description: Committer email of the commit that last touched this line. examples: - jane@example.com type: string committer_name: description: Committer of the commit that last touched this line. examples: - Jane Doe type: string committer_time: description: Committer timestamp in RFC 3339 format. examples: - "2024-01-15T14:32:18Z" type: string line_number: description: Line number in the current file. examples: - 42 format: int32 type: integer original_line_number: description: Line number in the original file before any renames or moves. examples: - 40 format: int32 type: integer original_path: description: Original repository-relative path the line was introduced at. examples: - src/main.go type: string previous_commit_sha: description: Commit SHA prior to the current commit when known. examples: - a4d39d7c79e819ab003fc78805954584e1ee36 type: string summary: description: First line of the commit message. examples: - "fix: resolve scrolling issue in dashboard" type: string required: - line_number - commit_sha - original_line_number - original_path - author_name - author_email - author_time - committer_name - committer_email - committer_time - summary type: object BlobChunk: additionalProperties: false description: Part of the content of one file in a create-commit NDJSON body. Send the chunks of a file in order, and set `eof` on the last one. properties: content_id: description: Ties the chunk to a file operation. type: string data: description: Base64-encoded payload (decoded payload must be at most 4 MiB per chunk). type: string eof: description: Set true on the final chunk for that content_id. type: boolean required: - content_id - data - eof type: object Branch: description: A branch. properties: created_at: description: ISO 8601 creation timestamp. examples: - "2024-01-15T10:30:00Z" type: string head_sha: description: HEAD commit SHA for the branch. examples: - a1b2c3d4e5f6 type: string name: description: Branch name. examples: - main type: string required: - name - head_sha - created_at type: object BranchListItem: allOf: - $ref: "#/components/schemas/Branch" - properties: cursor: description: Opaque pagination token for this branch entry. examples: - b_123abc type: string required: - cursor type: object description: A branch in a list, with its pagination cursor. type: object Commit: additionalProperties: false description: Commit metadata. For a signed commit, repos.commits.get also returns the armored signature and the signed payload. properties: author_email: description: Commit author email. examples: - jane@example.com type: string author_name: description: Commit author name. examples: - Jane Doe type: string committer_date: description: Commit committer timestamp in RFC 3339 format. A rebase or cherry-pick sets it to a later time than the author timestamp. examples: - "2024-01-16T09:05:41Z" type: string committer_email: description: Commit committer email. examples: - jane@example.com type: string committer_name: description: Commit committer name. examples: - Jane Doe type: string date: description: Commit author timestamp in RFC 3339 format. examples: - "2024-01-15T14:32:18Z" type: string message: description: "The commit message. In repos.commits.get responses, the full message. In repos.commits.list responses, only the subject line: the first paragraph of the message as one line, without the body and the trailers." examples: - "fix: resolve scrolling issue in dashboard" type: string parent_shas: description: Parent commit SHAs in Git parent order. Empty for root commits. examples: - - f4f9df3b8db66c73f6bf67e8f8f4f14f6522731e items: type: string type: array payload: description: "The signed payload: the raw commit object with the gpgsig header removed. This is the exact data the signature is computed over. Present in repos.commits.get responses when the commit is signed." type: string sha: description: The commit SHA. examples: - b003fc78805954584e1ee364a4ad39d7c79e819a type: string signature: description: Armored signature from the commit's gpgsig header (OpenPGP or SSH). Present in repos.commits.get responses when the commit is signed. examples: - | -----BEGIN PGP SIGNATURE----- ... -----END PGP SIGNATURE----- type: string required: - sha - parent_shas - message - author_name - author_email - committer_name - committer_email - date type: object CommitWriteRefGuardProblemDetails: allOf: - $ref: "#/components/schemas/RefGuardProblemDetails" - properties: result: $ref: "#/components/schemas/RefUpdateResult" description: Final branch update outcome. required: - result type: object description: Problem details of a commit write whose `expected_target_sha` guard failed. The body keeps `result`, and `commit` is null. type: object CommitWriteResponse: additionalProperties: false description: Result of applying an NDJSON commit pack, including the resulting commit and branch update. properties: commit: $ref: "#/components/schemas/WrittenCommit" description: Commit object information generated by the storage service. result: $ref: "#/components/schemas/RefUpdateResult" description: Final branch update outcome. required: - commit - result type: object DiffChunk: additionalProperties: false description: Part of the Git patch in a create-commit-from-diff NDJSON body. Send the chunks in order, and set `eof` on the last one. properties: data: description: Base64-encoded diff bytes. Decoded payloads must be at most 4 MiB. Combined diff must be compatible with git apply --cached --binary. type: string eof: description: Set true on the final chunk to signal end-of-stream. type: boolean required: - data - eof type: object DiffStats: additionalProperties: false description: Aggregate diff statistics across all files. properties: additions: description: Total added lines across the diff. examples: - 50 format: int64 type: integer changes: description: Total line changes (additions plus deletions). examples: - 60 format: int64 type: integer deletions: description: Total deleted lines across the diff. examples: - 10 format: int64 type: integer files: description: Number of files changed. examples: - 3 format: int64 type: integer required: - files - additions - deletions - changes type: object FileDiff: additionalProperties: false description: Per-file diff entry including the raw unified diff text. properties: additions: description: Added lines in this file. format: int64 type: integer bytes: description: File size in bytes. examples: - 2048 format: int64 type: integer deletions: description: Deleted lines in this file. format: int64 type: integer is_eof: description: Whether the file ends with a newline. examples: - true type: boolean old_path: description: Previous file path for renamed files. type: string path: description: Repository-relative file path (new location for renames). examples: - src/main.go type: string raw: description: Raw unified diff content. examples: - |- diff --git a/src/main.go b/src/main.go ... type: string state: description: "Git status code: A (added), M (modified), D (deleted), R (renamed), C (copied), or T (type changed)." examples: - M type: string required: - path - state - raw - bytes - is_eof - additions - deletions type: object FileEntry: additionalProperties: false description: Tree entry in a list-files response, including the repository-rooted path, six-digit Git mode, and derived type. properties: mode: description: Six-digit Git mode for the entry. examples: - "100644" type: string path: description: Repository-rooted path. examples: - src/main.go type: string type: description: "Entry type: blob, tree, symlink, or submodule." examples: - blob type: string required: - path - type - mode type: object FileLastCommit: additionalProperties: false description: Commit metadata shared by one or more files in a list-files-with-metadata response. properties: author: description: Author display name for the commit. examples: - Jon Crosby type: string date: description: RFC 3339 author date for the commit. examples: - "2026-02-18T10:30:00Z" type: string message: description: "The subject line of the commit message: the first paragraph of the message as one line, without the body and the trailers. repos.commits.get returns the full message." examples: - add list files with metadata endpoint type: string order: description: "History-order rank relative to the resolved ref: 0 is the commit closest to the ref tip (newest in history), larger values are older. Derived from a topological walk rather than author dates, so callers can rank a folder's latest change by the smallest order among its files." examples: - 0 format: int32 type: integer required: - author - date - message - order type: object FileOperation: additionalProperties: false description: A file that a commit adds, replaces, or deletes. properties: content_id: description: Identifier that blob chunks reference for this file. Required for upsert. type: string mode: description: File mode such as 100644 or 100755. Defaults to 100644. type: string operation: description: upsert (default) to add or replace content, or delete to remove a file. type: string path: description: Repository-relative path, with no leading slash. type: string required: - path type: object FileWithMetadata: additionalProperties: false description: File entry in a list-files-with-metadata response, including mode, type, and the SHA of the most recent commit that touched it. properties: last_commit_sha: description: Commit SHA of the most recent commit that touched this file. examples: - a1b2c3d4e5f6 type: string mode: description: File mode as stored in Git, for example 100644. examples: - "100644" type: string path: description: Repository-relative file path. examples: - README.md type: string size: description: File size in bytes. examples: - 2048 format: int64 type: integer type: description: "Derived file type: blob, tree, symlink, or submodule." examples: - blob type: string required: - path - mode - type - size - last_commit_sha type: object FilteredFile: additionalProperties: false description: Per-file diff entry that was excluded from inline diff output because of size or file-type rules. properties: bytes: description: File size in bytes. examples: - 50000 format: int64 type: integer is_eof: description: Whether the file ends with a newline. examples: - true type: boolean old_path: description: Previous file path for renamed files. type: string path: description: Repository-relative file path (new location for renames). Excluded from inline diff content because of size or file-type rules. examples: - package-lock.json type: string state: description: "Git status code: A (added), M (modified), D (deleted), R (renamed), C (copied), or T (type changed)." examples: - M type: string required: - path - state - bytes - is_eof type: object GetBranchDiffResponse: additionalProperties: false description: Diff between a branch and its base, including merge base, aggregate stats, and per-file changes. properties: base: description: The base branch or ref used for comparison. examples: - main type: string branch: description: The branch name being diffed. examples: - feature/new-feature type: string files: description: Files returned with inline diff content. items: $ref: "#/components/schemas/FileDiff" type: array filtered_files: description: Files filtered out of inline diff output because of size or file-type rules. items: $ref: "#/components/schemas/FilteredFile" type: array merge_base_sha: description: Merge base SHA used for the three-dot branch diff. examples: - a2d127e6a4d54bb7390de828a99e36411f0c84df type: string stats: $ref: "#/components/schemas/DiffStats" description: Aggregate diff statistics. required: - branch - base - merge_base_sha - stats - files - filtered_files type: object GitCredential: additionalProperties: false description: Stored Git credential summary returned after a credential is created or updated. properties: created_at: description: Credential creation timestamp in ISO 8601 format. examples: - "2026-03-12T15:04:05Z" type: string id: description: Credential ID returned when the credential is created. examples: - ggc_1234567890abcdef type: string required: - id 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 GitPushEvent: additionalProperties: false description: A Git ref update. The type field and the X-Pierre-Event header identify this payload as push. properties: after: description: The new commit SHA. All zeros for a deleted ref. type: string before: description: The previous commit SHA. All zeros for a newly created ref. type: string customer_id: deprecated: true description: "Deprecated: use org. The internal ID of the customer that owns the repository." type: string org: description: The organization name. It is the iss claim of the JWTs that the organization signs. It can be absent on older deliveries. type: string pushed_at: description: When the push occurred, as an RFC 3339 timestamp. format: date-time type: string ref: description: The full Git ref name, for example refs/heads/main. type: string repository: $ref: "#/components/schemas/WebhookRepository" description: The repository that produced the event. type: description: The event type. It matches the X-Pierre-Event header. It can be absent on older deliveries. enum: - push type: string required: - repository - ref - before - after - customer_id - pushed_at type: object GitSyncFailedEvent: additionalProperties: false description: Sent when a repository sync run fails, including failures after retries are exhausted and infrastructure failures. Internal cancellations do not produce this event. run_count includes the run that just finished. properties: completed_at: description: When the sync run finished, as an RFC 3339 timestamp. format: date-time type: string error: description: The failure message. type: string is_first_sync: description: Whether the repository had never synced successfully before this run began. type: boolean lifecycle_id: description: The sync lifecycle ID. It can be absent on older deliveries. type: string org: description: The organization name. It is the iss claim of the JWTs that the organization signs. It can be absent on older deliveries. type: string repository: $ref: "#/components/schemas/WebhookRepository" description: The repository that produced the event. run_count: description: Completed sync runs. For started events, this excludes the current run. For succeeded and failed events, it includes the current run. format: int64 type: integer started_at: description: When the sync run began, as an RFC 3339 timestamp. format: date-time type: string type: description: The event type. It matches the X-Pierre-Event header. enum: - repo.sync.failed type: string required: - type - repository - run_count - is_first_sync - started_at - completed_at - error type: object GitSyncStartedEvent: additionalProperties: false description: Sent when a repository sync run begins, before the upstream fetch starts. run_count counts previously completed runs. properties: is_first_sync: description: Whether the repository had never synced successfully before this run began. type: boolean lifecycle_id: description: The sync lifecycle ID. It can be absent on older deliveries. type: string org: description: The organization name. It is the iss claim of the JWTs that the organization signs. It can be absent on older deliveries. type: string repository: $ref: "#/components/schemas/WebhookRepository" description: The repository that produced the event. run_count: description: Completed sync runs. For started events, this excludes the current run. For succeeded and failed events, it includes the current run. format: int64 type: integer started_at: description: When the sync run began, as an RFC 3339 timestamp. format: date-time type: string type: description: The event type. It matches the X-Pierre-Event header. enum: - repo.sync.started type: string required: - type - repository - run_count - is_first_sync - started_at type: object GitSyncSucceededEvent: additionalProperties: false description: Sent when a repository sync run completes successfully. run_count includes the run that just finished. properties: completed_at: description: When the sync run finished, as an RFC 3339 timestamp. format: date-time type: string is_first_sync: description: Whether the repository had never synced successfully before this run began. type: boolean lifecycle_id: description: The sync lifecycle ID. It can be absent on older deliveries. type: string org: description: The organization name. It is the iss claim of the JWTs that the organization signs. It can be absent on older deliveries. type: string repository: $ref: "#/components/schemas/WebhookRepository" description: The repository that produced the event. run_count: description: Completed sync runs. For started events, this excludes the current run. For succeeded and failed events, it includes the current run. format: int64 type: integer started_at: description: When the sync run began, as an RFC 3339 timestamp. format: date-time type: string type: description: The event type. It matches the X-Pierre-Event header. enum: - repo.sync.succeeded type: string required: - type - repository - run_count - is_first_sync - started_at - completed_at type: object GrepContext: additionalProperties: false description: Number of context lines to return before and after each match. properties: after: description: Number of lines to include after each match. examples: - 1 format: int32 type: integer before: description: Number of lines to include before each match. examples: - 0 format: int32 type: integer type: object GrepFileFilters: additionalProperties: false description: Glob and extension filters that select the files to search. properties: exclude_globs: description: Glob patterns for files to exclude. items: description: Glob pattern such as `node_modules/**`. type: string type: array extension_filters: description: File extensions to filter by (e.g. [".js", ".py"]). items: description: File extension to match, including the leading dot (e.g. `.js`). type: string type: array include_globs: description: Glob patterns for files to include. items: description: Glob pattern such as `src/**/*.go`. type: string type: array type: object GrepFileMatch: additionalProperties: false description: Matches grouped under a single file path. properties: lines: description: Lines returned for the match, including optional context lines. items: $ref: "#/components/schemas/GrepLine" type: array path: description: Repository-relative file path that matched. examples: - app/blog/markdown/ephemeral-branches.md type: string required: - path - lines type: object GrepLimits: additionalProperties: false description: Limits on the total lines and on the matches for each file in a grep response. properties: max_lines: description: Maximum total lines to return (default 2000, max 2000). format: int32 type: integer max_matches_per_file: description: Maximum matches returned per file (default 200). format: int32 type: integer type: object GrepLine: additionalProperties: false description: Single line returned by grep, either a match or a surrounding context line. properties: line_number: description: Line number in the file. format: int32 type: integer text: description: Line text content. type: string type: description: match for lines satisfying the pattern, or context for surrounding context lines. type: string required: - line_number - text - type type: object GrepPagination: additionalProperties: false description: Cursor and page size for grep matches. properties: cursor: description: Pagination cursor returned by a previous grep response. type: string limit: description: Maximum number of matches to return (default 200). examples: - 50 format: int32 type: integer type: object GrepQuery: additionalProperties: false description: Pattern to search for, and whether the search is case-sensitive. properties: case_sensitive: default: true description: Defaults to true when omitted. examples: - true type: boolean pattern: description: Regular expression or literal pattern to search for. examples: - ephemeral branches type: string required: - pattern type: object GrepResolvedQuery: additionalProperties: false description: Query settings that the server used for the search. properties: case_sensitive: description: Echoed case-sensitivity setting. examples: - true type: boolean pattern: description: Echoed pattern that was searched. examples: - ephemeral branches type: string required: - pattern - case_sensitive type: object GrepResolvedRef: additionalProperties: false description: Ref and resolved commit that the search ran against. properties: commit: description: Resolved commit SHA the grep ran against. examples: - b003fc78805954584e1ee364a4ad39d7c79e819a type: string ref: description: Ref that was grepped. examples: - main type: string required: - ref - commit 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 MergeConflict: additionalProperties: false description: Merge failure caused by a conflict, a moved target branch, or a repository change, with the conflicting paths when known. properties: conflict_paths: description: Repository paths that conflicted during the merge. items: type: string type: array conflict_type: description: "Machine-readable conflict type: merge_conflict, target_moved, or repo_changed." examples: - merge_conflict type: string error: description: High-level conflict result. examples: - merge conflict type: string merge_base_sha: description: Merge base SHA used when the conflict was calculated. type: string required: - error type: object MergeSourceState: additionalProperties: false description: Resolved source ref state for a merge response. properties: branch: deprecated: true description: "Deprecated: use ref. Source branch name." examples: - feature/preview type: string ephemeral: description: Whether the source ref was resolved under the ephemeral namespace. examples: - true type: boolean ref: description: The source ref the merge reads. examples: - feature/preview type: string sha: description: Resolved source SHA. examples: - 9eb378bdb5bf1944f6ba0bd5a2c4df3ce32f4df1 type: string required: - ref - branch - ephemeral - sha type: object MergeTargetState: additionalProperties: false description: Resolved target ref state for a merge response, including the previous and new tip SHAs. properties: branch: description: Target branch name. examples: - main type: string ephemeral: description: Whether the target ref was resolved under the ephemeral namespace. type: boolean new_sha: description: New target tip SHA after the merge. examples: - 41f0d5c6cc5f4d0fb4a3af2de27ccf9a80ab3b84 type: string old_sha: description: Previous target tip SHA before the merge. examples: - c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 type: string required: - branch - ephemeral - old_sha - new_sha type: object Meta: additionalProperties: false description: Cloud location and inbound IP addresses of the Code Storage cluster that serves the current organisation. properties: ips: $ref: "#/components/schemas/MetaIPs" description: Public IPv4 addresses, in CIDR notation, that accept inbound traffic for the organisation. Allow these in firewall rules that restrict outbound connections to Code Storage. provider: $ref: "#/components/schemas/MetaProvider" description: Cloud provider and region that host the organisation. required: - provider - ips type: object MetaIPs: additionalProperties: false description: Inbound IPv4 address ranges of the cluster, grouped by the kind of traffic they accept. properties: api: description: Addresses that accept HTTP API traffic. Empty when no addresses are published for the organisation's cluster. examples: - - 192.0.2.0/24 items: type: string type: array git: description: Addresses that accept Git over HTTPS traffic. Empty when no addresses are published for the organisation's cluster. examples: - - 192.0.2.0/24 items: type: string type: array required: - git - api type: object MetaProvider: additionalProperties: false description: Cloud provider and region of the cluster that serves the current organisation. properties: name: description: Cloud provider that hosts the organisation, such as aws or gcp. Empty when the gateway cannot determine its location. examples: - aws type: string region: description: Cloud provider region that hosts the organisation. Empty when the gateway cannot determine its location. examples: - us-east-2 type: string required: - name - region type: object NotesRef: additionalProperties: false description: Git notes ref entry including its full ref name and current tip SHA. properties: cursor: description: Opaque pagination token for this notes ref entry. examples: - refs/notes/reviews/session-a type: string ref: description: Full notes ref name. examples: - refs/notes/reviews/session-a type: string sha: description: Current tip SHA stored in the notes ref. examples: - a1b2c3d4e5f6 type: string required: - cursor - ref - sha 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 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 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 PreviewMergeBlob: additionalProperties: false description: Single Git blob rendered as part of a merge conflict preview. properties: binary: description: Whether the blob appears to be binary content. examples: - false type: boolean content: description: UTF-8 text content when available and not binary. type: string oid: description: Git object ID for this blob. examples: - "1111111111111111111111111111111111111111" type: string truncated: description: Whether content was truncated by server-side limits. examples: - false type: boolean required: - truncated - binary type: object PreviewMergeConflict: additionalProperties: false description: Inline conflict content for a single conflicted repository path. properties: base: $ref: "#/components/schemas/PreviewMergeBlob" description: Base stage blob. ours: $ref: "#/components/schemas/PreviewMergeBlob" description: Target branch stage blob. path: description: Repository path for this conflict. examples: - docs/conflict.txt type: string result: $ref: "#/components/schemas/PreviewMergeBlob" description: Best-effort merged blob content, usually with conflict markers for text conflicts. theirs: $ref: "#/components/schemas/PreviewMergeBlob" description: Source branch stage blob. required: - path - result - base - ours - theirs type: object PreviewMergeFilteredConflict: additionalProperties: false description: Conflict omitted from inline content because of request or server limits. properties: path: description: Repository path omitted from inline conflict content. examples: - src/app.ts type: string reason: description: Reason the conflict content was omitted. examples: - max_conflict_files_exceeded type: string required: - path - reason 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 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 RefUpdateResult: additionalProperties: false description: Branch update outcome for an operation that writes a commit. properties: branch: deprecated: true description: "Deprecated: use target_branch. The branch the operation updates." type: string message: description: Optional human-readable message. type: string new_sha: description: New tip SHA after the update. type: string old_sha: description: Previous tip SHA (40-char hex; all zeros when the branch did not previously exist). type: string status: description: Status code (ok, conflict, precondition_failed, etc.). enum: - ok - failed - precondition_failed - conflict - not_found - unauthorized - forbidden - timeout - invalid - payload_too_large - unavailable - internal type: string success: description: Whether the operation succeeded. type: boolean target_branch: description: The branch the operation updates. type: string required: - target_branch - branch - old_sha - new_sha - success - status type: object ReposArchiveGetRequest: additionalProperties: false description: Archive options describing the ref to snapshot and the include or exclude filters applied to the resulting tarball. properties: archive: $ref: "#/components/schemas/ArchiveOptions" description: Optional archive output settings. exclude_globs: description: Exclude files matching these glob patterns after include filtering. items: description: Glob pattern such as `node_modules/**`. type: string type: array include_globs: description: Only include files matching these glob patterns. items: description: Glob pattern such as `src/**/*.go`. type: string type: array max_blob_size: description: Maximum blob size to include in the archive, in bytes. format: int64 type: integer ref: description: Branch, tag, or commit to archive. When omitted, the default branch or HEAD is used. type: string type: object ReposBlameGetResponse: additionalProperties: false description: Per-line blame information for the requested file at the resolved revision. properties: commit_sha: description: Commit SHA the blame was computed at. examples: - b003fc78805954584e1ee364a4ad39d7c79e819a type: string lines: description: Per-line blame results in file order. items: $ref: "#/components/schemas/BlameLine" type: array path: description: Repository-relative file path that was blamed. examples: - src/main.go type: string ref: description: Resolved ref used for the blame. examples: - main type: string required: - ref - path - commit_sha - lines type: object ReposBranchesCreateRequest: additionalProperties: false description: Create-branch request body describing the new branch and its base ref. properties: base_branch: deprecated: true description: "Deprecated: use base_ref. Preferred source branch name." type: string base_is_ephemeral: description: Whether the base branch should be resolved from the ephemeral namespace. examples: - false type: boolean base_ref: description: Optional source ref or revision. Provide base_ref or the deprecated base_branch. examples: - main type: string force: description: Allow non-fast-forward updates when recreating an existing named branch. Requires target_branch. type: boolean preferred_base: description: Optional pack hint. A branch name the backend prefers as the delta base when it builds the thin pack. It does not change the source or the result. type: string target_branch: description: Optional destination branch name. Omit it to let the server allocate a name. examples: - feature/new-onboarding type: string target_is_ephemeral: description: Whether the new branch should be created in the ephemeral namespace. examples: - false type: boolean type: object ReposBranchesCreateResponse: additionalProperties: false description: Result of creating a branch, including the resulting ref state. properties: commit_sha: description: Resolved commit SHA at the new branch tip. examples: - abc123def4567890abc123def4567890abc123de type: string message: description: Human-readable result message. examples: - branch created type: string target_branch: description: Destination branch name. examples: - feature/new-onboarding type: string target_is_ephemeral: description: Whether the created branch is ephemeral. examples: - false type: boolean required: - message - target_branch - target_is_ephemeral type: object ReposBranchesDeleteRequest: additionalProperties: false description: Deprecated branch deletion body. Use the target_branch and ephemeral query parameters. properties: ephemeral: deprecated: true description: "Deprecated: use the ephemeral query parameter. Delete the branch from the ephemeral namespace instead of the default namespace." examples: - false type: boolean name: deprecated: true description: "Deprecated: use the target_branch query parameter. Branch name to delete." examples: - feature/old-onboarding type: string target_branch: deprecated: true description: "Deprecated: use the target_branch query parameter. Branch name to delete. Must not start with refs/." examples: - feature/old-onboarding type: string type: object ReposBranchesDeleteResponse: additionalProperties: false description: Result of deleting a branch. properties: ephemeral: description: Whether the deleted branch lived in the ephemeral namespace. examples: - false type: boolean message: description: Human-readable result message. examples: - branch deleted type: string name: deprecated: true description: "Deprecated: use target_branch. Deleted branch name." examples: - feature/old-onboarding type: string target_branch: description: Deleted branch name. examples: - feature/old-onboarding type: string required: - target_branch - name - ephemeral - message type: object ReposBranchesGetResponse: additionalProperties: false description: One branch that matches an exact short name. properties: branch: $ref: "#/components/schemas/Branch" description: The branch that has the requested name. required: - branch type: object ReposBranchesListResponse: additionalProperties: false description: Paginated list of branches for the repository. properties: branches: description: List of branch objects. items: $ref: "#/components/schemas/BranchListItem" type: array has_more: description: Whether another page is available. examples: - true type: boolean next_cursor: description: Opaque cursor for the next page. Pass it as `cursor` to read the next page. Absent when there are no more results. examples: - MTcwNzU3MzQ1MTAwMDAwMDAwMHxyZXBvXzlhNGMyMWY type: string required: - branches - has_more type: object ReposCommitsCreateFromDiffRequest: additionalProperties: false description: "Metadata line of a create-commit-from-diff NDJSON body: the target branch and the commit message and identities. The `diff_chunk` lines that follow carry the patch." properties: author: $ref: "#/components/schemas/GitIdentity" description: Author identity for the commit. base_branch: description: Source branch to seed from when target_branch does not exist yet. type: string base_is_ephemeral: description: When true, interpret base_branch as ephemeral. type: boolean commit_message: description: Commit message for the new commit. type: string committer: $ref: "#/components/schemas/GitIdentity" description: Committer identity. Defaults to author when omitted. ephemeral: deprecated: true description: "Deprecated: use target_is_ephemeral. When true, write the target branch under the ephemeral namespace." type: boolean ephemeral_base: deprecated: true description: "Deprecated: use base_is_ephemeral. When true, interpret base_branch as ephemeral." type: boolean expected_head_sha: deprecated: true description: "Deprecated: use expected_target_sha. Guard ensuring the branch tip matches before applying the patch." type: string expected_target_sha: description: Guard ensuring the target branch tip matches before applying the patch. type: string target_branch: description: Destination branch name. type: string target_is_ephemeral: description: When true, write the target branch under the ephemeral namespace. type: boolean required: - target_branch - commit_message - author type: object ReposCommitsCreateRequest: additionalProperties: false description: "Metadata line of a create-commit NDJSON body: the target branch, the commit message and identities, and the file operations. The `blob_chunk` lines that follow carry the file content." properties: author: $ref: "#/components/schemas/GitIdentity" description: Author identity for the commit. base_branch: description: Source branch to copy when target_branch does not yet exist. type: string base_is_ephemeral: description: When true, interpret base_branch as ephemeral. type: boolean commit_message: description: Commit message for the new commit. type: string committer: $ref: "#/components/schemas/GitIdentity" description: Committer identity. Defaults to author when omitted. ephemeral: deprecated: true description: "Deprecated: use target_is_ephemeral. When true, write the target branch under the ephemeral namespace." type: boolean ephemeral_base: deprecated: true description: "Deprecated: use base_is_ephemeral. When true, interpret base_branch as ephemeral." type: boolean expected_head_sha: deprecated: true description: "Deprecated: use expected_target_sha. Commit SHA that must match the branch tip before writing." type: string expected_target_sha: description: Commit SHA that must match the target branch tip before writing. Omit to fast-forward unconditionally. type: string files: description: File operations applied in this commit. items: $ref: "#/components/schemas/FileOperation" type: array target_branch: description: Destination branch name (no refs/ prefix). type: string target_is_ephemeral: description: When true, write the target branch under the ephemeral namespace. type: boolean required: - target_branch - commit_message - author - files type: object ReposCommitsGetResponse: additionalProperties: false description: Commit metadata for a single resolved revision, without diff content. properties: commit: $ref: "#/components/schemas/Commit" description: Resolved commit metadata. required: - commit type: object ReposCommitsListResponse: additionalProperties: false description: Paginated commit history for the repository, optionally filtered by branch. properties: commits: description: List of commit objects. items: $ref: "#/components/schemas/Commit" type: array has_more: description: Whether another page is available. examples: - true type: boolean next_cursor: description: Opaque cursor for the next page. Pass it as `cursor` to read the next page. Absent when there are no more results. examples: - MTcwNzU3MzQ1MTAwMDAwMDAwMHxyZXBvXzlhNGMyMWY type: string required: - commits - has_more type: object ReposCommitsRestoreRequest: additionalProperties: false description: "Metadata line of a restore-commit NDJSON body: the branch to reset, the revision to reset it to, and the commit identities. The body has no other line." properties: author: $ref: "#/components/schemas/GitIdentity" description: Author identity for the restore commit. base_ref: description: Branch, tag, or commit to reset the branch to. Provide base_ref or the deprecated target_commit_sha. type: string commit_message: description: Commit message for the restore commit. Defaults to a message that names the branch and the commit. type: string committer: $ref: "#/components/schemas/GitIdentity" description: Committer identity. Defaults to author when omitted. expected_head_sha: deprecated: true description: "Deprecated: use expected_target_sha. Guard ensuring the current tip matches before applying the restore." type: string expected_target_sha: description: Guard ensuring the target branch tip matches before applying the restore. type: string target_branch: description: Branch name to reset (no refs/ prefix). type: string target_commit_sha: deprecated: true description: "Deprecated: use base_ref. Commit to reset the branch to." type: string required: - target_branch - author type: object ReposCommitsRestoreResponse: additionalProperties: false description: Result of a restore commit operation, including the created commit and the branch update. properties: commit: $ref: "#/components/schemas/RestoredCommit" description: Created restore commit metadata. result: $ref: "#/components/schemas/RefUpdateResult" description: Branch update result. required: - commit - result type: object ReposCreateRequest: additionalProperties: false description: Create-repository request body. It supplies the optional repository name, default branch, and Git Sync or fork configuration. properties: base_repo: $ref: "#/components/schemas/BaseRepo" description: Code Storage repository to copy once. The new repository keeps no link to it. Do not set it together with upstream. default_branch: description: Default branch for the new repository. When omitted, a copy takes the default branch of the source, a sync from GitHub takes the default branch of the GitHub repository, and any other repository uses main. An empty repository has no branch until its first commit, and a commit to this name creates the default branch. examples: - main type: string repo_name: description: Name of the new repository. It can contain a slash. examples: - pierre/sdk-documentation type: string upstream: $ref: "#/components/schemas/UpstreamConfig" description: External Git host to keep syncing from. The link lasts, and the repository can sync again. Do not set it together with base_repo. type: object ReposCreateResponse: additionalProperties: false description: Result of creating a repository, including its repository name. properties: http_url: deprecated: true description: "Deprecated: use repo_name. Repository name or path, not a full URL." examples: - pierre/sdk-documentation type: string message: description: "Human-readable result: the repository was created, or it already exists. The status gives the same result: 201 or 200." examples: - Repository 'pierre/sdk-documentation' created type: string repo_id: deprecated: true description: "Deprecated: use repo_name. Stable repository identifier." examples: - repo_7f2b3d9 type: string repo_name: description: Repository name or path. It can contain a slash. It matches the JWT repo claim. examples: - pierre/sdk-documentation type: string required: - repo_id - repo_name - http_url - message type: object ReposDeleteResponse: additionalProperties: false description: Confirmation that the repository deletion has been accepted. properties: message: description: Human-readable deletion status message. examples: - Repository pierre/sdk-documentation deletion initiated. Physical storage cleanup will complete asynchronously. type: string repo_id: deprecated: true description: "Deprecated: use repo_name. Stable repository identifier." examples: - repo_7f2b3d9 type: string repo_name: description: Repository name or path. It can contain a slash. It matches the JWT repo claim. examples: - pierre/sdk-documentation type: string required: - repo_name - repo_id - message type: object ReposDiffGetResponse: additionalProperties: false description: Diff for a single commit, including merge base when applicable, aggregate stats, and per-file changes. properties: base_sha: description: The commit that the base revision (base_ref) resolved to. Empty for a single-commit diff. Use it to record the exact base of the comparison. examples: - a2d127e6a4d54bb7390de828a99e36411f0c84df type: string files: description: Files returned with inline diff content. items: $ref: "#/components/schemas/FileDiff" type: array filtered_files: description: Files filtered out of inline diff output because of size or file-type rules. items: $ref: "#/components/schemas/FilteredFile" type: array merge_base_sha: description: "The merge base of base_ref and ref: the commit where the diff starts. Empty for a single-commit diff." examples: - a2d127e6a4d54bb7390de828a99e36411f0c84df type: string sha: description: The commit SHA to diff. examples: - b003fc78805954584e1ee364a4ad39d7c79e819a type: string stats: $ref: "#/components/schemas/DiffStats" description: Aggregate diff statistics. required: - sha - stats - files - filtered_files type: object ReposFilesListResponse: additionalProperties: false description: Paginated tree entries in the repository at the resolved revision. properties: entries: description: Tree entries for the resolved revision. items: $ref: "#/components/schemas/FileEntry" type: array has_more: description: Whether another page is available. examples: - true type: boolean next_cursor: description: Opaque cursor for the next page. Pass it as `cursor` to read the next page. Absent when there are no more results. examples: - MTcwNzU3MzQ1MTAwMDAwMDAwMHxyZXBvXzlhNGMyMWY type: string paths: description: Flat blob-only path list. Mirrors the path of every entry whose type is "blob". Convenience shape for callers that just want file paths; use entries when you need type/mode. examples: - - README.md items: description: Repository-relative path used to scope the operation. type: string type: array ref: description: The resolved reference (branch name or commit SHA) that was used. examples: - main type: string required: - entries - paths - ref - has_more type: object ReposFilesMetadataListResponse: additionalProperties: false description: Files in the repository at the resolved revision, each annotated with mode, type, and the latest commit that changed it. properties: commits: additionalProperties: $ref: "#/components/schemas/FileLastCommit" description: Commit metadata keyed by last_commit_sha so repeated commits are only sent once. type: object files: description: Files in the resolved revision, each annotated with the latest commit that changed it. items: $ref: "#/components/schemas/FileWithMetadata" type: array has_more: description: Whether another page is available. examples: - true type: boolean next_cursor: description: Opaque cursor for the next page. Pass it as `cursor` to read the next page. Absent when there are no more results. examples: - MTcwNzU3MzQ1MTAwMDAwMDAwMHxyZXBvXzlhNGMyMWY type: string ref: description: The resolved ref or commit used to generate the listing. examples: - main type: string required: - files - commits - ref - has_more type: object ReposGitCredentialsCreateRequest: additionalProperties: false description: Request body for storing a new HTTPS Git credential when the repository is identified via the URL path. properties: password: description: Password or access token for the upstream provider. examples: - glpat_xxxxxxxxxxxx type: string username: description: "Username for HTTPS authentication. Optional. With no username, requests to the upstream send the token as the password with the username `x-token-auth` for Bitbucket and `oauth2` for GitLab, and as the username for Gitea, Forgejo, and Codeberg. sr.ht takes no credential over HTTPS: it serves private repositories and pushes only over SSH." examples: - oauth2 type: string required: - password type: object ReposGitCredentialsCreateRequestLegacy: additionalProperties: false description: Request body for storing a new HTTPS Git credential against a repository configured for a generic Git provider. properties: password: description: Password or access token for the upstream provider. examples: - glpat_xxxxxxxxxxxx type: string repo_id: deprecated: true description: "Deprecated: use the repo_name path parameter instead. Stable repository identifier." examples: - repo_7f2b3d9 type: string username: description: "Username for HTTPS authentication. Optional. With no username, requests to the upstream send the token as the password with the username `x-token-auth` for Bitbucket and `oauth2` for GitLab, and as the username for Gitea, Forgejo, and Codeberg. sr.ht takes no credential over HTTPS: it serves private repositories and pushes only over SSH." examples: - oauth2 type: string required: - repo_id - password type: object ReposGitCredentialsDeleteRequestLegacy: additionalProperties: false description: Request body identifying the HTTPS Git credential to delete. properties: id: description: Credential ID to delete. examples: - ggc_1234567890abcdef type: string required: - id type: object ReposGitCredentialsUpdateRequest: additionalProperties: false description: Request body for rotating an existing HTTPS Git credential when the credential is identified via the URL path. properties: password: description: Updated password or access token for the upstream provider. examples: - glpat_rotated_token type: string username: description: "Username for HTTPS authentication. Optional. With no username, requests to the upstream send the token as the password with the username `x-token-auth` for Bitbucket and `oauth2` for GitLab, and as the username for Gitea, Forgejo, and Codeberg. sr.ht takes no credential over HTTPS: it serves private repositories and pushes only over SSH. An omitted username clears the stored one." examples: - oauth2 type: string required: - password type: object ReposGitCredentialsUpdateRequestLegacy: additionalProperties: false description: Request body for rotating an existing HTTPS Git credential by credential ID. properties: id: description: Credential ID returned at create time. examples: - ggc_1234567890abcdef type: string password: description: Updated password or access token for the upstream provider. examples: - glpat_rotated_token type: string username: description: "Username for HTTPS authentication. Optional. With no username, requests to the upstream send the token as the password with the username `x-token-auth` for Bitbucket and `oauth2` for GitLab, and as the username for Gitea, Forgejo, and Codeberg. sr.ht takes no credential over HTTPS: it serves private repositories and pushes only over SSH. An omitted username clears the stored one." examples: - oauth2 type: string required: - id - password type: object ReposGrepRequest: additionalProperties: false description: Grep request describing the pattern, ref, filters, limits, and pagination for a repository content search. properties: context: $ref: "#/components/schemas/GrepContext" description: Lines of context to include before and after each match. ephemeral: description: Whether ref should be resolved from the ephemeral namespace. type: boolean file_filters: $ref: "#/components/schemas/GrepFileFilters" description: Optional include and exclude filters applied before matching. limits: $ref: "#/components/schemas/GrepLimits" description: Maximum line and per-file match limits. pagination: $ref: "#/components/schemas/GrepPagination" description: Cursor-based pagination controls for large result sets. paths: description: Optional path prefixes used to narrow the search before pattern matching. items: description: Repository-relative path used to scope the operation. type: string type: array query: $ref: "#/components/schemas/GrepQuery" description: Pattern configuration. ref: description: Preferred branch, tag, or commit to search. examples: - main type: string rev: deprecated: true description: "Deprecated: use ref. Legacy ref field retained for backwards compatibility." type: string required: - query type: object ReposGrepResponse: additionalProperties: false description: Grep results grouped per file, including the resolved ref and pagination state. properties: has_more: description: Whether additional matches remain. examples: - true type: boolean incomplete_results: description: "True when the result set is incomplete because the server-side output cap was reached. Matches beyond the cap exist in the repo but cannot be retrieved by paging: narrow the query (pattern, paths, file filters) or raise max_lines if it was set below the maximum. next_cursor still pages through everything collected below the cap." examples: - false type: boolean matches: description: Files that matched the query, each with matching and context lines. items: $ref: "#/components/schemas/GrepFileMatch" type: array next_cursor: description: Opaque cursor for the next page, if any. type: - string - "null" query: $ref: "#/components/schemas/GrepResolvedQuery" description: The effective query settings used by the server. repo: $ref: "#/components/schemas/GrepResolvedRef" description: Resolved repository ref and commit used for the search. required: - query - repo - matches - next_cursor - has_more - incomplete_results type: object ReposListResponse: additionalProperties: false description: Paginated list of repositories for the current organisation. properties: has_more: description: Whether another page is available. examples: - true type: boolean next_cursor: description: Opaque cursor for the next page. Pass it as `cursor` to read the next page. Absent when there are no more results. examples: - MTcwNzU3MzQ1MTAwMDAwMDAwMHxyZXBvXzlhNGMyMWY type: string repos: description: Repositories in the current page. items: $ref: "#/components/schemas/Repository" type: array required: - repos - has_more type: object ReposMergeRequest: additionalProperties: false description: Merge request body specifying source and target branches, optional pinned source SHA, merge strategy, optional squash flag, and optional retry-on-target-move behavior, which is currently unsupported for GitHub-backed public targets. properties: allow_unrelated_histories: description: Permit merges between unrelated histories. type: boolean author: $ref: "#/components/schemas/GitIdentity" description: Author identity used when the backend creates a merge commit. Required for merge-commit strategies. commit_message: description: Commit message used when a merge commit is created. examples: - Merge feature/preview type: string committer: $ref: "#/components/schemas/GitIdentity" description: Committer identity for the merge commit. Defaults to author when omitted. expected_source_sha: description: Optional source commit guard. The merge uses this commit instead of the current tip of source_ref, and fails if source_ref does not contain it when the merge starts. A later advance of source_ref does not change the merged commit. examples: - 9eb378bdb5bf1944f6ba0bd5a2c4df3ce32f4df1 type: string expected_target_sha: description: Optional branch tip guard. The merge fails if the target has moved since this SHA. examples: - c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 type: string source_branch: deprecated: true description: "Deprecated: use source_ref. Source branch to merge from." examples: - feature/preview type: string source_is_ephemeral: description: Whether source_ref should be resolved from the ephemeral namespace. examples: - true type: boolean source_ref: description: Branch or refs/heads ref to merge from. The merge reads the source and never updates it. Provide source_ref or the deprecated source_branch. examples: - feature/preview type: string squash: description: When true, collapse the source into a single new commit whose only parent is the current target tip. Defaults to false, which preserves the standard merge/fast-forward behavior. Incompatible with the ff_only strategy. examples: - false type: boolean strategy: description: Merge strategy. merge creates a merge commit when needed, ff_only rejects non-fast-forward merges, and ff_prefer fast-forwards when possible before falling back to a merge commit. enum: - merge - ff_only - ff_prefer examples: - merge type: string target_branch: description: Destination branch to update. A merge always updates a branch. examples: - main type: string target_is_ephemeral: description: Whether target_branch should be resolved from the ephemeral namespace. type: boolean required: - target_branch - strategy type: object ReposMergeResponse: additionalProperties: false description: Merge outcome including the resulting commit, source and target state, merge base information, and retry attempt counters when applicable. properties: commit_sha: description: Commit SHA for the merge result. For a fast-forward or no-op, this is the resulting target tip. examples: - 41f0d5c6cc5f4d0fb4a3af2de27ccf9a80ab3b84 type: string merge_base_sha: description: Merge base SHA when one exists and the backend reports it. examples: - a2d127e6a4d54bb7390de828a99e36411f0c84df type: string promoted_commits: description: Number of commits promoted from source onto target. examples: - 3 format: int32 minimum: 0 type: integer result: description: "Merge outcome: merge_commit, fast_forward, no_op, squash, or unknown." examples: - merged type: string source: $ref: "#/components/schemas/MergeSourceState" description: Source ref metadata with branch, ephemeral, and resolved sha. target: $ref: "#/components/schemas/MergeTargetState" description: Target ref metadata with branch, ephemeral, previous old_sha, and resulting new_sha. tree_sha: description: Tree SHA for the resulting commit or target tip. examples: - b9532c5d5be50d88e2f45d7c229566b2f1f99731 type: string required: - result - commit_sha - tree_sha - source - target - promoted_commits type: object ReposNotesAppendRequest: additionalProperties: false description: Append-note request describing the Git object, the text to add, and the optional notes ref guard. properties: author: $ref: "#/components/schemas/GitIdentity" description: Author object with name and email for the notes commit. expected_notes_ref_sha: description: Optional compare-and-swap guard for the notes ref. Provide expected_notes_ref_sha or the deprecated expected_ref_sha. type: string expected_ref_sha: deprecated: true description: "Deprecated: use expected_notes_ref_sha. Optional compare-and-swap guard for the notes ref." type: string note: description: Plain text to add to the note. examples: - Deployment complete. type: string notes_ref: description: 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. examples: - refs/notes/commits type: string object_ref: description: "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." examples: - b003fc78805954584e1ee364a4ad39d7c79e819a type: string ref: deprecated: true description: "Deprecated: use notes_ref. Optional notes ref to target." examples: - refs/notes/commits type: string sha: deprecated: true description: "Deprecated: use object_ref. Git object SHA to attach the note to." examples: - b003fc78805954584e1ee364a4ad39d7c79e819a type: string required: - note type: object ReposNotesCreateRequest: additionalProperties: false description: Create-note request describing the Git object, the note content, and the optional notes ref guard. properties: action: default: add deprecated: true description: "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." type: string author: $ref: "#/components/schemas/GitIdentity" description: Author object with name and email for the notes commit. expected_notes_ref_sha: description: Optional compare-and-swap guard for the notes ref. Provide expected_notes_ref_sha or the deprecated expected_ref_sha. type: string expected_ref_sha: deprecated: true description: "Deprecated: use expected_notes_ref_sha. Optional compare-and-swap guard for the notes ref." type: string note: description: Plain-text note content. Required. examples: - Reviewed. Ready for production. type: string notes_ref: description: 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. examples: - refs/notes/commits type: string object_ref: description: "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." examples: - b003fc78805954584e1ee364a4ad39d7c79e819a type: string ref: deprecated: true description: "Deprecated: use notes_ref. Optional notes ref to target." examples: - refs/notes/commits type: string sha: deprecated: true description: "Deprecated: use object_ref. Git object SHA to attach the note to." examples: - b003fc78805954584e1ee364a4ad39d7c79e819a type: string type: object 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 ReposNotesGetResponse: additionalProperties: false description: A single Git note attached to a commit, including the current notes ref tip. properties: note: description: The note content. examples: - Reviewed. Ready for production. type: string ref_sha: description: Current SHA of the notes ref the note was read from. examples: - 0c8b5bb9d550d58fcfd651a4fdce8024ef7f1492 type: string sha: description: The commit SHA. examples: - b003fc78805954584e1ee364a4ad39d7c79e819a type: string required: - sha - note - ref_sha type: object ReposNotesRefsListResponse: additionalProperties: false description: Paginated list of Git notes refs under the requested prefix. properties: has_more: description: Whether another page is available. examples: - true type: boolean next_cursor: description: Opaque cursor for the next page. Pass it as `cursor` to read the next page. Absent when there are no more results. examples: - MTcwNzU3MzQ1MTAwMDAwMDAwMHxyZXBvXzlhNGMyMWY type: string prefix: description: Normalized notes ref prefix used for the listing. examples: - refs/notes/reviews/ type: string refs: description: List of notes refs. items: $ref: "#/components/schemas/NotesRef" type: array required: - refs - prefix - has_more type: object ReposPreviewMergeResponse: additionalProperties: false description: Read-only merge preview result, including clean or conflicted status and optional inline conflict content. properties: conflict_paths: description: Repository paths that conflicted during the merge preview. items: type: string type: array conflicts: description: Inline conflict content, populated only when include_content=true. items: $ref: "#/components/schemas/PreviewMergeConflict" type: array filtered_conflicts: description: Conflicts omitted from inline content because of request or server limits. items: $ref: "#/components/schemas/PreviewMergeFilteredConflict" type: array merge_base_sha: description: Merge base SHA used for the preview. examples: - a2d127e6a4d54bb7390de828a99e36411f0c84df type: string result: description: "Operation result if applied: merge_commit, fast_forward, or no_op." enum: - merge_commit - fast_forward - no_op examples: - merge_commit type: string source_branch: description: Source branch requested by the caller. examples: - feature/preview type: string source_tip_sha: description: Resolved source branch tip SHA. examples: - 9eb378bdb5bf1944f6ba0bd5a2c4df3ce32f4df1 type: string status: description: "Preview status: clean or conflicted." enum: - clean - conflicted examples: - conflicted type: string target_branch: description: Target branch requested by the caller. examples: - main type: string target_tip_sha: description: Resolved target branch tip SHA. examples: - c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 type: string required: - status - result - source_branch - target_branch - source_tip_sha - target_tip_sha - conflict_paths - conflicts type: object ReposTagsCreateRequest: additionalProperties: false description: Create-tag request body describing the new tag and the commit it points to. properties: name: description: Tag name. Must be a valid Git ref name and must not start with refs/. examples: - v1.0.0 type: string ref: description: Branch, tag, or commit the tag should point to. Provide ref or the deprecated target. examples: - main type: string target: deprecated: true description: "Deprecated: use ref. Commit the tag should point to." examples: - a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2 type: string required: - name type: object ReposTagsCreateResponse: additionalProperties: false description: Result of creating a tag. properties: message: description: Human-readable result message. examples: - tag created type: string name: description: Tag name. examples: - v1.0.0 type: string sha: description: Commit SHA the tag points to. examples: - a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2 type: string required: - name - sha - message type: object ReposTagsDeleteRequestLegacy: additionalProperties: false description: Tag deletion request identifying the tag to remove. properties: name: description: Tag name to delete. Must not start with refs/. examples: - v1.0.0 type: string required: - name type: object ReposTagsDeleteResponse: additionalProperties: false description: Result of deleting a tag. properties: message: description: Human-readable result message. examples: - tag deleted type: string name: description: Tag name. examples: - v1.0.0 type: string required: - name - message type: object ReposTagsGetResponse: additionalProperties: false description: One tag that matches an exact short name. properties: tag: $ref: "#/components/schemas/Tag" description: The tag that has the requested name. required: - tag type: object ReposTagsListResponse: additionalProperties: false description: Paginated list of tags for the repository. properties: has_more: description: Whether another page is available. examples: - true type: boolean next_cursor: description: Opaque cursor for the next page. Pass it as `cursor` to read the next page. Absent when there are no more results. examples: - MTcwNzU3MzQ1MTAwMDAwMDAwMHxyZXBvXzlhNGMyMWY type: string tags: description: List of tag objects. items: $ref: "#/components/schemas/TagListItem" type: array required: - tags - has_more type: object ReposUpdateRequest: additionalProperties: false description: Repository settings to patch, such as the default branch. properties: default_branch: description: New default branch name for the Code Storage repository. examples: - main type: string type: object ReposUpdateResponse: additionalProperties: false description: Repository state after applying the patch. properties: default_branch: description: Updated default branch name. examples: - main type: string id: deprecated: true description: "Deprecated: use repo_name. Stable repository identifier." examples: - repo_7f2b3d9 type: string repo_id: deprecated: true description: "Deprecated: use repo_name. Stable repository identifier." examples: - repo_7f2b3d9 type: string repo_name: description: Repository name or path. It can contain a slash. It matches the JWT repo claim. examples: - pierre/sdk-documentation type: string url: deprecated: true description: "Deprecated: use repo_name. Repository name or path, not a full URL." examples: - pierre/sdk-documentation type: string required: - repo_id - id - repo_name - url - default_branch type: object ReposUpstreamDeleteResponse: additionalProperties: false description: Confirmation that the upstream link has been detached from the repository. properties: message: description: Human-readable detach status message. examples: - repository detached type: string required: - message type: object ReposUpstreamPullRequest: additionalProperties: false description: Deprecated upstream pull body. Its fields have no effect, so send no body. properties: after: deprecated: true description: "Deprecated: omit it. The field has no effect, and no response returns a token for it. A pull syncs every branch and tag of the upstream." type: string ref: deprecated: true description: "Deprecated: omit it. The field has no effect: a pull syncs every branch and tag of the upstream." type: string type: object ReposUpstreamPullResponse: additionalProperties: false description: Acknowledgement that an upstream sync has been initiated; the sync itself runs asynchronously. properties: message: description: Human-readable status message. examples: - Repository sync initiated successfully type: string required: - message type: object Repository: additionalProperties: false description: A repository, including its Git Sync upstream when one is configured. properties: base_repo: $ref: "#/components/schemas/UpstreamRepo" deprecated: true description: "Deprecated: use upstream. The upstream of the repository, when it has one." created_at: description: ISO 8601 creation timestamp. examples: - "2024-01-15T10:30:00Z" type: string default_branch: description: Default branch name. examples: - main type: string repo_id: deprecated: true description: "Deprecated: use repo_name. Stable repository identifier." examples: - repo_7f2b3d9 type: string repo_name: description: Repository name or path. It can contain a slash. It matches the JWT repo claim. examples: - team/project-alpha type: string upstream: $ref: "#/components/schemas/UpstreamRepo" description: External Git host that the repository keeps syncing from. Absent when the repository has no upstream. url: deprecated: true description: "Deprecated: use repo_name. Repository name or path, not a full URL." examples: - team/project-alpha type: string required: - repo_id - repo_name - url - default_branch - created_at type: object RestoreCommitRefGuardProblemDetails: allOf: - $ref: "#/components/schemas/RefGuardProblemDetails" - properties: result: $ref: "#/components/schemas/RefUpdateResult" description: Branch update result. required: - result type: object description: Problem details of a restore whose `expected_target_sha` guard failed. The body keeps `result`, and `commit` is null. type: object RestoredCommit: additionalProperties: false description: Commit object generated by a restore-commit operation. properties: commit_sha: description: SHA of the new restore commit. type: string pack_bytes: description: Size of the generated pack in bytes. format: int64 minimum: 0 type: integer target_branch: description: Branch that was reset. type: string tree_sha: description: Tree SHA of the restore commit. type: string required: - commit_sha - tree_sha - target_branch - pack_bytes type: object Tag: description: A tag. properties: name: description: Tag name. examples: - v1.0.0 type: string sha: description: Dereferenced commit SHA for the tag. examples: - a1b2c3d4e5f6 type: string required: - name - sha type: object TagListItem: allOf: - $ref: "#/components/schemas/Tag" - properties: cursor: description: Opaque pagination token for this tag entry. examples: - t_abc123 type: string required: - cursor type: object description: A tag in a list, with its pagination cursor. type: object UpstreamConfig: additionalProperties: false description: External Git host that a new repository keeps syncing from. properties: access: description: GitHub only. app (the default) reads through the GitHub App installation of the organization. public mirrors a public repository without an installation, and syncs only on request. enum: - app - public type: string host: description: Bare hostname of a self-hosted provider, such as gitlab.example.com. It defaults to the public host of the provider. type: string name: description: Repository name on the upstream provider. examples: - hello-world type: string owner: description: Repository owner or namespace on the upstream provider. examples: - octocat type: string provider: description: External Git host of the upstream repository. enum: - github - gitlab - bitbucket - gitea - forgejo - codeberg - sr.ht - sourcehut type: string required: - provider - owner - name type: object UpstreamRepo: additionalProperties: false description: Git Sync upstream of a repository. properties: name: description: Upstream repository name. examples: - Hello-World type: string owner: description: Upstream repository owner or namespace. examples: - octocat type: string provider: description: Upstream provider name. examples: - github type: string required: - provider 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 WebhookRepository: additionalProperties: false description: The repository that produced the event. properties: id: description: The internal repository ID. type: string repo_name: description: The repository name, for example team/project. It can be absent on older deliveries. type: string url: deprecated: true description: "Deprecated: use repo_name, which has the same value. The repository name, for example team/project." type: string required: - id - url type: object WrittenCommit: additionalProperties: false description: Commit object information generated when a pack is applied. properties: blob_count: description: Number of blobs included in the pack. format: int32 minimum: 0 type: integer commit_sha: description: SHA of the new commit. type: string pack_bytes: description: Size of the generated pack in bytes. format: int64 minimum: 0 type: integer target_branch: description: Branch the commit was written to. type: string tree_sha: description: Tree SHA of the new commit. type: string required: - commit_sha - tree_sha - target_branch - pack_bytes - blob_count 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 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 openapi: 3.1.0 paths: /api/meta: get: description: |- Return the cloud provider, region, and public inbound IP addresses of the Code Storage cluster that serves the current organisation. Addresses are listed separately for Git over HTTPS and for the HTTP API; allow them in firewall rules that restrict outbound traffic to Code Storage. The lists change when the cluster's ingress changes, so poll this endpoint rather than copying them once. Scope: `org:read`. operationId: meta-get responses: "200": content: application/json: example: ips: api: - 192.0.2.0/24 git: - 192.0.2.0/24 provider: name: aws region: us-east-2 schema: $ref: "#/components/schemas/Meta" description: Cloud location and inbound IP addresses of the cluster that serves the organisation. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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: - org:read summary: Get Organization Metadata tags: - Organization x-permission-scopes: - org:read x-requires-repo-scope: false x-stability: stable /api/repos: get: description: |- List repositories for the current organisation with cursor-based pagination. Supply `q` to filter results by a case-insensitive substring match against `repo_name` (for example `pierre/sdk-documentation`), and `prefix` to filter by the start of `repo_name`. When both are set they combine with AND: a repository is returned only when it matches both filters. Scope: `org:read`. operationId: repos-list parameters: - description: Case-insensitive substring to match against `repo_name`. Trimmed before matching. When `prefix` is also set, both must match (AND) and `q` only matches the part of `repo_name` after the prefix. When omitted or empty after trimming, the full repository list is returned. example: sdk in: query name: q schema: type: string - description: Case-insensitive prefix to match against the start of `repo_name`. For example, `pierre/` matches `pierre/sdk-documentation` and `pierre/example` but not `acme/pierre-tools`. When `q` is also set, both must match (AND) and `q` only matches the part of `repo_name` after the prefix, so `prefix=pierre/&q=sdk` returns `pierre/sdk-documentation` but not `pierre/example`. Trimmed before matching. When omitted or empty after trimming, no prefix filter applies. example: pierre/ in: query name: prefix schema: type: string - description: Pagination cursor from previous response (base64 encoded) example: MTcwNzU3MzQ1MTAwMDAwMDAwMHxyZXBvXzlhNGMyMWY in: query name: cursor schema: type: string - description: Maximum number of repositories to return. Defaults to 20 and is capped at 100. example: 20 in: query name: limit schema: default: 20 maximum: 100 minimum: 1 type: integer responses: "200": content: application/json: example: has_more: true next_cursor: MTcwNzU3MzQ1MTAwMDAwMDAwMHxyZXBvXzlhNGMyMWY repos: - created_at: "2024-01-15T10:30:00Z" default_branch: main repo_name: team/project-alpha upstream: name: Hello-World owner: octocat provider: github schema: $ref: "#/components/schemas/ReposListResponse" description: A paginated view of repositories in the organisation. "400": content: application/json: example: code: bad_request detail: invalid cursor error: invalid cursor instance: /api/repos status: 400 title: Bad Request type: about:blank schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: example: code: bad_request detail: invalid cursor error: invalid cursor instance: /api/repos status: 400 title: Bad Request type: about:blank schema: $ref: "#/components/schemas/ProblemDetails" description: The supplied pagination cursor could not be decoded. "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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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: - org:read summary: List Repos tags: - Repositories x-permission-scopes: - org:read x-requires-repo-scope: false x-stability: stable post: description: |- Create a repository. A repository starts empty or from a source. `base_repo` is a one-time copy of a Code Storage repository; `upstream` is a lasting link to an external Git host. A copy takes the history of one commit (`base_repo.ref`, or the source HEAD) into one branch, and keeps no link to its source. A sync keeps its upstream, and the repository can sync from it again. Set at most one of the two. A new empty repository has no branch until its first commit. The first commit creates the branch that it targets, so the default branch exists only after a commit to it. Create is idempotent on the repository name. A new repository returns `201`. When the name already exists, the request returns `200`, and a copy copies nothing. When the name exists with a different upstream, the request returns `409`. The deprecated form of `base_repo`, with `provider` and `operation`, still works. Scope: `repo:write` on the repository. operationId: repos-create parameters: - deprecated: true description: "Deprecated: use the default_branch body field instead. Default branch for the new repository. When the body also has default_branch, the body value wins." in: query name: default_branch schema: type: string requestBody: content: application/json: example: base_repo: auth: token: SOURCE_REPO_READ_TOKEN name: pierre/sdk-documentation ref: main default_branch: feature-preview repo_name: pierre/docs-copy examples: copy: description: Create an independent repository from one commit of another Code Storage repository. summary: Copy value: base_repo: auth: token: SOURCE_REPO_READ_TOKEN name: pierre/sdk-documentation ref: main default_branch: feature-preview repo_name: pierre/docs-copy empty_repo: description: Create a new repository with an explicit default branch. summary: Empty repository value: default_branch: main repo_name: pierre/my-repo generic_git_sync: description: Mirror a repository from a generic HTTPS Git provider such as GitLab, Bitbucket, Gitea, or Forgejo. summary: Generic HTTPS Git sync value: default_branch: main repo_name: pierre/repo-name upstream: host: git.example.com name: repo-name owner: org-name provider: gitea public_github_sync: description: Mirror a public GitHub repository without a GitHub App installation. summary: Public GitHub sync value: default_branch: main repo_name: pierre/hello-world upstream: access: public name: hello-world owner: octocat provider: github schema: $ref: "#/components/schemas/ReposCreateRequest" description: Create an empty repository, a copy of a Code Storage repository (`base_repo`), or a repository that syncs from an external Git host (`upstream`). responses: "200": content: application/json: example: message: Repository 'pierre/sdk-documentation' already exists repo_name: pierre/sdk-documentation schema: $ref: "#/components/schemas/ReposCreateResponse" description: The repository already existed, and the request created nothing. "201": content: application/json: example: message: Repository 'pierre/sdk-documentation' created repo_name: pierre/sdk-documentation schema: $ref: "#/components/schemas/ReposCreateResponse" description: The request created the repository. "400": content: application/json: example: code: bad_request detail: base_repo and upstream cannot both be set. Use base_repo to copy a Code Storage repository, or upstream to sync from an external Git host. error: base_repo and upstream cannot both be set. Use base_repo to copy a Code Storage repository, or upstream to sync from an external Git host. instance: /api/repos status: 400 title: Bad Request type: about:blank schema: $ref: "#/components/schemas/ValidationProblemDetails" application/problem+json: example: code: bad_request detail: base_repo and upstream cannot both be set. Use base_repo to copy a Code Storage repository, or upstream to sync from an external Git host. error: base_repo and upstream cannot both be set. Use base_repo to copy a Code Storage repository, or upstream to sync from an external Git host. instance: /api/repos status: 400 title: Bad Request type: about:blank schema: $ref: "#/components/schemas/ValidationProblemDetails" description: The repository name was invalid or did not match the JWT repo claim, the request set both base_repo and upstream, or the source was invalid. `invalid_params` names each invalid field of the body. "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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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: - repo:write summary: Create Repo tags: - Repositories x-permission-scopes: - repo:write x-request-validation-profile: create_repo x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}: delete: description: |- Permanently retire a repository. The API performs a soft delete first and then triggers asynchronous hot and cold storage cleanup. Scope: `repo:write` on the repository. operationId: repos-delete parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string responses: "200": content: application/json: example: message: Repository pierre/sdk-documentation deletion initiated. Physical storage cleanup will complete asynchronously. repo_name: pierre/sdk-documentation schema: $ref: "#/components/schemas/ReposDeleteResponse" description: Deletion accepted. Physical storage cleanup continues asynchronously. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: example: code: repository_deleted detail: repository already deleted error: repository already deleted instance: /api/repos/dotfiles status: 409 title: Conflict type: about:blank schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: example: code: repository_deleted detail: repository already deleted error: repository already deleted instance: /api/repos/dotfiles status: 409 title: Conflict type: about:blank schema: $ref: "#/components/schemas/ProblemDetails" description: The repository was already deleted. "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: - repo:write summary: Delete Repo tags: - Repositories x-permission-scopes: - repo:write x-requires-repo-scope: true x-stability: stable get: description: |- Fetch the metadata of a repository. Scope: `git:read` on the repository. operationId: repos-get parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string responses: "200": content: application/json: example: created_at: "2024-01-15T10:30:00Z" default_branch: main repo_name: team/project-alpha upstream: name: Hello-World owner: octocat provider: github schema: $ref: "#/components/schemas/Repository" description: Repository metadata resolved from the JWT `repo` claim. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: Get Repo tags: - Repositories x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable patch: description: |- Change the default branch of a repository. The gateway reads the current `HEAD` symbolic ref, then repoints it at the requested branch through a transactional compare-and-swap against that value, and finally records the new default branch in the repository row. Branch names are fully qualified for you: `main` is written as the symref target `refs/heads/main`, and a value that already starts with `refs/` is used verbatim. The branch itself is not created by this call. Scope: `repo:write` on the repository. operationId: repos-update parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string requestBody: content: application/json: example: default_branch: main schema: $ref: "#/components/schemas/ReposUpdateRequest" description: Repository settings to change. `default_branch` is the only supported field and must be a non-empty branch name. required: true responses: "200": content: application/json: example: default_branch: main repo_name: pierre/sdk-documentation schema: $ref: "#/components/schemas/ReposUpdateResponse" description: Default branch updated. Returns the repository ID, its URL path, and the branch name now recorded as the default. "400": content: application/json: example: code: bad_request detail: default_branch must be a string error: default_branch must be a string invalid_params: - name: default_branch reason: must be a string status: 400 title: Bad Request type: about:blank schema: $ref: "#/components/schemas/ValidationProblemDetails" application/problem+json: example: code: bad_request detail: default_branch must be a string error: default_branch must be a string invalid_params: - name: default_branch reason: must be a string status: 400 title: Bad Request type: about:blank schema: $ref: "#/components/schemas/ValidationProblemDetails" description: The body could not be decoded as JSON, a field was not valid, or `default_branch` was missing or empty. `invalid_params` names each invalid field. "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: No repository matching the JWT `repo` claim exists for this organisation. "409": content: application/json: example: code: conflict detail: default branch was modified concurrently, please retry error: default branch was modified concurrently, please retry instance: /api/repos/my-demo-repository status: 409 title: Conflict type: about:blank schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: example: code: conflict detail: default branch was modified concurrently, please retry error: default branch was modified concurrently, please retry instance: /api/repos/my-demo-repository status: 409 title: Conflict type: about:blank schema: $ref: "#/components/schemas/ProblemDetails" description: "`HEAD` moved between the read and the compare-and-swap, so the update was rejected. Retry the request." "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: The current `HEAD` value could not be read from storage, so no compare-and-swap was attempted and nothing was changed. headers: Retry-After: description: Minimum delay in seconds before retrying. schema: type: string security: - bearerAuth: - repo:write summary: Update Repository Settings tags: - Repositories x-permission-scopes: - repo:write x-request-validation-profile: update_repo x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}/archive: post: description: |- Download a repository snapshot without cloning the repo. This is useful for packaging docs, examples, or release artefacts directly from a branch, tag, or commit. Scope: `git:read` on the repository. operationId: repos-archive-get parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string requestBody: content: application/json: examples: docs_snapshot: description: Download just the docs tree with a prefixed root folder. summary: Filtered documentation snapshot value: archive: prefix: sdk-docs/ exclude_globs: - "**/drafts/**" include_globs: - docs/** - README.md ref: main schema: $ref: "#/components/schemas/ReposArchiveGetRequest" description: Request a `.tar.gz` snapshot of the repository at a branch, tag, or commit. Include and exclude globs let you shape the archive before it streams back. responses: "200": content: application/gzip: schema: contentMediaType: application/octet-stream description: Gzip-compressed tar archive stream. format: binary type: string description: A streamed `.tar.gz` archive of the resolved revision. headers: Cache-Control: description: Archive downloads are returned with `no-store`. schema: type: string Content-Disposition: description: Attachment filename generated from the repository URL and resolved revision. schema: type: string "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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: Archive tags: - Files x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}/base: delete: deprecated: true description: |- Detach the repository from its configured upstream provider. The operation is idempotent: already-detached repositories return success. `DELETE /api/repos/{repo_name}/upstream` replaces this endpoint. It returns the same responses. Scope: `repo:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/upstream` instead. operationId: unset_base_repo parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string responses: "200": content: application/json: example: message: repository detached schema: $ref: "#/components/schemas/ReposUpstreamDeleteResponse" description: Upstream detach result. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: example: message: repository detached schema: $ref: "#/components/schemas/ReposUpstreamDeleteResponse" description: The detach workflow is already in progress or the sync workflow is missing. "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: - repo:write summary: Unset Base Repo tags: - Repositories x-deprecation-message: Use `/api/repos/{repo_name}/upstream` instead. x-permission-scopes: - repo:write x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}/blame: get: description: |- Return per-line blame metadata for a file at a branch, tag, or commit. Supports `git blame -L`-style range filters and rename/copy detection for callers building IDE blame views or audit tooling. Scope: `git:read` on the repository. operationId: repos-blame-get parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string - description: Repository-relative file path to blame. example: src/main.go in: query name: path required: true schema: type: string - description: Optional branch, tag, or commit SHA to blame at. When omitted, the repository default branch is used. example: main in: query name: ref schema: type: string - description: Whether `ref` should be resolved from the ephemeral namespace. in: query name: ephemeral schema: type: boolean - description: "Optional `git blame -L`-style range spec. May be repeated to blame multiple regions (max 16). Each value is one `-L` argument: e.g. `10,20`, `10,+5`, `/getUser/,/^}/`, `/getUser/,+30`, `10,`, `,20`, `10`, `:^func .*Foo`, `:funcname`." example: - 10,20 in: query name: range schema: items: type: string type: array - description: Follow the file across renames and copies. in: query name: detect_moves schema: type: boolean responses: "200": content: application/json: example: commit_sha: b003fc78805954584e1ee364a4ad39d7c79e819a lines: - author_email: jane@example.com author_name: Jane Doe author_time: "2024-01-15T14:32:18Z" commit_sha: b003fc78805954584e1ee364a4ad39d7c79e819a committer_email: jane@example.com committer_name: Jane Doe committer_time: "2024-01-15T14:32:18Z" line_number: 42 original_line_number: 40 original_path: src/main.go previous_commit_sha: a4d39d7c79e819ab003fc78805954584e1ee36 summary: "fix: resolve scrolling issue in dashboard" path: src/main.go ref: main schema: $ref: "#/components/schemas/ReposBlameGetResponse" description: Per-line blame for the resolved file revision. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: Blame tags: - Files x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}/branch: get: description: |- Get one branch by its exact short name. The response omits list pagination fields. A new empty repository has no branch until its first commit, so the request returns `404`. Scope: `git:read` on the repository. operationId: repos-branches-get parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string - description: Exact short branch name. example: main in: query name: name required: true schema: type: string - description: When true, get the branch from the ephemeral namespace. in: query name: ephemeral schema: type: boolean responses: "200": content: application/json: example: branch: created_at: "2024-01-15T10:30:00Z" head_sha: a1b2c3d4e5f6 name: main schema: $ref: "#/components/schemas/ReposBranchesGetResponse" description: The branch with the requested name. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: Get Branch tags: - Branches x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}/branches: delete: description: |- Delete a branch from the repository. Name the branch with the `target_branch` and `ephemeral` query parameters. The server resolves the current branch tip before deleting, so the caller does not need the branch SHA. The default branch is protected and cannot be deleted through this endpoint. Scope: `git:write` on the repository. operationId: repos-branches-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: Exact short name of the branch to delete. Must not start with refs/. Required unless the deprecated body names the branch. example: feature/old-onboarding in: query name: target_branch schema: type: string - description: When true, delete the branch from the ephemeral namespace instead of the default namespace. in: query name: ephemeral schema: type: boolean requestBody: content: application/json: schema: $ref: "#/components/schemas/ReposBranchesDeleteRequest" description: "Deprecated: send the `target_branch` and `ephemeral` query parameters, and no body. A query parameter wins over its body field." responses: "200": content: application/json: example: ephemeral: false message: branch deleted target_branch: feature/old-onboarding schema: $ref: "#/components/schemas/ReposBranchesDeleteResponse" description: Branch deletion result. "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: example: code: conflict detail: cannot delete the default branch error: cannot delete the default branch instance: /api/repos/dotfiles/branches status: 409 title: Conflict type: about:blank schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: example: code: conflict detail: cannot delete the default branch error: cannot delete the default branch instance: /api/repos/dotfiles/branches status: 409 title: Conflict type: about:blank schema: $ref: "#/components/schemas/ProblemDetails" description: The branch could not be deleted because it is the repository default branch. "412": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" description: "`412` has more than one cause. Storage returns `precondition_failed` for a write-specific reason, such as a merge with no common ancestor between source and target, a merge target that moved off a fast-forward under the `ff_only` strategy, or a branch creation whose target cannot be fast-forwarded. A repository with a GitHub upstream also gets `412` when the write cannot reach GitHub: the code is `github_app_not_configured` when the GitHub App has no usable private key, `github_repository_inaccessible` when GitHub does not give the App access to the repository, and `precondition_failed` when GitHub refuses the push for another reason, such as an archived repository. `detail` explains the failure." "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 "502": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" description: A storage node, the upstream Git server or GitHub failed or could not be reached. When the push request to the upstream failed or got a server error, the write may have been applied; check the branch before retrying. "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 summary: Delete Branch tags: - Branches x-permission-scopes: - git:write x-requires-repo-scope: true x-stability: stable get: description: |- List branches in the repository with cursor pagination. Use this to build branch selectors, review tools, or sync jobs without shelling out to Git. A new empty repository has no branch until its first commit, so its list is empty. Scope: `git:read` on the repository. operationId: repos-branches-list parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string - description: Pagination cursor returned by a previous `list_branches` response. example: b_456def in: query name: cursor schema: type: string - description: Maximum number of branches to return. Defaults to 20. example: 20 in: query name: limit schema: default: 20 type: integer - description: When true, list branches under the ephemeral namespace instead of regular branches. in: query name: ephemeral schema: type: boolean responses: "200": content: application/json: example: branches: - created_at: "2024-01-15T10:30:00Z" cursor: b_123abc head_sha: a1b2c3d4e5f6 name: main has_more: true next_cursor: MTcwNzU3MzQ1MTAwMDAwMDAwMHxyZXBvXzlhNGMyMWY schema: $ref: "#/components/schemas/ReposBranchesListResponse" description: Repository branches in creation order. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: List Branches tags: - Branches x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}/branches/create: post: description: |- Create a new branch from an existing branch or ref. This is useful for agent workflows, ephemeral previews, or server-side automation where you do not want to clone the repo first. The base ref must exist. A new empty repository has no branch until its first commit, so the request returns `404`. Scope: `git:write` on the repository. operationId: repos-branches-create parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string requestBody: content: application/json: example: base_is_ephemeral: false base_ref: main target_branch: feature/new-onboarding target_is_ephemeral: false schema: $ref: "#/components/schemas/ReposBranchesCreateRequest" description: Create a branch from another branch or ref. The source and destination can live in the default namespace or the ephemeral namespace. required: true responses: "200": content: application/json: example: commit_sha: abc123def4567890abc123def4567890abc123de message: branch created target_branch: feature/new-onboarding target_is_ephemeral: false schema: $ref: "#/components/schemas/ReposBranchesCreateResponse" description: Branch creation result. "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: schema: $ref: "#/components/schemas/ProblemDetails" description: Conflict "412": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" description: "`412` has more than one cause. Storage returns `precondition_failed` for a write-specific reason, such as a merge with no common ancestor between source and target, a merge target that moved off a fast-forward under the `ff_only` strategy, or a branch creation whose target cannot be fast-forwarded. A repository with a GitHub upstream also gets `412` when the write cannot reach GitHub: the code is `github_app_not_configured` when the GitHub App has no usable private key, `github_repository_inaccessible` when GitHub does not give the App access to the repository, and `precondition_failed` when GitHub refuses the push for another reason, such as an archived repository. `detail` explains the failure." "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 "502": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" description: A storage node, the upstream Git server or GitHub failed or could not be reached. When the push request to the upstream failed or got a server error, the write may have been applied; check the branch before retrying. "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 summary: Create Branch tags: - Branches x-permission-scopes: - git:write x-request-validation-profile: create_branch x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}/branches/diff: get: deprecated: true description: |- Compare a feature branch to its base branch and return every change that would be reviewed before a merge. Repeated `path` filters limit the diff to selected files and bypass the usual large-file filtering for those requested paths. `GET /api/repos/{repo_name}/diff` replaces this endpoint. Send `branch` as `ref`, `base` as `base_ref`, `ephemeral` as `ref_is_ephemeral`, and `ephemeral_base` as `base_is_ephemeral`. When you omit `base`, this endpoint diffs against the repository default branch. When you omit `base_ref`, `/diff` returns the diff of one commit. To get the same diff, read `default_branch` from the repository and send it as `base_ref`. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/diff` with `ref` and `base_ref` instead. operationId: get_branch_diff parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string - description: Branch name to diff. example: feature/new-auth in: query name: branch required: true schema: type: string - description: Optional base branch or ref to diff against. When omitted, the repository default branch is used. example: main in: query name: base schema: type: string - description: Whether `branch` should be resolved from the ephemeral namespace. example: true in: query name: ephemeral schema: type: boolean - description: Whether `base` should be resolved from the ephemeral namespace. example: false in: query name: ephemeral_base schema: type: boolean - description: Optional repeated path filter. Provide multiple `path` query values to restrict the diff to specific files or directories. example: - src/main.go - README.md in: query name: path schema: items: type: string type: array responses: "200": content: application/json: example: base: main branch: feature/new-feature files: - bytes: 2048 is_eof: true path: src/main.go raw: |- diff --git a/src/main.go b/src/main.go ... state: M filtered_files: - bytes: 50000 is_eof: true path: package-lock.json state: M merge_base_sha: a2d127e6a4d54bb7390de828a99e36411f0c84df stats: additions: 50 changes: 60 deletions: 10 files: 3 schema: $ref: "#/components/schemas/GetBranchDiffResponse" description: Diff between a source branch and its base, including the merge base used for the three-dot comparison. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: Get Branch Diff tags: - Commits x-deprecation-message: Use `/api/repos/{repo_name}/diff` with `ref` and `base_ref` instead. x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}/commit: get: description: |- Resolve a branch name, short SHA, or full SHA to a commit and return the same metadata shape used in commit listings. Use this when you need commit details without computing a diff. Scope: `git:read` on the repository. operationId: repos-commits-get parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string - description: Branch name, tag, full commit SHA, short SHA, or other revision Git can resolve. Provide `ref` or the deprecated `sha`. example: main in: query name: ref schema: type: string - deprecated: true description: "Deprecated: use ref instead. Commit SHA, short SHA, branch name, or other revision Git can resolve." in: query name: sha schema: type: string responses: "200": content: application/json: example: commit: author_email: jane@example.com author_name: Jane Doe committer_date: "2024-01-16T09:05:41Z" committer_email: jane@example.com committer_name: Jane Doe date: "2024-01-15T14:32:18Z" message: "fix: resolve scrolling issue in dashboard" parent_shas: - f4f9df3b8db66c73f6bf67e8f8f4f14f6522731e sha: b003fc78805954584e1ee364a4ad39d7c79e819a signature: | -----BEGIN PGP SIGNATURE----- ... -----END PGP SIGNATURE----- schema: $ref: "#/components/schemas/ReposCommitsGetResponse" description: Commit metadata for the resolved revision. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: Get Commit tags: - Commits x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}/commit-pack: post: description: |- Create a commit by streaming file operations directly to the service. This is designed for automation, AI agents, and other workflows that need atomic Git writes without running a local Git process. Scope: `git:write` on the repository. operationId: repos-commits-create parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string requestBody: content: application/x-ndjson: example: | {"metadata":{"target_branch":"main","expected_target_sha":"d34db33fd34db33fd34db33fd34db33fd34db33f","commit_message":"Update docs","author":{"name":"Docs Bot","email":"docs@example.com"},"files":[{"path":"docs/changelog.md","operation":"upsert","content_id":"blob-1","mode":"100644"},{"path":"docs/legacy.txt","operation":"delete","content_id":"blob-2"}]}} {"blob_chunk":{"content_id":"blob-1","data":"IyBWZXJzaW9uIDIuMS4wCi0gcmVmcmVzaCBkb2NzCg==","eof":true}} {"blob_chunk":{"content_id":"blob-2","data":"","eof":true}} schema: contentSchema: items: additionalProperties: false properties: blob_chunk: $ref: "#/components/schemas/BlobChunk" required: - blob_chunk type: object minItems: 1 prefixItems: - additionalProperties: false properties: metadata: $ref: "#/components/schemas/ReposCommitsCreateRequest" required: - metadata type: object type: array description: NDJSON stream. The first line must be `metadata`; subsequent lines must be `blob_chunk` payloads. Decoded blob chunks are limited to 4 MiB each. type: string description: Send newline-delimited JSON where the first line is a `metadata` object and each following line is a `blob_chunk`. This lets you stream file contents without a local Git client. required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/CommitWriteResponse" description: Commit created and written to the target branch. "400": content: application/json: example: commit: null result: message: first payload must be metadata new_sha: "" old_sha: "" status: invalid success: false target_branch: "" schema: $ref: "#/components/schemas/CommitWriteResponse" description: The NDJSON stream was malformed or metadata validation failed. "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: example: commit: blob_count: 1 commit_sha: 7b3e9f2a1c4d5e6f708192a3b4c5d6e7f8091a2b pack_bytes: 1024 target_branch: main tree_sha: e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4 result: message: failed to update ref new_sha: 7b3e9f2a1c4d5e6f708192a3b4c5d6e7f8091a2b old_sha: d34db33fd34db33fd34db33fd34db33fd34db33f status: failed success: false target_branch: main schema: $ref: "#/components/schemas/CommitWriteResponse" application/problem+json: example: type: about:blank title: Conflict status: 409 detail: base_ref (d34db33fd34db33fd34db33fd34db33fd34db33f) does not match current head c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 code: ref_guard_failed error: base_ref (d34db33fd34db33fd34db33fd34db33fd34db33f) does not match current head c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 guard: expected_target_sha current_sha: c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 commit: null result: target_branch: main branch: main old_sha: c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 new_sha: "" success: false status: conflict message: base_ref (d34db33fd34db33fd34db33fd34db33fd34db33f) does not match current head c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 schema: $ref: "#/components/schemas/CommitWriteRefGuardProblemDetails" description: "The branch moved or the requested update could not be applied cleanly. When the branch moves after storage writes the commit, the body is `application/json`: `result.status` is `failed`, and `commit` is the commit that the branch did not get. When `expected_target_sha` is not the tip of the branch, the body is `application/problem+json` with the code `ref_guard_failed`: `guard` names the guard, and `current_sha` is the tip of the branch, which `result.old_sha` repeats. The body keeps the members of the failure body, and `result.status` is `conflict`." "412": content: application/json: example: commit: null result: message: no changes to commit new_sha: "" old_sha: "" status: precondition_failed success: false target_branch: "" schema: $ref: "#/components/schemas/CommitWriteResponse" description: "The commit makes no changes to the branch: the files match its tip, the request has no file operations, or it deletes only paths that do not exist. `result.status` is `precondition_failed` and `result.message` is `no changes to commit`. A malformed stream, such as a file without its final `eof` chunk, also gets `412`, with another message. A repository with a GitHub upstream also gets `412` when the write cannot reach GitHub: the GitHub App has no usable private key, GitHub does not give the App access to the repository, or GitHub refuses the push with `401`, `403` or `404`. Then `result.status` is `failed` and `result.message` explains the failure." "413": content: application/json: example: commit: null result: message: "commit payload too large: exceeds total blob limit (262144000 bytes)" new_sha: "" old_sha: "" status: payload_too_large success: false target_branch: "" schema: $ref: "#/components/schemas/CommitWriteResponse" description: The decoded file contents of the commit exceeded the total size limit. "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 "502": content: application/json: example: commit: null result: message: upstream Git server request failed; the push may or may not have been applied, check the branch before retrying new_sha: "" old_sha: "" status: internal success: false target_branch: "" schema: $ref: "#/components/schemas/CommitWriteResponse" description: A storage node, the upstream Git server or GitHub failed or could not be reached. When the push request to the upstream failed or got a server error, the write may have been applied; check the branch before retrying. `result.status` is `failed` when GitHub answers the push with a server error, and `commit` is the commit that the write tried to set. `result.status` is `internal` and `commit` is `null` when the push request fails, or when GitHub answers with a server error or cannot be reached while the gateway gets its GitHub token. `result.message` explains the failure. "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 summary: Create Commit from Files tags: - Commits x-permission-scopes: - git:write x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}/commits: get: description: |- List commit history for the repository default branch or for an explicit branch. Results are cursor-paginated and ordered by commit date, newest first. Set `path` to restrict the history to commits that modified a specific file or subtree. Scope: `git:read` on the repository. operationId: repos-commits-list parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string - description: Optional branch, tag, or commit to list commits from. When omitted, the repository default branch is used. Provide `ref` or the deprecated `branch`. example: main in: query name: ref schema: type: string - deprecated: true description: "Deprecated: use ref instead. Optional branch name to list commits from. When omitted, the repository default branch is used." in: query name: branch schema: type: string - description: Optional repository-relative path to scope the history to commits that touched that path. example: docs/guide.md in: query name: path schema: type: string - description: Pagination cursor returned by a previous `list_commits` response. example: "20" in: query name: cursor schema: type: string - description: Maximum number of commits to return. Defaults to 20. example: 20 in: query name: limit schema: default: 20 type: integer - description: Whether `ref` should be resolved from the ephemeral namespace. in: query name: ephemeral schema: type: boolean responses: "200": content: application/json: example: commits: - author_email: jane@example.com author_name: Jane Doe committer_date: "2024-01-16T09:05:41Z" committer_email: jane@example.com committer_name: Jane Doe date: "2024-01-15T14:32:18Z" message: "fix: resolve scrolling issue in dashboard" parent_shas: - f4f9df3b8db66c73f6bf67e8f8f4f14f6522731e sha: b003fc78805954584e1ee364a4ad39d7c79e819a signature: | -----BEGIN PGP SIGNATURE----- ... -----END PGP SIGNATURE----- has_more: true next_cursor: MTcwNzU3MzQ1MTAwMDAwMDAwMHxyZXBvXzlhNGMyMWY schema: $ref: "#/components/schemas/ReposCommitsListResponse" description: Commit history ordered from newest to oldest. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: List Commits tags: - Commits x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}/diff: get: description: |- Get the diff for a commit, optionally relative to a specific base commit. Repeated `path` parameters narrow the diff to selected files or directories. Scope: `git:read` on the repository. operationId: repos-diff-get parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string - description: Branch, tag, or commit to diff. Provide `ref` or the deprecated `sha`. example: b003fc78805954584e1ee364a4ad39d7c79e819a in: query name: ref schema: type: string - deprecated: true description: "Deprecated: use ref instead. Commit SHA to diff." in: query name: sha schema: type: string - description: Optional base branch, tag, or commit to diff against. When omitted, the diff is generated against the commit's parent. When set, the diff starts at the merge base of `base_ref` and `ref`, as `git diff base_ref...ref` does, and `merge_base_sha` gives that commit. So the diff holds only the changes on `ref` after the two histories split. When `ref` is an ancestor of `base_ref`, the merge base is `ref`, and the diff is empty. Provide `base_ref` or the deprecated `baseSha`. example: a4d39d7c79e819ab003fc78805954584e1ee36 in: query name: base_ref schema: type: string - deprecated: true description: "Deprecated: use base_ref instead. Optional base commit SHA to diff against. When omitted, the diff is generated against the commit's parent." in: query name: baseSha schema: type: string - description: Whether `ref` should be resolved from the ephemeral namespace. in: query name: ref_is_ephemeral schema: type: boolean - description: Whether `base_ref` should be resolved from the ephemeral namespace. in: query name: base_is_ephemeral schema: type: boolean - description: Optional repeated path filter. Provide multiple `path` query values to restrict the diff to specific files or directories. example: - src/main.go - README.md in: query name: path schema: items: type: string type: array - description: When enabled, concatenate `files[].raw` in response order and apply the result against the selected base with `git apply`. Changes listed in `filtered_files` are not included in the patch. Defaults to false, preserving review-oriented whitespace suppression. Provide `git_apply_compatible` or the deprecated `gitApplyCompatible`. example: false in: query name: git_apply_compatible schema: type: boolean - deprecated: true description: "Deprecated: use git_apply_compatible instead. When enabled, concatenate `files[].raw` in response order and apply the result against the selected base with `git apply`. Changes listed in `filtered_files` are not included in the patch. Defaults to false, preserving review-oriented whitespace suppression." in: query name: gitApplyCompatible schema: type: boolean responses: "200": content: application/json: example: base_sha: a2d127e6a4d54bb7390de828a99e36411f0c84df files: - bytes: 2048 is_eof: true path: src/main.go raw: |- diff --git a/src/main.go b/src/main.go ... state: M filtered_files: - bytes: 50000 is_eof: true path: package-lock.json state: M merge_base_sha: a2d127e6a4d54bb7390de828a99e36411f0c84df sha: b003fc78805954584e1ee364a4ad39d7c79e819a stats: additions: 50 changes: 60 deletions: 10 files: 3 schema: $ref: "#/components/schemas/ReposDiffGetResponse" description: Full diff for the requested commit, including file-level stats, line-level hunks, and merge base for explicit base comparisons. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: Get Commit Diff tags: - Commits x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}/diff-commit: post: description: |- Create a commit by streaming a Git patch instead of individual file blobs. Use this when your workflow already produces unified diffs or generated patches. Scope: `git:write` on the repository. operationId: repos-commits-createFromDiff parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string requestBody: content: application/x-ndjson: example: | {"metadata":{"target_branch":"main","expected_target_sha":"d34db33fd34db33fd34db33fd34db33fd34db33f","commit_message":"Apply generated patch","author":{"name":"Diff Bot","email":"diff@example.com"}}} {"diff_chunk":{"data":"ZGlmZiAtLWdpdCBhL1JFQURNRS5tZCBiL1JFQURNRS5tZAo=","eof":false}} {"diff_chunk":{"data":"QEAgLTEsMSArMSwyIEBACi1IZWxsbworSGVsbG8gV29ybGQK","eof":true}} schema: contentSchema: items: additionalProperties: false properties: diff_chunk: $ref: "#/components/schemas/DiffChunk" required: - diff_chunk type: object minItems: 1 prefixItems: - additionalProperties: false properties: metadata: $ref: "#/components/schemas/ReposCommitsCreateFromDiffRequest" required: - metadata type: object type: array description: NDJSON stream. The first line must be `metadata`; subsequent lines must be `diff_chunk` payloads. Decoded diff chunks are limited to 4 MiB each. type: string description: Send newline-delimited JSON where the first line is a `metadata` object and each following line is a `diff_chunk`. The combined diff must be compatible with `git apply --cached --binary`. required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/CommitWriteResponse" description: Commit created from the supplied diff. "400": content: application/json: example: commit: null result: message: diff content missing new_sha: "" old_sha: "" status: invalid success: false target_branch: "" schema: $ref: "#/components/schemas/CommitWriteResponse" description: The NDJSON stream or diff payload was invalid. "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: example: commit: blob_count: 1 commit_sha: 7b3e9f2a1c4d5e6f708192a3b4c5d6e7f8091a2b pack_bytes: 1024 target_branch: main tree_sha: e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4 result: message: failed to update ref new_sha: 7b3e9f2a1c4d5e6f708192a3b4c5d6e7f8091a2b old_sha: d34db33fd34db33fd34db33fd34db33fd34db33f status: failed success: false target_branch: main schema: $ref: "#/components/schemas/CommitWriteResponse" application/problem+json: example: type: about:blank title: Conflict status: 409 detail: base_ref (d34db33fd34db33fd34db33fd34db33fd34db33f) does not match current head c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 code: ref_guard_failed error: base_ref (d34db33fd34db33fd34db33fd34db33fd34db33f) does not match current head c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 guard: expected_target_sha current_sha: c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 commit: null result: target_branch: main branch: main old_sha: c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 new_sha: "" success: false status: conflict message: base_ref (d34db33fd34db33fd34db33fd34db33fd34db33f) does not match current head c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 schema: $ref: "#/components/schemas/CommitWriteRefGuardProblemDetails" description: "The diff could not be applied cleanly or the target branch tip changed. When the diff does not apply, the body is `application/json` and `result.status` is `conflict`. When the branch moves after storage writes the commit, the body is `application/json`: `result.status` is `failed`, and `commit` is the commit that the branch did not get. When `expected_target_sha` is not the tip of the branch, the body is `application/problem+json` with the code `ref_guard_failed`: `guard` names the guard, and `current_sha` is the tip of the branch, which `result.old_sha` repeats. The body keeps the members of the failure body, and `result.status` is `conflict`." "412": content: application/json: example: commit: null result: message: no changes to commit new_sha: "" old_sha: "" status: precondition_failed success: false target_branch: "" schema: $ref: "#/components/schemas/CommitWriteResponse" description: "Applying the diff makes no changes to the branch. `result.status` is `precondition_failed` and `result.message` is `no changes to commit`. A malformed stream, such as a stream without its final `eof` chunk, also gets `412`, with another message. A repository with a GitHub upstream also gets `412` when the write cannot reach GitHub: the GitHub App has no usable private key, GitHub does not give the App access to the repository, or GitHub refuses the push with `401`, `403` or `404`. Then `result.status` is `failed` and `result.message` explains the failure." "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 "502": content: application/json: example: commit: null result: message: upstream Git server request failed; the push may or may not have been applied, check the branch before retrying new_sha: "" old_sha: "" status: internal success: false target_branch: "" schema: $ref: "#/components/schemas/CommitWriteResponse" description: A storage node, the upstream Git server or GitHub failed or could not be reached. When the push request to the upstream failed or got a server error, the write may have been applied; check the branch before retrying. `result.status` is `failed` when GitHub answers the push with a server error, and `commit` is the commit that the write tried to set. `result.status` is `internal` and `commit` is `null` when the push request fails, or when GitHub answers with a server error or cannot be reached while the gateway gets its GitHub token. `result.message` explains the failure. "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 summary: Create Commit from Diff tags: - Commits x-permission-scopes: - git:write x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}/file: get: description: |- Stream a file directly from the repository with byte ranges, ETag validators, and Last-Modified conditionals. Use `ref` to read from a branch, tag, or commit without cloning the repo locally. Scope: `git:read` on the repository. operationId: repos-files-get parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string - description: Repository-relative file path to fetch. example: src/main.js in: query name: path required: true schema: type: string - description: Optional branch, tag, or commit SHA to read from. When omitted, the repository default branch is used. example: v1.0.0 in: query name: ref schema: type: string - description: Whether `ref` should be resolved from the ephemeral namespace. example: true in: query name: ephemeral schema: type: boolean - description: Standard HTTP byte-range header (`bytes=-`). Triggers a `206 Partial Content` response. in: header name: Range schema: type: string - description: "Conditional range request: when the supplied validator matches `ETag` or `Last-Modified`, the server returns `206 Partial Content`; otherwise the full body is returned with `200 OK`." in: header name: If-Range schema: type: string - description: Returns `412 Precondition Failed` when the current `ETag` does not match. in: header name: If-Match schema: type: string - description: Returns `304 Not Modified` when the current `ETag` matches. in: header name: If-None-Match schema: type: string - description: Returns `304 Not Modified` when `Last-Modified` is on or before this date. in: header name: If-Modified-Since schema: type: string - description: Returns `412 Precondition Failed` when `Last-Modified` is after this date. in: header name: If-Unmodified-Since schema: type: string responses: "200": content: application/octet-stream: schema: contentMediaType: application/octet-stream description: Raw file bytes exactly as stored in the Git blob. No transcoding or encoding is applied. format: binary type: string description: File content returned. headers: Accept-Ranges: description: Set to `bytes`; the endpoint accepts byte-range requests via `Range`. schema: type: string Content-Length: description: Full blob size in bytes for 200 responses, or range size for 206 responses. schema: type: string Content-Range: description: Returned for 206 responses; identifies the byte range served. schema: type: string Content-Type: description: Always `application/octet-stream`. schema: type: string ETag: description: Strong validator equal to the quoted blob object SHA. Use with `If-Match` / `If-None-Match`. schema: type: string Last-Modified: description: Committer date of the most recent commit reachable from `ref` that modified `path`. Use with `If-Modified-Since` / `If-Unmodified-Since`. schema: type: string X-Blob-Sha: description: Git blob object SHA of the served file. schema: type: string X-Last-Commit-Sha: description: SHA of the most recent commit reachable from `ref` that modified `path`. schema: type: string "206": content: application/octet-stream: schema: contentMediaType: application/octet-stream description: The requested slice of the raw file bytes. `Content-Range` identifies which bytes were served. format: binary type: string description: Byte range satisfied. Body contains only the requested bytes; `Content-Range` identifies the range. headers: Accept-Ranges: description: Set to `bytes`; the endpoint accepts byte-range requests via `Range`. schema: type: string Content-Length: description: Full blob size in bytes for 200 responses, or range size for 206 responses. schema: type: string Content-Range: description: Returned for 206 responses; identifies the byte range served. schema: type: string Content-Type: description: Always `application/octet-stream`. schema: type: string ETag: description: Strong validator equal to the quoted blob object SHA. Use with `If-Match` / `If-None-Match`. schema: type: string Last-Modified: description: Committer date of the most recent commit reachable from `ref` that modified `path`. Use with `If-Modified-Since` / `If-Unmodified-Since`. schema: type: string X-Blob-Sha: description: Git blob object SHA of the served file. schema: type: string X-Last-Commit-Sha: description: SHA of the most recent commit reachable from `ref` that modified `path`. schema: type: string "304": description: Cached representation still valid. Returned when `If-None-Match` matches the current `ETag` or `If-Modified-Since` is on or after `Last-Modified`. Body is empty. headers: ETag: description: Strong validator equal to the quoted blob object SHA. Use with `If-Match` / `If-None-Match`. schema: type: string Last-Modified: description: Committer date of the most recent commit reachable from `ref` that modified `path`. Use with `If-Modified-Since` / `If-Unmodified-Since`. schema: type: string X-Blob-Sha: description: Git blob object SHA of the served file. schema: type: string X-Last-Commit-Sha: description: SHA of the most recent commit reachable from `ref` that modified `path`. schema: type: string "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: Conflict "412": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" description: "Precondition from `If-Match` or `If-Unmodified-Since` failed: the resource has changed since the validator the client supplied." "416": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" description: Requested byte range is outside the blob size. "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:read summary: Get File tags: - Files x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable head: description: |- Return file metadata headers for a repository file without streaming the file body. Supports byte ranges, ETag validators, and Last-Modified conditionals. Use `ref` to inspect a branch, tag, or commit without cloning the repo locally. Scope: `git:read` on the repository. operationId: repos-files-metadata-get parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string - description: Repository-relative file path to fetch. example: src/main.js in: query name: path required: true schema: type: string - description: Optional branch, tag, or commit SHA to read from. When omitted, the repository default branch is used. example: v1.0.0 in: query name: ref schema: type: string - description: Whether `ref` should be resolved from the ephemeral namespace. example: true in: query name: ephemeral schema: type: boolean - description: Standard HTTP byte-range header (`bytes=-`). Triggers a `206 Partial Content` response. in: header name: Range schema: type: string - description: "Conditional range request: when the supplied validator matches `ETag` or `Last-Modified`, the server returns `206 Partial Content`; otherwise the full body is returned with `200 OK`." in: header name: If-Range schema: type: string - description: Returns `412 Precondition Failed` when the current `ETag` does not match. in: header name: If-Match schema: type: string - description: Returns `304 Not Modified` when the current `ETag` matches. in: header name: If-None-Match schema: type: string - description: Returns `304 Not Modified` when `Last-Modified` is on or before this date. in: header name: If-Modified-Since schema: type: string - description: Returns `412 Precondition Failed` when `Last-Modified` is after this date. in: header name: If-Unmodified-Since schema: type: string responses: "200": description: File metadata headers returned. Body is empty. headers: Accept-Ranges: description: Set to `bytes`; the endpoint accepts byte-range requests via `Range`. schema: type: string Content-Length: description: Full blob size in bytes for 200 responses, or range size for 206 responses. schema: type: string Content-Range: description: Returned for 206 responses; identifies the byte range served. schema: type: string Content-Type: description: Always `application/octet-stream`. schema: type: string ETag: description: Strong validator equal to the quoted blob object SHA. Use with `If-Match` / `If-None-Match`. schema: type: string Last-Modified: description: Committer date of the most recent commit reachable from `ref` that modified `path`. Use with `If-Modified-Since` / `If-Unmodified-Since`. schema: type: string X-Blob-Sha: description: Git blob object SHA of the served file. schema: type: string X-Last-Commit-Sha: description: SHA of the most recent commit reachable from `ref` that modified `path`. schema: type: string "206": description: Byte range satisfied. Body is empty; `Content-Range` identifies the range. headers: Accept-Ranges: description: Set to `bytes`; the endpoint accepts byte-range requests via `Range`. schema: type: string Content-Length: description: Full blob size in bytes for 200 responses, or range size for 206 responses. schema: type: string Content-Range: description: Returned for 206 responses; identifies the byte range served. schema: type: string Content-Type: description: Always `application/octet-stream`. schema: type: string ETag: description: Strong validator equal to the quoted blob object SHA. Use with `If-Match` / `If-None-Match`. schema: type: string Last-Modified: description: Committer date of the most recent commit reachable from `ref` that modified `path`. Use with `If-Modified-Since` / `If-Unmodified-Since`. schema: type: string X-Blob-Sha: description: Git blob object SHA of the served file. schema: type: string X-Last-Commit-Sha: description: SHA of the most recent commit reachable from `ref` that modified `path`. schema: type: string "304": description: Cached representation still valid. Returned when `If-None-Match` matches the current `ETag` or `If-Modified-Since` is on or after `Last-Modified`. Body is empty. headers: ETag: description: Strong validator equal to the quoted blob object SHA. Use with `If-Match` / `If-None-Match`. schema: type: string Last-Modified: description: Committer date of the most recent commit reachable from `ref` that modified `path`. Use with `If-Modified-Since` / `If-Unmodified-Since`. schema: type: string X-Blob-Sha: description: Git blob object SHA of the served file. schema: type: string X-Last-Commit-Sha: description: SHA of the most recent commit reachable from `ref` that modified `path`. schema: type: string "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: Conflict "412": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" description: "Precondition from `If-Match` or `If-Unmodified-Since` failed: the resource has changed since the validator the client supplied." "416": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" description: Requested byte range is outside the blob size. "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:read summary: Get File Headers tags: - Files x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}/files: get: description: |- List files or direct child entries at a branch, tag, or commit without cloning the repository. Each entry includes its path, Git mode, and derived type (`blob`, `tree`, `symlink`, or `submodule`). Trees no longer carry a trailing `/`; branch on `type` instead. Scope: `git:read` on the repository. operationId: repos-files-list parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string - description: Optional branch, tag, or commit SHA to list from. When omitted, the repository default branch is used. example: main in: query name: ref schema: type: string - description: Optional repository-relative subtree to list. Empty means the repository root. example: docs in: query name: path schema: type: string - description: When true, include descendants recursively. When false, only direct children are returned. Defaults to true. example: false in: query name: recursive schema: default: true type: boolean - description: Pagination cursor returned by a previous `list_files` response. example: docs/guide.md in: query name: cursor schema: type: string - description: Maximum number of paths to return. A call with no `limit` and no `cursor` returns every path in one response, with `has_more` false. A `limit` of 0 is the same as no `limit`. A call with a `cursor` and no `limit` returns up to 1000 paths. example: 1000 in: query name: limit schema: maximum: 5000 minimum: 0 type: integer - description: Whether `ref` should be resolved from the ephemeral namespace. example: true in: query name: ephemeral schema: type: boolean responses: "200": content: application/json: example: entries: - mode: "100644" path: src/main.go type: blob has_more: true next_cursor: MTcwNzU3MzQ1MTAwMDAwMDAwMHxyZXBvXzlhNGMyMWY paths: - README.md ref: main schema: $ref: "#/components/schemas/ReposFilesListResponse" description: Tree entries for the resolved revision. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: List Files tags: - Files x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}/files/metadata: get: description: |- Return a recursive file tree together with per-file commit metadata in one request. Each file also includes a derived `type` field for symmetry with `/files`. The server reads the last commit of each file under `path`, also when the call sends a `limit` or a `cursor`. When those files have more than 50,000 distinct last commits, the call fails with a 429 response, and a retry gets the same response. To list such a tree, send a narrower `path`. Scope: `git:read` on the repository. operationId: repos-files-metadata-list parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string - description: Optional branch, tag, or commit SHA to list from. When omitted, the repository default branch is used. example: main in: query name: ref schema: type: string - description: Optional repository-relative subtree to list recursively. Empty means the repository root. example: docs in: query name: path schema: type: string - description: Accepted for API symmetry. Metadata listings are recursive regardless of this flag. example: true in: query name: recursive schema: type: boolean - description: Pagination cursor returned by a previous `list_files_with_metadata` response. example: docs/guide.md in: query name: cursor schema: type: string - description: Maximum number of files to return. A call with no `limit` and no `cursor` returns every file in one response, with `has_more` false. A `limit` of 0 is the same as no `limit`. A call with a `cursor` and no `limit` returns up to 200 files. example: 200 in: query name: limit schema: maximum: 1000 minimum: 0 type: integer - description: Whether `ref` should be resolved from the ephemeral namespace. example: true in: query name: ephemeral schema: type: boolean responses: "200": content: application/json: example: files: - last_commit_sha: a1b2c3d4e5f6 mode: "100644" path: README.md size: 2048 type: blob has_more: true next_cursor: MTcwNzU3MzQ1MTAwMDAwMDAwMHxyZXBvXzlhNGMyMWY ref: main schema: $ref: "#/components/schemas/ReposFilesMetadataListResponse" description: The repository tree plus deduplicated commit metadata for the latest change touching each file. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: List Files with Metadata tags: - Files x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}/git-credentials: post: description: |- Create a stored HTTPS credential for a repository configured with a generic Git upstream. Scope: `repo:write` on the repository. operationId: repos-gitCredentials-create parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string requestBody: content: application/json: example: password: glpat_xxxxxxxxxxxx username: oauth2 schema: $ref: "#/components/schemas/ReposGitCredentialsCreateRequest" description: Store HTTPS credentials for a generic Git upstream such as GitLab, Bitbucket, Gitea, Forgejo, Codeberg, or SourceHut. required: true responses: "201": content: application/json: example: created_at: "2026-03-12T15:04:05Z" id: ggc_1234567890abcdef schema: $ref: "#/components/schemas/GitCredential" description: Credential created successfully. "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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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: - repo:write summary: Create Git Credential tags: - Repositories x-permission-scopes: - repo:write x-request-validation-profile: create_generic_git_credential_by_path x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}/git-credentials/{git_credential_id}: delete: description: |- Delete a stored HTTPS credential for a generic Git upstream. Scope: `repo:write` on the repository. operationId: repos-gitCredentials-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: Credential identifier. example: cred_01hs8z6j9m6v2m3v0x7g1h5n8q in: path name: git_credential_id required: true schema: type: string responses: "204": description: Credential deleted successfully. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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: - repo:write summary: Delete Git Credential tags: - Repositories x-permission-scopes: - repo:write x-requires-repo-scope: true x-stability: stable put: description: |- Update a stored HTTPS credential for a generic Git upstream. Scope: `repo:write` on the repository. operationId: repos-gitCredentials-update parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string - description: Credential identifier. example: cred_01hs8z6j9m6v2m3v0x7g1h5n8q in: path name: git_credential_id required: true schema: type: string requestBody: content: application/json: example: password: glpat_rotated_token username: oauth2 schema: $ref: "#/components/schemas/ReposGitCredentialsUpdateRequest" description: Rotate or replace an existing generic Git credential. required: true responses: "200": content: application/json: example: created_at: "2026-03-12T15:04:05Z" id: ggc_1234567890abcdef schema: $ref: "#/components/schemas/GitCredential" description: Credential updated successfully. "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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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: - repo:write summary: Update Git Credential tags: - Repositories x-permission-scopes: - repo:write x-request-validation-profile: update_generic_git_credential_by_path x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}/grep: post: description: |- Search a repository without cloning it. Results are paginated and can include surrounding context lines so downstream tools only fetch the relevant slices. Scope: `git:read` on the repository. operationId: repos-grep parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string requestBody: content: application/json: example: context: after: 1 before: 0 pagination: limit: 50 query: case_sensitive: true pattern: ephemeral branches ref: main schema: $ref: "#/components/schemas/ReposGrepRequest" description: Search repository contents by pattern. Optional file filters, context lines, and pagination let you retrieve only the relevant slices for agents and tools. required: true responses: "200": content: application/json: example: has_more: true incomplete_results: false matches: - path: app/blog/markdown/ephemeral-branches.md query: case_sensitive: true pattern: ephemeral branches repo: commit: b003fc78805954584e1ee364a4ad39d7c79e819a ref: main schema: $ref: "#/components/schemas/ReposGrepResponse" description: Search results for the requested pattern. headers: X-Cache: description: Indicates grep cache status (`HIT` or `MISS`). schema: type: string "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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: Grep tags: - Files x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}/merge: post: description: |- Merge changes between branches without cloning the repository or shelling out to Git. This endpoint also supports promoting work from ephemeral branches into long-lived branches such as `main`. Set `expected_source_sha` to merge the exact source commit that a preview returned, even if the source branch advances. Omit `expected_target_sha` to merge into the current target tip and allow the gateway to retry stale target/repository movement internally; set `expected_target_sha` to require a strict target-tip precondition. GitHub-backed public targets currently do not use automatic retry. Scope: `git:write` on the repository. operationId: repos-merge parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string requestBody: content: application/json: example: author: email: review@example.com name: Review Bot commit_message: Merge feature/preview committer: email: review@example.com name: Review Bot expected_source_sha: 9eb378bdb5bf1944f6ba0bd5a2c4df3ce32f4df1 expected_target_sha: c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 source_is_ephemeral: true source_ref: feature/preview squash: false strategy: merge target_branch: main schema: $ref: "#/components/schemas/ReposMergeRequest" description: "Merge a source branch into a target branch using a merge commit, fast-forward only, or fast-forward preferred behaviour. Source and target can live in the default or ephemeral namespace. Set expected_source_sha to merge the source commit that a preview returned: the merge uses that commit, and fails if source_ref no longer contains it. When expected_target_sha is omitted, the gateway may retry stale target updates internally while keeping the originally resolved source commit pinned. Automatic stale-target retry is disabled for GitHub-backed public targets." required: true responses: "200": content: application/json: example: commit_sha: 41f0d5c6cc5f4d0fb4a3af2de27ccf9a80ab3b84 merge_base_sha: a2d127e6a4d54bb7390de828a99e36411f0c84df promoted_commits: 3 result: merged source: ephemeral: true ref: feature/preview sha: 9eb378bdb5bf1944f6ba0bd5a2c4df3ce32f4df1 target: branch: main new_sha: 41f0d5c6cc5f4d0fb4a3af2de27ccf9a80ab3b84 old_sha: c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 tree_sha: b9532c5d5be50d88e2f45d7c229566b2f1f99731 schema: $ref: "#/components/schemas/ReposMergeResponse" description: Merge result, including the source and target commit state after the operation. "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: example: conflict_type: merge_conflict error: merge conflict schema: $ref: "#/components/schemas/MergeConflict" application/problem+json: example: type: about:blank title: Conflict status: 409 detail: "source branch moved: the source branch does not contain commit 9eb378bdb5bf1944f6ba0bd5a2c4df3ce32f4df1" code: ref_guard_failed error: "source branch moved: the source branch does not contain commit 9eb378bdb5bf1944f6ba0bd5a2c4df3ce32f4df1" guard: expected_source_sha current_sha: c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 schema: $ref: "#/components/schemas/ProblemDetails" description: "The merge could not be completed. An `application/json` body reports file-level conflicts, or an automatic stale-target retry that could not absorb concurrent target/repository movement. Inspect conflict_type to distinguish merge_conflict, target_moved, and repo_changed. A problem body reports any other conflict. A failed guard has the code `ref_guard_failed`: the target no longer matches `expected_target_sha`, or the source branch no longer contains `expected_source_sha`. Its body is a `RefGuardProblemDetails`: `guard` names the guard, and `current_sha` is the tip of the guarded branch, or 40 zeros when the source branch does not exist." "412": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" description: "`412` has more than one cause. Storage returns `precondition_failed` for a write-specific reason, such as a merge with no common ancestor between source and target, a merge target that moved off a fast-forward under the `ff_only` strategy, or a branch creation whose target cannot be fast-forwarded. A repository with a GitHub upstream also gets `412` when the write cannot reach GitHub: the code is `github_app_not_configured` when the GitHub App has no usable private key, `github_repository_inaccessible` when GitHub does not give the App access to the repository, and `precondition_failed` when GitHub refuses the push for another reason, such as an archived repository. `detail` explains the failure." "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 "502": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" description: A storage node, the upstream Git server or GitHub failed or could not be reached. When the push request to the upstream failed or got a server error, the write may have been applied; check the branch before retrying. "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 summary: Merge Branch tags: - Branches x-permission-scopes: - git:write x-request-validation-profile: merge_branch x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}/merge/preview: get: description: |- Preview merge conflicts without creating commits, updating refs, or touching a working tree. When requested, conflict content is rendered from Git objects produced in request-local scratch storage. Scope: `git:read` on the repository. operationId: repos-previewMerge parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string - description: Source branch to merge from. example: feature/preview in: query name: source_branch required: true schema: type: string - description: Destination branch to preview merging into. example: main in: query name: target_branch required: true schema: type: string - description: Whether `source_branch` should be resolved from the ephemeral namespace. in: query name: source_is_ephemeral schema: type: boolean - description: Whether `target_branch` should be resolved from the ephemeral namespace. in: query name: target_is_ephemeral schema: type: boolean - description: When true, include bounded conflict content in the response. example: true in: query name: include_content schema: type: boolean responses: "200": content: application/json: example: conflicts: - base: binary: false oid: "1111111111111111111111111111111111111111" truncated: false ours: binary: false oid: "1111111111111111111111111111111111111111" truncated: false path: docs/conflict.txt result: binary: false oid: "1111111111111111111111111111111111111111" truncated: false theirs: binary: false oid: "1111111111111111111111111111111111111111" truncated: false filtered_conflicts: - path: src/app.ts reason: max_conflict_files_exceeded merge_base_sha: a2d127e6a4d54bb7390de828a99e36411f0c84df result: merge_commit source_branch: feature/preview source_tip_sha: 9eb378bdb5bf1944f6ba0bd5a2c4df3ce32f4df1 status: conflicted target_branch: main target_tip_sha: c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 schema: $ref: "#/components/schemas/ReposPreviewMergeResponse" description: Merge preview result. Conflicted previews return HTTP 200 with `status=conflicted`; request and storage failures use normal HTTP errors. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: Preview Merge tags: - Branches x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}/notes: delete: 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 summary: Delete Note tags: - Notes x-permission-scopes: - git:write x-requires-repo-scope: true x-stability: stable get: description: |- Read the Git note attached to a commit or other Git object SHA. Notes let you store review status, handoff details, or other context without changing repository contents. Scope: `git:read` on the repository. operationId: repos-notes-get 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 fetched. A full object SHA today. Provide object_ref or the deprecated sha. example: b003fc78805954584e1ee364a4ad39d7c79e819a in: query name: object_ref schema: type: string - deprecated: true description: "Deprecated: use object_ref instead. Git object SHA whose note should be fetched." in: query name: sha schema: type: string - description: Optional notes ref to read 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. Provide notes_ref or the deprecated ref. example: refs/notes/commits in: query name: notes_ref schema: type: string - deprecated: true description: "Deprecated: use notes_ref instead. Optional notes ref to read from. Defaults to refs/notes/commits." in: query name: ref schema: type: string responses: "200": content: application/json: example: note: Reviewed. Ready for production. ref_sha: 0c8b5bb9d550d58fcfd651a4fdce8024ef7f1492 sha: b003fc78805954584e1ee364a4ad39d7c79e819a schema: $ref: "#/components/schemas/ReposNotesGetResponse" description: The note stored for the requested Git object. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: Get Note tags: - Notes x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable post: description: |- 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. operationId: repos-notes-create parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string requestBody: content: application/json: example: author: email: review@example.com name: Review Bot note: Reviewed. Ready for production. notes_ref: refs/notes/commits object_ref: b003fc78805954584e1ee364a4ad39d7c79e819a examples: create_note: description: Create a new note on a commit. summary: Create note value: author: email: review@example.com name: Review Bot note: Reviewed. Ready for production. object_ref: b003fc78805954584e1ee364a4ad39d7c79e819a schema: $ref: "#/components/schemas/ReposNotesCreateRequest" description: "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." required: true 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 update applied to 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 summary: Create Note tags: - Notes x-permission-scopes: - git:write x-pierre-operation: mapping: add: repos.notes.create append: repos.notes.append propertyName: action x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}/notes/append: post: description: |- Add text to the note on a Git object, or create the note if the object has none. A retry after a success adds the text again. To make a retry safe, set `expected_notes_ref_sha` to the notes ref SHA that you read before the first request: a retry then fails with 409 and adds nothing. Scope: `git:write` on the repository. operationId: repos-notes-append parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string requestBody: content: application/json: example: author: email: review@example.com name: Review Bot note: Deployment complete. notes_ref: refs/notes/commits object_ref: b003fc78805954584e1ee364a4ad39d7c79e819a examples: append_note: description: Add text to the note on a commit. summary: Append note value: author: email: review@example.com name: Review Bot note: Deployment complete. object_ref: b003fc78805954584e1ee364a4ad39d7c79e819a schema: $ref: "#/components/schemas/ReposNotesAppendRequest" description: Add text to the Git note of the supplied `object_ref`. If the object has no note, the request creates it. 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/. required: true 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 update applied to 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 summary: Append Note tags: - Notes x-permission-scopes: - git:write x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}/notes/refs: get: description: |- List Git notes refs under a notes ref prefix with cursor pagination. Use this to discover custom notes namespaces before reading individual notes. Scope: `git:read` on the repository. operationId: repos-notes-refs-list parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string - description: Notes ref prefix to enumerate. A bare prefix like reviews is placed under refs/notes/; a fully-qualified refs/notes/* prefix is also accepted. Defaults to refs/notes/. example: reviews/ in: query name: prefix schema: type: string - description: Pagination cursor returned by a previous `list_notes_refs` response. example: refs/notes/reviews/session-b in: query name: cursor schema: type: string - description: Maximum number of notes refs to return. Defaults to 20. example: 20 in: query name: limit schema: default: 20 type: integer responses: "200": content: application/json: example: has_more: true next_cursor: MTcwNzU3MzQ1MTAwMDAwMDAwMHxyZXBvXzlhNGMyMWY prefix: refs/notes/reviews/ refs: - cursor: refs/notes/reviews/session-a ref: refs/notes/reviews/session-a sha: a1b2c3d4e5f6 schema: $ref: "#/components/schemas/ReposNotesRefsListResponse" description: Notes refs in lexical order. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: List Notes Refs tags: - Notes x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}/pull-upstream: post: deprecated: true description: |- Trigger a sync from the configured upstream of the repository. This only works for repositories that have an `upstream`. `POST /api/repos/{repo_name}/upstream/pull` replaces this endpoint. It takes the same request body and returns the same response. Scope: `git:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/upstream/pull` instead. operationId: pull_upstream parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/ReposUpstreamPullRequest" description: "Deprecated: send no body. Its fields have no effect: a pull syncs every branch and tag of the upstream." responses: "202": content: application/json: example: message: Repository sync initiated successfully schema: $ref: "#/components/schemas/ReposUpstreamPullResponse" description: Sync trigger accepted. The repository sync runs asynchronously. "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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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 summary: Pull Upstream tags: - Repositories x-deprecation-message: Use `/api/repos/{repo_name}/upstream/pull` instead. x-permission-scopes: - git:write x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}/reset-commits: post: description: |- Create a new commit that resets a branch back to a specific commit SHA while preserving normal Git history. This is an alias of `restore-commit` and is served by the same handler; prefer `restore-commit` for new integrations. A successful reset responds with `201 Created`. Ref-level outcomes are reported in `result.status` and `result.success`, not by the status code alone, and failures raised by the restore itself come back in that same restore-result body. The problem-details schemas below describe gateway-level rejections such as `401`, `403` and `429`. Scope: `git:write` on the repository. operationId: reset_commits parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string requestBody: content: application/x-ndjson: example: | {"metadata":{"target_branch":"main","base_ref":"abc123def4567890abc123def4567890abc123de","expected_target_sha":"0123456789abcdef0123456789abcdef01234567","commit_message":"Reset branch","author":{"name":"Docs Bot","email":"docs@example.com"}}} schema: contentSchema: maxItems: 1 minItems: 1 prefixItems: - additionalProperties: false properties: metadata: $ref: "#/components/schemas/ReposCommitsRestoreRequest" required: - metadata type: object type: array description: NDJSON stream containing one `metadata` object. type: string description: Send a single NDJSON metadata line describing the branch to restore and the commit SHA to restore it to. The handler requires this line and rejects an empty body with `400`, even though the published contract leaves it optional. responses: "200": content: application/json: schema: $ref: "#/components/schemas/ReposCommitsRestoreResponse" description: Documented for backwards compatibility with clients written against the original `reset-commits` contract. Successful resets return `201 Created`; see the `201` response. "201": content: application/json: schema: $ref: "#/components/schemas/ReposCommitsRestoreResponse" description: Restore commit created and the branch reset. This is the status a successful reset returns. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: base_ref (d34db33fd34db33fd34db33fd34db33fd34db33f) does not match current head c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 code: ref_guard_failed error: base_ref (d34db33fd34db33fd34db33fd34db33fd34db33f) does not match current head c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 guard: expected_target_sha current_sha: c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 commit: null result: target_branch: main branch: main old_sha: c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 new_sha: "" success: false status: conflict message: base_ref (d34db33fd34db33fd34db33fd34db33fd34db33f) does not match current head c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 schema: $ref: "#/components/schemas/RestoreCommitRefGuardProblemDetails" description: "Conflict. When `expected_target_sha` is not the tip of the branch, the body is `application/problem+json` with the code `ref_guard_failed`: `guard` names the guard, and `current_sha` is the tip of the branch, which `result.old_sha` repeats. The body keeps the members of the failure body, and `result.status` is `conflict`." "412": content: application/json: example: commit: null result: message: branch already matches target commit new_sha: "" old_sha: "" status: precondition_failed success: false target_branch: "" schema: $ref: "#/components/schemas/ReposCommitsRestoreResponse" description: "Storage rejected the restore because the branch cannot move as requested: the branch already points at `base_ref`, the restore would produce no change, or `base_ref` is not an ancestor of the current tip. The body carries the restore result with `result.status` set to `precondition_failed`. A repository with a GitHub upstream also gets `412` when the write cannot reach GitHub: the GitHub App has no usable private key, GitHub does not give the App access to the repository, or GitHub refuses the push with `401`, `403` or `404`. Then `result.status` is `failed` and `result.message` explains the failure." "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 "502": content: application/json: example: commit: null result: message: upstream Git server request failed; the push may or may not have been applied, check the branch before retrying new_sha: "" old_sha: "" status: internal success: false target_branch: "" schema: $ref: "#/components/schemas/ReposCommitsRestoreResponse" description: A storage node, the upstream Git server or GitHub failed or could not be reached. When the push request to the upstream failed or got a server error, the write may have been applied; check the branch before retrying. `result.status` is `failed` when GitHub answers the push with a server error, and `commit` is the commit that the write tried to set. `result.status` is `internal` and `commit` is `null` when the push request fails, or when GitHub answers with a server error or cannot be reached while the gateway gets its GitHub token. `result.message` explains the failure. "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 summary: Reset Branch to Commit tags: - Commits x-permission-scopes: - git:write x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}/restore-commit: post: description: |- Create a new commit that resets a branch back to a specific commit SHA while preserving normal Git history. Ref-level outcomes are reported in `result.status` and `result.success`, not by the status code alone, and failures raised by the restore itself come back in that same restore-result body. The problem-details schemas below describe gateway-level rejections such as `401`, `403` and `429`. Scope: `git:write` on the repository. operationId: repos-commits-restore parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string requestBody: content: application/x-ndjson: example: | {"metadata":{"target_branch":"main","base_ref":"abc123def4567890abc123def4567890abc123de","expected_target_sha":"0123456789abcdef0123456789abcdef01234567","commit_message":"Reset branch","author":{"name":"Docs Bot","email":"docs@example.com"}}} schema: contentSchema: maxItems: 1 minItems: 1 prefixItems: - additionalProperties: false properties: metadata: $ref: "#/components/schemas/ReposCommitsRestoreRequest" required: - metadata type: object type: array description: NDJSON stream containing one `metadata` object. type: string description: Send a single NDJSON metadata line describing the branch to restore and the commit SHA to restore it to. required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/ReposCommitsRestoreResponse" description: Restore commit created successfully. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: base_ref (d34db33fd34db33fd34db33fd34db33fd34db33f) does not match current head c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 code: ref_guard_failed error: base_ref (d34db33fd34db33fd34db33fd34db33fd34db33f) does not match current head c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 guard: expected_target_sha current_sha: c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 commit: null result: target_branch: main branch: main old_sha: c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 new_sha: "" success: false status: conflict message: base_ref (d34db33fd34db33fd34db33fd34db33fd34db33f) does not match current head c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 schema: $ref: "#/components/schemas/RestoreCommitRefGuardProblemDetails" description: "Conflict. When `expected_target_sha` is not the tip of the branch, the body is `application/problem+json` with the code `ref_guard_failed`: `guard` names the guard, and `current_sha` is the tip of the branch, which `result.old_sha` repeats. The body keeps the members of the failure body, and `result.status` is `conflict`." "412": content: application/json: example: commit: null result: message: branch already matches target commit new_sha: "" old_sha: "" status: precondition_failed success: false target_branch: "" schema: $ref: "#/components/schemas/ReposCommitsRestoreResponse" description: "Storage rejected the restore because the branch cannot move as requested: the branch already points at `base_ref`, the restore would produce no change, or `base_ref` is not an ancestor of the current tip. The body carries the restore result with `result.status` set to `precondition_failed`. A repository with a GitHub upstream also gets `412` when the write cannot reach GitHub: the GitHub App has no usable private key, GitHub does not give the App access to the repository, or GitHub refuses the push with `401`, `403` or `404`. Then `result.status` is `failed` and `result.message` explains the failure." "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 "502": content: application/json: example: commit: null result: message: upstream Git server request failed; the push may or may not have been applied, check the branch before retrying new_sha: "" old_sha: "" status: internal success: false target_branch: "" schema: $ref: "#/components/schemas/ReposCommitsRestoreResponse" description: A storage node, the upstream Git server or GitHub failed or could not be reached. When the push request to the upstream failed or got a server error, the write may have been applied; check the branch before retrying. `result.status` is `failed` when GitHub answers the push with a server error, and `commit` is the commit that the write tried to set. `result.status` is `internal` and `commit` is `null` when the push request fails, or when GitHub answers with a server error or cannot be reached while the gateway gets its GitHub token. `result.message` explains the failure. "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 summary: Restore Commit tags: - Commits x-permission-scopes: - git:write x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}/tag: get: description: |- Get one tag by its exact short name. The response returns the dereferenced commit SHA and omits internal fields. Scope: `git:read` on the repository. operationId: repos-tags-get parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string - description: Exact short tag name. example: v1.0.0 in: query name: name required: true schema: type: string responses: "200": content: application/json: example: tag: name: v1.0.0 sha: a1b2c3d4e5f6 schema: $ref: "#/components/schemas/ReposTagsGetResponse" description: The tag with the requested name. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: Get Tag tags: - Tags x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}/tags: get: description: |- List tags in lexical order with cursor pagination. The returned `sha` is the dereferenced commit SHA, even for annotated tags. Scope: `git:read` on the repository. operationId: repos-tags-list parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string - description: Pagination cursor returned by a previous `list_tags` response. example: t_def456 in: query name: cursor schema: type: string - description: Maximum number of tags to return. Defaults to 20. example: 20 in: query name: limit schema: default: 20 type: integer responses: "200": content: application/json: example: has_more: true next_cursor: MTcwNzU3MzQ1MTAwMDAwMDAwMHxyZXBvXzlhNGMyMWY tags: - cursor: t_abc123 name: v1.0.0 sha: a1b2c3d4e5f6 schema: $ref: "#/components/schemas/ReposTagsListResponse" description: Repository tags in lexical order. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: List Tags tags: - Tags x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable post: description: |- Create a lightweight tag pointing to a specific commit. Annotated tags are not created through this endpoint. Scope: `git:write` on the repository. operationId: repos-tags-create parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string requestBody: content: application/json: example: name: v1.0.0 ref: main schema: $ref: "#/components/schemas/ReposTagsCreateRequest" description: Create a lightweight tag that points to an exact commit SHA. required: true responses: "200": content: application/json: example: message: tag created name: v1.0.0 sha: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2 schema: $ref: "#/components/schemas/ReposTagsCreateResponse" description: Tag creation result. "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: schema: $ref: "#/components/schemas/ProblemDetails" description: Conflict "412": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" description: "`412` has more than one cause. Storage returns `precondition_failed` for a write-specific reason, such as a merge with no common ancestor between source and target, a merge target that moved off a fast-forward under the `ff_only` strategy, or a branch creation whose target cannot be fast-forwarded. A repository with a GitHub upstream also gets `412` when the write cannot reach GitHub: the code is `github_app_not_configured` when the GitHub App has no usable private key, `github_repository_inaccessible` when GitHub does not give the App access to the repository, and `precondition_failed` when GitHub refuses the push for another reason, such as an archived repository. `detail` explains the failure." "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 "502": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" description: A storage node, the upstream Git server or GitHub failed or could not be reached. When the push request to the upstream failed or got a server error, the write may have been applied; check the branch before retrying. "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 summary: Create Tag tags: - Tags x-permission-scopes: - git:write x-request-validation-profile: create_tag x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}/tags/{tag_name}: delete: description: |- Delete a tag from the repository. The server resolves the stored ref correctly for both lightweight and annotated tags. Scopes: `git:read` and `git:write` on the repository. operationId: repos-tags-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: Tag name. example: v1.0.0 in: path name: tag_name required: true schema: type: string responses: "200": content: application/json: example: message: tag deleted name: v1.0.0 schema: $ref: "#/components/schemas/ReposTagsDeleteResponse" description: Tag deletion result. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: Conflict "412": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" description: "`412` has more than one cause. Storage returns `precondition_failed` for a write-specific reason, such as a merge with no common ancestor between source and target, a merge target that moved off a fast-forward under the `ff_only` strategy, or a branch creation whose target cannot be fast-forwarded. A repository with a GitHub upstream also gets `412` when the write cannot reach GitHub: the code is `github_app_not_configured` when the GitHub App has no usable private key, `github_repository_inaccessible` when GitHub does not give the App access to the repository, and `precondition_failed` when GitHub refuses the push for another reason, such as an archived repository. `detail` explains the failure." "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 "502": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" description: A storage node, the upstream Git server or GitHub failed or could not be reached. When the push request to the upstream failed or got a server error, the write may have been applied; check the branch before retrying. "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:read - git:write summary: Delete Tag tags: - Tags x-permission-scopes: - git:read - git:write x-request-validation-profile: delete_tag_by_path x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}/upstream: delete: description: |- Detach the repository from its configured upstream provider. The operation is idempotent: already-detached repositories return success. Scope: `repo:write` on the repository. operationId: repos-upstream-delete parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string responses: "200": content: application/json: example: message: repository detached schema: $ref: "#/components/schemas/ReposUpstreamDeleteResponse" description: Upstream detach result. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: example: message: repository detached schema: $ref: "#/components/schemas/ReposUpstreamDeleteResponse" description: The detach workflow is already in progress or the sync workflow is missing. "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: - repo:write summary: Delete Upstream tags: - Repositories x-permission-scopes: - repo:write x-requires-repo-scope: true x-stability: stable /api/repos/{repo_name}/upstream/pull: post: description: |- Trigger a sync from the configured upstream of the repository. This only works for repositories that have an `upstream`. Scope: `git:write` on the repository. operationId: repos-upstream-pull parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/ReposUpstreamPullRequest" description: "Deprecated: send no body. Its fields have no effect: a pull syncs every branch and tag of the upstream." responses: "202": content: application/json: example: message: Repository sync initiated successfully schema: $ref: "#/components/schemas/ReposUpstreamPullResponse" description: Sync trigger accepted. The repository sync runs asynchronously. "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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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 summary: Pull Upstream tags: - Repositories x-permission-scopes: - git:write x-requires-repo-scope: true x-stability: stable /api/v1/repo: get: deprecated: true description: |- Fetch the metadata of a repository. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}` instead. operationId: get_repo_legacy responses: "200": content: application/json: example: base_repo: name: Hello-World owner: octocat provider: github created_at: "2024-01-15T10:30:00Z" default_branch: main repo_id: repo_7f2b3d9 repo_name: team/project-alpha upstream: name: Hello-World owner: octocat provider: github url: team/project-alpha schema: $ref: "#/components/schemas/Repository" description: Repository metadata resolved from the JWT `repo` claim. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: Get Repo tags: - Repositories x-deprecation-message: Use `/api/repos/{repo_name}` instead. x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable patch: deprecated: true description: |- Change the default branch of a repository. The gateway reads the current `HEAD` symbolic ref, then repoints it at the requested branch through a transactional compare-and-swap against that value, and finally records the new default branch in the repository row. Branch names are fully qualified for you: `main` is written as the symref target `refs/heads/main`, and a value that already starts with `refs/` is used verbatim. The branch itself is not created by this call. Scope: `repo:write` on the repository. Deprecated: Use `/api/repos/{repo_name}` instead. operationId: update_repo_legacy requestBody: content: application/json: example: default_branch: main schema: $ref: "#/components/schemas/ReposUpdateRequest" description: Repository settings to change. `default_branch` is the only supported field and must be a non-empty branch name. required: true responses: "200": content: application/json: example: default_branch: main id: repo_7f2b3d9 repo_id: repo_7f2b3d9 repo_name: pierre/sdk-documentation url: pierre/sdk-documentation schema: $ref: "#/components/schemas/ReposUpdateResponse" description: Default branch updated. Returns the repository ID, its URL path, and the branch name now recorded as the default. "400": content: application/json: example: code: bad_request detail: default_branch must be a string error: default_branch must be a string invalid_params: - name: default_branch reason: must be a string status: 400 title: Bad Request type: about:blank schema: $ref: "#/components/schemas/ValidationProblemDetails" application/problem+json: example: code: bad_request detail: default_branch must be a string error: default_branch must be a string invalid_params: - name: default_branch reason: must be a string status: 400 title: Bad Request type: about:blank schema: $ref: "#/components/schemas/ValidationProblemDetails" description: The body could not be decoded as JSON, a field was not valid, or `default_branch` was missing or empty. `invalid_params` names each invalid field. "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: No repository matching the JWT `repo` claim exists for this organisation. "409": content: application/json: example: code: conflict detail: default branch was modified concurrently, please retry error: default branch was modified concurrently, please retry instance: /api/repos/my-demo-repository status: 409 title: Conflict type: about:blank schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: example: code: conflict detail: default branch was modified concurrently, please retry error: default branch was modified concurrently, please retry instance: /api/repos/my-demo-repository status: 409 title: Conflict type: about:blank schema: $ref: "#/components/schemas/ProblemDetails" description: "`HEAD` moved between the read and the compare-and-swap, so the update was rejected. Retry the request." "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: The current `HEAD` value could not be read from storage, so no compare-and-swap was attempted and nothing was changed. headers: Retry-After: description: Minimum delay in seconds before retrying. schema: type: string security: - bearerAuth: - repo:write summary: Update Repository Settings tags: - Repositories x-deprecation-message: Use `/api/repos/{repo_name}` instead. x-permission-scopes: - repo:write x-request-validation-profile: update_repo x-requires-repo-scope: true x-stability: stable /api/v1/repos: get: deprecated: true description: |- List repositories for the current organisation with cursor-based pagination. Supply `q` to filter results by a case-insensitive substring match against `repo_name` (for example `pierre/sdk-documentation`), and `prefix` to filter by the start of `repo_name`. When both are set they combine with AND: a repository is returned only when it matches both filters. Scope: `org:read`. Deprecated: Use `/api/repos` instead. operationId: list_repos_legacy parameters: - description: Case-insensitive substring to match against `repo_name`. Trimmed before matching. When `prefix` is also set, both must match (AND) and `q` only matches the part of `repo_name` after the prefix. When omitted or empty after trimming, the full repository list is returned. example: sdk in: query name: q schema: type: string - description: Case-insensitive prefix to match against the start of `repo_name`. For example, `pierre/` matches `pierre/sdk-documentation` and `pierre/example` but not `acme/pierre-tools`. When `q` is also set, both must match (AND) and `q` only matches the part of `repo_name` after the prefix, so `prefix=pierre/&q=sdk` returns `pierre/sdk-documentation` but not `pierre/example`. Trimmed before matching. When omitted or empty after trimming, no prefix filter applies. example: pierre/ in: query name: prefix schema: type: string - description: Pagination cursor from previous response (base64 encoded) example: MTcwNzU3MzQ1MTAwMDAwMDAwMHxyZXBvXzlhNGMyMWY in: query name: cursor schema: type: string - description: Maximum number of repositories to return. Defaults to 20 and is capped at 100. example: 20 in: query name: limit schema: default: 20 maximum: 100 minimum: 1 type: integer responses: "200": content: application/json: example: has_more: true next_cursor: MTcwNzU3MzQ1MTAwMDAwMDAwMHxyZXBvXzlhNGMyMWY repos: - base_repo: name: Hello-World owner: octocat provider: github created_at: "2024-01-15T10:30:00Z" default_branch: main repo_id: repo_7f2b3d9 repo_name: team/project-alpha upstream: name: Hello-World owner: octocat provider: github url: team/project-alpha schema: $ref: "#/components/schemas/ReposListResponse" description: A paginated view of repositories in the organisation. "400": content: application/json: example: code: bad_request detail: invalid cursor error: invalid cursor instance: /api/repos status: 400 title: Bad Request type: about:blank schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: example: code: bad_request detail: invalid cursor error: invalid cursor instance: /api/repos status: 400 title: Bad Request type: about:blank schema: $ref: "#/components/schemas/ProblemDetails" description: The supplied pagination cursor could not be decoded. "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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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: - org:read summary: List Repos tags: - Repositories x-deprecation-message: Use `/api/repos` instead. x-permission-scopes: - org:read x-requires-repo-scope: false x-stability: stable post: deprecated: true description: |- Create a repository. A repository starts empty or from a source. `base_repo` is a one-time copy of a Code Storage repository; `upstream` is a lasting link to an external Git host. A copy takes the history of one commit (`base_repo.ref`, or the source HEAD) into one branch, and keeps no link to its source. A sync keeps its upstream, and the repository can sync from it again. Set at most one of the two. A new empty repository has no branch until its first commit. The first commit creates the branch that it targets, so the default branch exists only after a commit to it. Create is idempotent on the repository name. A new repository returns `201`. When the name already exists, the request returns `200`, and a copy copies nothing. When the name exists with a different upstream, the request returns `409`. The deprecated form of `base_repo`, with `provider` and `operation`, still works. Scope: `repo:write` on the repository. Deprecated: Use `/api/repos` instead. operationId: create_repo_legacy parameters: - deprecated: true description: "Deprecated: use the default_branch body field instead. Default branch for the new repository. When the body also has default_branch, the body value wins." in: query name: default_branch schema: type: string requestBody: content: application/json: example: base_repo: auth: token: SOURCE_REPO_READ_TOKEN name: pierre/sdk-documentation ref: main default_branch: feature-preview repo_name: pierre/docs-copy examples: copy: description: Create an independent repository from one commit of another Code Storage repository. summary: Copy value: base_repo: auth: token: SOURCE_REPO_READ_TOKEN name: pierre/sdk-documentation ref: main default_branch: feature-preview repo_name: pierre/docs-copy empty_repo: description: Create a new repository with an explicit default branch. summary: Empty repository value: default_branch: main repo_name: pierre/my-repo generic_git_sync: description: Mirror a repository from a generic HTTPS Git provider such as GitLab, Bitbucket, Gitea, or Forgejo. summary: Generic HTTPS Git sync value: default_branch: main repo_name: pierre/repo-name upstream: host: git.example.com name: repo-name owner: org-name provider: gitea public_github_sync: description: Mirror a public GitHub repository without a GitHub App installation. summary: Public GitHub sync value: default_branch: main repo_name: pierre/hello-world upstream: access: public name: hello-world owner: octocat provider: github schema: $ref: "#/components/schemas/ReposCreateRequest" description: Create an empty repository, a copy of a Code Storage repository (`base_repo`), or a repository that syncs from an external Git host (`upstream`). responses: "200": content: application/json: example: message: Repository 'pierre/sdk-documentation' already exists repo_name: pierre/sdk-documentation schema: $ref: "#/components/schemas/ReposCreateResponse" description: The repository already existed, and the request created nothing. "201": content: application/json: example: http_url: pierre/sdk-documentation message: Repository 'pierre/sdk-documentation' created repo_id: repo_7f2b3d9 repo_name: pierre/sdk-documentation schema: $ref: "#/components/schemas/ReposCreateResponse" description: The request created the repository. "400": content: application/json: example: code: bad_request detail: base_repo and upstream cannot both be set. Use base_repo to copy a Code Storage repository, or upstream to sync from an external Git host. error: base_repo and upstream cannot both be set. Use base_repo to copy a Code Storage repository, or upstream to sync from an external Git host. instance: /api/repos status: 400 title: Bad Request type: about:blank schema: $ref: "#/components/schemas/ValidationProblemDetails" application/problem+json: example: code: bad_request detail: base_repo and upstream cannot both be set. Use base_repo to copy a Code Storage repository, or upstream to sync from an external Git host. error: base_repo and upstream cannot both be set. Use base_repo to copy a Code Storage repository, or upstream to sync from an external Git host. instance: /api/repos status: 400 title: Bad Request type: about:blank schema: $ref: "#/components/schemas/ValidationProblemDetails" description: The repository name was invalid or did not match the JWT repo claim, the request set both base_repo and upstream, or the source was invalid. `invalid_params` names each invalid field of the body. "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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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: - repo:write summary: Create Repo tags: - Repositories x-deprecation-message: Use `/api/repos` instead. x-permission-scopes: - repo:write x-request-validation-profile: create_repo x-requires-repo-scope: true x-stability: stable /api/v1/repos/archive: post: deprecated: true description: |- Download a repository snapshot without cloning the repo. This is useful for packaging docs, examples, or release artefacts directly from a branch, tag, or commit. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/archive` instead. operationId: archive_legacy requestBody: content: application/json: examples: docs_snapshot: description: Download just the docs tree with a prefixed root folder. summary: Filtered documentation snapshot value: archive: prefix: sdk-docs/ exclude_globs: - "**/drafts/**" include_globs: - docs/** - README.md ref: main schema: $ref: "#/components/schemas/ReposArchiveGetRequest" description: Request a `.tar.gz` snapshot of the repository at a branch, tag, or commit. Include and exclude globs let you shape the archive before it streams back. responses: "200": content: application/gzip: schema: contentMediaType: application/octet-stream description: Gzip-compressed tar archive stream. format: binary type: string description: A streamed `.tar.gz` archive of the resolved revision. headers: Cache-Control: description: Archive downloads are returned with `no-store`. schema: type: string Content-Disposition: description: Attachment filename generated from the repository URL and resolved revision. schema: type: string "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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: Archive tags: - Files x-deprecation-message: Use `/api/repos/{repo_name}/archive` instead. x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable /api/v1/repos/base: delete: deprecated: true description: |- Detach the repository from its configured upstream provider. The operation is idempotent: already-detached repositories return success. `DELETE /api/repos/{repo_name}/upstream` replaces this endpoint. It returns the same responses. Scope: `repo:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/upstream` instead. operationId: unset_base_repo_legacy responses: "200": content: application/json: example: message: repository detached schema: $ref: "#/components/schemas/ReposUpstreamDeleteResponse" description: Upstream detach result. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: example: message: repository detached schema: $ref: "#/components/schemas/ReposUpstreamDeleteResponse" description: The detach workflow is already in progress or the sync workflow is missing. "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: - repo:write summary: Unset Base Repo tags: - Repositories x-deprecation-message: Use `/api/repos/{repo_name}/upstream` instead. x-permission-scopes: - repo:write x-requires-repo-scope: true x-stability: stable /api/v1/repos/blame: get: deprecated: true description: |- Return per-line blame metadata for a file at a branch, tag, or commit. Supports `git blame -L`-style range filters and rename/copy detection for callers building IDE blame views or audit tooling. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/blame` instead. operationId: blame_legacy parameters: - description: Repository-relative file path to blame. example: src/main.go in: query name: path required: true schema: type: string - description: Optional branch, tag, or commit SHA to blame at. When omitted, the repository default branch is used. example: main in: query name: ref schema: type: string - description: Whether `ref` should be resolved from the ephemeral namespace. in: query name: ephemeral schema: type: boolean - description: "Optional `git blame -L`-style range spec. May be repeated to blame multiple regions (max 16). Each value is one `-L` argument: e.g. `10,20`, `10,+5`, `/getUser/,/^}/`, `/getUser/,+30`, `10,`, `,20`, `10`, `:^func .*Foo`, `:funcname`." example: - 10,20 in: query name: range schema: items: type: string type: array - description: Follow the file across renames and copies. in: query name: detect_moves schema: type: boolean responses: "200": content: application/json: example: commit_sha: b003fc78805954584e1ee364a4ad39d7c79e819a lines: - author_email: jane@example.com author_name: Jane Doe author_time: "2024-01-15T14:32:18Z" commit_sha: b003fc78805954584e1ee364a4ad39d7c79e819a committer_email: jane@example.com committer_name: Jane Doe committer_time: "2024-01-15T14:32:18Z" line_number: 42 original_line_number: 40 original_path: src/main.go previous_commit_sha: a4d39d7c79e819ab003fc78805954584e1ee36 summary: "fix: resolve scrolling issue in dashboard" path: src/main.go ref: main schema: $ref: "#/components/schemas/ReposBlameGetResponse" description: Per-line blame for the resolved file revision. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: Blame tags: - Files x-deprecation-message: Use `/api/repos/{repo_name}/blame` instead. x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable /api/v1/repos/branches: delete: deprecated: true description: |- Delete a branch from the repository. Name the branch with the `target_branch` and `ephemeral` query parameters. The server resolves the current branch tip before deleting, so the caller does not need the branch SHA. The default branch is protected and cannot be deleted through this endpoint. Scope: `git:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/branches` instead. operationId: delete_branch_legacy parameters: - description: Exact short name of the branch to delete. Must not start with refs/. Required unless the deprecated body names the branch. example: feature/old-onboarding in: query name: target_branch schema: type: string - description: When true, delete the branch from the ephemeral namespace instead of the default namespace. in: query name: ephemeral schema: type: boolean requestBody: content: application/json: example: ephemeral: false name: feature/old-onboarding target_branch: feature/old-onboarding schema: $ref: "#/components/schemas/ReposBranchesDeleteRequest" description: "Deprecated: send the `target_branch` and `ephemeral` query parameters, and no body. A query parameter wins over its body field." responses: "200": content: application/json: example: ephemeral: false message: branch deleted name: feature/old-onboarding target_branch: feature/old-onboarding schema: $ref: "#/components/schemas/ReposBranchesDeleteResponse" description: Branch deletion result. "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: example: code: conflict detail: cannot delete the default branch error: cannot delete the default branch instance: /api/repos/dotfiles/branches status: 409 title: Conflict type: about:blank schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: example: code: conflict detail: cannot delete the default branch error: cannot delete the default branch instance: /api/repos/dotfiles/branches status: 409 title: Conflict type: about:blank schema: $ref: "#/components/schemas/ProblemDetails" description: The branch could not be deleted because it is the repository default branch. "412": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" description: "`412` has more than one cause. Storage returns `precondition_failed` for a write-specific reason, such as a merge with no common ancestor between source and target, a merge target that moved off a fast-forward under the `ff_only` strategy, or a branch creation whose target cannot be fast-forwarded. A repository with a GitHub upstream also gets `412` when the write cannot reach GitHub: the code is `github_app_not_configured` when the GitHub App has no usable private key, `github_repository_inaccessible` when GitHub does not give the App access to the repository, and `precondition_failed` when GitHub refuses the push for another reason, such as an archived repository. `detail` explains the failure." "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 "502": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" description: A storage node, the upstream Git server or GitHub failed or could not be reached. When the push request to the upstream failed or got a server error, the write may have been applied; check the branch before retrying. "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 summary: Delete Branch tags: - Branches x-deprecation-message: Use `/api/repos/{repo_name}/branches` instead. x-permission-scopes: - git:write x-requires-repo-scope: true x-stability: stable get: deprecated: true description: |- List branches in the repository with cursor pagination. Use this to build branch selectors, review tools, or sync jobs without shelling out to Git. A new empty repository has no branch until its first commit, so its list is empty. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/branches` instead. operationId: list_branches_legacy parameters: - description: Pagination cursor returned by a previous `list_branches` response. example: b_456def in: query name: cursor schema: type: string - description: Maximum number of branches to return. Defaults to 20. example: 20 in: query name: limit schema: default: 20 type: integer - description: When true, list branches under the ephemeral namespace instead of regular branches. in: query name: ephemeral schema: type: boolean responses: "200": content: application/json: example: branches: - created_at: "2024-01-15T10:30:00Z" cursor: b_123abc head_sha: a1b2c3d4e5f6 name: main has_more: true next_cursor: MTcwNzU3MzQ1MTAwMDAwMDAwMHxyZXBvXzlhNGMyMWY schema: $ref: "#/components/schemas/ReposBranchesListResponse" description: Repository branches in creation order. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: List Branches tags: - Branches x-deprecation-message: Use `/api/repos/{repo_name}/branches` instead. x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable /api/v1/repos/branches/create: post: deprecated: true description: |- Create a new branch from an existing branch or ref. This is useful for agent workflows, ephemeral previews, or server-side automation where you do not want to clone the repo first. The base ref must exist. A new empty repository has no branch until its first commit, so the request returns `404`. Scope: `git:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/branches/create` instead. operationId: create_branch_legacy requestBody: content: application/json: example: base_is_ephemeral: false base_ref: main target_branch: feature/new-onboarding target_is_ephemeral: false schema: $ref: "#/components/schemas/ReposBranchesCreateRequest" description: Create a branch from another branch or ref. The source and destination can live in the default namespace or the ephemeral namespace. required: true responses: "200": content: application/json: example: commit_sha: abc123def4567890abc123def4567890abc123de message: branch created target_branch: feature/new-onboarding target_is_ephemeral: false schema: $ref: "#/components/schemas/ReposBranchesCreateResponse" description: Branch creation result. "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: schema: $ref: "#/components/schemas/ProblemDetails" description: Conflict "412": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" description: "`412` has more than one cause. Storage returns `precondition_failed` for a write-specific reason, such as a merge with no common ancestor between source and target, a merge target that moved off a fast-forward under the `ff_only` strategy, or a branch creation whose target cannot be fast-forwarded. A repository with a GitHub upstream also gets `412` when the write cannot reach GitHub: the code is `github_app_not_configured` when the GitHub App has no usable private key, `github_repository_inaccessible` when GitHub does not give the App access to the repository, and `precondition_failed` when GitHub refuses the push for another reason, such as an archived repository. `detail` explains the failure." "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 "502": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" description: A storage node, the upstream Git server or GitHub failed or could not be reached. When the push request to the upstream failed or got a server error, the write may have been applied; check the branch before retrying. "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 summary: Create Branch tags: - Branches x-deprecation-message: Use `/api/repos/{repo_name}/branches/create` instead. x-permission-scopes: - git:write x-request-validation-profile: create_branch x-requires-repo-scope: true x-stability: stable /api/v1/repos/branches/diff: get: deprecated: true description: |- Compare a feature branch to its base branch and return every change that would be reviewed before a merge. Repeated `path` filters limit the diff to selected files and bypass the usual large-file filtering for those requested paths. `GET /api/repos/{repo_name}/diff` replaces this endpoint. Send `branch` as `ref`, `base` as `base_ref`, `ephemeral` as `ref_is_ephemeral`, and `ephemeral_base` as `base_is_ephemeral`. When you omit `base`, this endpoint diffs against the repository default branch. When you omit `base_ref`, `/diff` returns the diff of one commit. To get the same diff, read `default_branch` from the repository and send it as `base_ref`. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/diff` with `ref` and `base_ref` instead. operationId: get_branch_diff_legacy parameters: - description: Branch name to diff. example: feature/new-auth in: query name: branch required: true schema: type: string - description: Optional base branch or ref to diff against. When omitted, the repository default branch is used. example: main in: query name: base schema: type: string - description: Whether `branch` should be resolved from the ephemeral namespace. example: true in: query name: ephemeral schema: type: boolean - description: Whether `base` should be resolved from the ephemeral namespace. example: false in: query name: ephemeral_base schema: type: boolean - description: Optional repeated path filter. Provide multiple `path` query values to restrict the diff to specific files or directories. example: - src/main.go - README.md in: query name: path schema: items: type: string type: array responses: "200": content: application/json: example: base: main branch: feature/new-feature files: - bytes: 2048 is_eof: true path: src/main.go raw: |- diff --git a/src/main.go b/src/main.go ... state: M filtered_files: - bytes: 50000 is_eof: true path: package-lock.json state: M merge_base_sha: a2d127e6a4d54bb7390de828a99e36411f0c84df stats: additions: 50 changes: 60 deletions: 10 files: 3 schema: $ref: "#/components/schemas/GetBranchDiffResponse" description: Diff between a source branch and its base, including the merge base used for the three-dot comparison. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: Get Branch Diff tags: - Commits x-deprecation-message: Use `/api/repos/{repo_name}/diff` with `ref` and `base_ref` instead. x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable /api/v1/repos/commit: get: deprecated: true description: |- Resolve a branch name, short SHA, or full SHA to a commit and return the same metadata shape used in commit listings. Use this when you need commit details without computing a diff. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/commit` instead. operationId: get_commit_legacy parameters: - description: Branch name, tag, full commit SHA, short SHA, or other revision Git can resolve. Provide `ref` or the deprecated `sha`. example: main in: query name: ref schema: type: string - deprecated: true description: "Deprecated: use ref instead. Commit SHA, short SHA, branch name, or other revision Git can resolve." in: query name: sha schema: type: string responses: "200": content: application/json: example: commit: author_email: jane@example.com author_name: Jane Doe committer_date: "2024-01-16T09:05:41Z" committer_email: jane@example.com committer_name: Jane Doe date: "2024-01-15T14:32:18Z" message: "fix: resolve scrolling issue in dashboard" parent_shas: - f4f9df3b8db66c73f6bf67e8f8f4f14f6522731e sha: b003fc78805954584e1ee364a4ad39d7c79e819a signature: | -----BEGIN PGP SIGNATURE----- ... -----END PGP SIGNATURE----- schema: $ref: "#/components/schemas/ReposCommitsGetResponse" description: Commit metadata for the resolved revision. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: Get Commit tags: - Commits x-deprecation-message: Use `/api/repos/{repo_name}/commit` instead. x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable /api/v1/repos/commit-pack: post: deprecated: true description: |- Create a commit by streaming file operations directly to the service. This is designed for automation, AI agents, and other workflows that need atomic Git writes without running a local Git process. Scope: `git:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/commit-pack` instead. operationId: commit_pack_legacy requestBody: content: application/x-ndjson: example: | {"metadata":{"target_branch":"main","expected_target_sha":"d34db33fd34db33fd34db33fd34db33fd34db33f","commit_message":"Update docs","author":{"name":"Docs Bot","email":"docs@example.com"},"files":[{"path":"docs/changelog.md","operation":"upsert","content_id":"blob-1","mode":"100644"},{"path":"docs/legacy.txt","operation":"delete","content_id":"blob-2"}]}} {"blob_chunk":{"content_id":"blob-1","data":"IyBWZXJzaW9uIDIuMS4wCi0gcmVmcmVzaCBkb2NzCg==","eof":true}} {"blob_chunk":{"content_id":"blob-2","data":"","eof":true}} schema: contentSchema: items: additionalProperties: false properties: blob_chunk: $ref: "#/components/schemas/BlobChunk" required: - blob_chunk type: object minItems: 1 prefixItems: - additionalProperties: false properties: metadata: $ref: "#/components/schemas/ReposCommitsCreateRequest" required: - metadata type: object type: array description: NDJSON stream. The first line must be `metadata`; subsequent lines must be `blob_chunk` payloads. Decoded blob chunks are limited to 4 MiB each. type: string description: Send newline-delimited JSON where the first line is a `metadata` object and each following line is a `blob_chunk`. This lets you stream file contents without a local Git client. required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/CommitWriteResponse" description: Commit created and written to the target branch. "400": content: application/json: example: commit: null result: message: first payload must be metadata new_sha: "" old_sha: "" status: invalid success: false target_branch: "" schema: $ref: "#/components/schemas/CommitWriteResponse" description: The NDJSON stream was malformed or metadata validation failed. "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: example: commit: blob_count: 1 commit_sha: 7b3e9f2a1c4d5e6f708192a3b4c5d6e7f8091a2b pack_bytes: 1024 target_branch: main tree_sha: e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4 result: message: failed to update ref new_sha: 7b3e9f2a1c4d5e6f708192a3b4c5d6e7f8091a2b old_sha: d34db33fd34db33fd34db33fd34db33fd34db33f status: failed success: false target_branch: main schema: $ref: "#/components/schemas/CommitWriteResponse" application/problem+json: example: type: about:blank title: Conflict status: 409 detail: base_ref (d34db33fd34db33fd34db33fd34db33fd34db33f) does not match current head c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 code: ref_guard_failed error: base_ref (d34db33fd34db33fd34db33fd34db33fd34db33f) does not match current head c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 guard: expected_target_sha current_sha: c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 commit: null result: target_branch: main branch: main old_sha: c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 new_sha: "" success: false status: conflict message: base_ref (d34db33fd34db33fd34db33fd34db33fd34db33f) does not match current head c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 schema: $ref: "#/components/schemas/CommitWriteRefGuardProblemDetails" description: "The branch moved or the requested update could not be applied cleanly. When the branch moves after storage writes the commit, the body is `application/json`: `result.status` is `failed`, and `commit` is the commit that the branch did not get. When `expected_target_sha` is not the tip of the branch, the body is `application/problem+json` with the code `ref_guard_failed`: `guard` names the guard, and `current_sha` is the tip of the branch, which `result.old_sha` repeats. The body keeps the members of the failure body, and `result.status` is `conflict`." "412": content: application/json: example: commit: null result: message: no changes to commit new_sha: "" old_sha: "" status: precondition_failed success: false target_branch: "" schema: $ref: "#/components/schemas/CommitWriteResponse" description: "The commit makes no changes to the branch: the files match its tip, the request has no file operations, or it deletes only paths that do not exist. `result.status` is `precondition_failed` and `result.message` is `no changes to commit`. A malformed stream, such as a file without its final `eof` chunk, also gets `412`, with another message. A repository with a GitHub upstream also gets `412` when the write cannot reach GitHub: the GitHub App has no usable private key, GitHub does not give the App access to the repository, or GitHub refuses the push with `401`, `403` or `404`. Then `result.status` is `failed` and `result.message` explains the failure." "413": content: application/json: example: commit: null result: message: "commit payload too large: exceeds total blob limit (262144000 bytes)" new_sha: "" old_sha: "" status: payload_too_large success: false target_branch: "" schema: $ref: "#/components/schemas/CommitWriteResponse" description: The decoded file contents of the commit exceeded the total size limit. "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 "502": content: application/json: example: commit: null result: message: upstream Git server request failed; the push may or may not have been applied, check the branch before retrying new_sha: "" old_sha: "" status: internal success: false target_branch: "" schema: $ref: "#/components/schemas/CommitWriteResponse" description: A storage node, the upstream Git server or GitHub failed or could not be reached. When the push request to the upstream failed or got a server error, the write may have been applied; check the branch before retrying. `result.status` is `failed` when GitHub answers the push with a server error, and `commit` is the commit that the write tried to set. `result.status` is `internal` and `commit` is `null` when the push request fails, or when GitHub answers with a server error or cannot be reached while the gateway gets its GitHub token. `result.message` explains the failure. "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 summary: Create Commit from Files tags: - Commits x-deprecation-message: Use `/api/repos/{repo_name}/commit-pack` instead. x-permission-scopes: - git:write x-requires-repo-scope: true x-stability: stable /api/v1/repos/commits: get: deprecated: true description: |- List commit history for the repository default branch or for an explicit branch. Results are cursor-paginated and ordered by commit date, newest first. Set `path` to restrict the history to commits that modified a specific file or subtree. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/commits` instead. operationId: list_commits_legacy parameters: - description: Optional branch, tag, or commit to list commits from. When omitted, the repository default branch is used. Provide `ref` or the deprecated `branch`. example: main in: query name: ref schema: type: string - deprecated: true description: "Deprecated: use ref instead. Optional branch name to list commits from. When omitted, the repository default branch is used." in: query name: branch schema: type: string - description: Optional repository-relative path to scope the history to commits that touched that path. example: docs/guide.md in: query name: path schema: type: string - description: Pagination cursor returned by a previous `list_commits` response. example: "20" in: query name: cursor schema: type: string - description: Maximum number of commits to return. Defaults to 20. example: 20 in: query name: limit schema: default: 20 type: integer - description: Whether `ref` should be resolved from the ephemeral namespace. in: query name: ephemeral schema: type: boolean responses: "200": content: application/json: example: commits: - author_email: jane@example.com author_name: Jane Doe committer_date: "2024-01-16T09:05:41Z" committer_email: jane@example.com committer_name: Jane Doe date: "2024-01-15T14:32:18Z" message: "fix: resolve scrolling issue in dashboard" parent_shas: - f4f9df3b8db66c73f6bf67e8f8f4f14f6522731e sha: b003fc78805954584e1ee364a4ad39d7c79e819a signature: | -----BEGIN PGP SIGNATURE----- ... -----END PGP SIGNATURE----- has_more: true next_cursor: MTcwNzU3MzQ1MTAwMDAwMDAwMHxyZXBvXzlhNGMyMWY schema: $ref: "#/components/schemas/ReposCommitsListResponse" description: Commit history ordered from newest to oldest. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: List Commits tags: - Commits x-deprecation-message: Use `/api/repos/{repo_name}/commits` instead. x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable /api/v1/repos/delete: delete: deprecated: true description: |- Permanently retire a repository. The API performs a soft delete first and then triggers asynchronous hot and cold storage cleanup. Scope: `repo:write` on the repository. Deprecated: Use `/api/repos/{repo_name}` instead. operationId: delete_repo_legacy responses: "200": content: application/json: example: message: Repository pierre/sdk-documentation deletion initiated. Physical storage cleanup will complete asynchronously. repo_id: repo_7f2b3d9 repo_name: pierre/sdk-documentation schema: $ref: "#/components/schemas/ReposDeleteResponse" description: Deletion accepted. Physical storage cleanup continues asynchronously. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: example: code: repository_deleted detail: repository already deleted error: repository already deleted instance: /api/repos/dotfiles status: 409 title: Conflict type: about:blank schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: example: code: repository_deleted detail: repository already deleted error: repository already deleted instance: /api/repos/dotfiles status: 409 title: Conflict type: about:blank schema: $ref: "#/components/schemas/ProblemDetails" description: The repository was already deleted. "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: - repo:write summary: Delete Repo tags: - Repositories x-deprecation-message: Use `/api/repos/{repo_name}` instead. x-permission-scopes: - repo:write x-requires-repo-scope: true x-stability: stable /api/v1/repos/diff: get: deprecated: true description: |- Get the diff for a commit, optionally relative to a specific base commit. Repeated `path` parameters narrow the diff to selected files or directories. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/diff` instead. operationId: get_commit_diff_legacy parameters: - description: Branch, tag, or commit to diff. Provide `ref` or the deprecated `sha`. example: b003fc78805954584e1ee364a4ad39d7c79e819a in: query name: ref schema: type: string - deprecated: true description: "Deprecated: use ref instead. Commit SHA to diff." in: query name: sha schema: type: string - description: Optional base branch, tag, or commit to diff against. When omitted, the diff is generated against the commit's parent. When set, the diff starts at the merge base of `base_ref` and `ref`, as `git diff base_ref...ref` does, and `merge_base_sha` gives that commit. So the diff holds only the changes on `ref` after the two histories split. When `ref` is an ancestor of `base_ref`, the merge base is `ref`, and the diff is empty. Provide `base_ref` or the deprecated `baseSha`. example: a4d39d7c79e819ab003fc78805954584e1ee36 in: query name: base_ref schema: type: string - deprecated: true description: "Deprecated: use base_ref instead. Optional base commit SHA to diff against. When omitted, the diff is generated against the commit's parent." in: query name: baseSha schema: type: string - description: Whether `ref` should be resolved from the ephemeral namespace. in: query name: ref_is_ephemeral schema: type: boolean - description: Whether `base_ref` should be resolved from the ephemeral namespace. in: query name: base_is_ephemeral schema: type: boolean - description: Optional repeated path filter. Provide multiple `path` query values to restrict the diff to specific files or directories. example: - src/main.go - README.md in: query name: path schema: items: type: string type: array - description: When enabled, concatenate `files[].raw` in response order and apply the result against the selected base with `git apply`. Changes listed in `filtered_files` are not included in the patch. Defaults to false, preserving review-oriented whitespace suppression. Provide `git_apply_compatible` or the deprecated `gitApplyCompatible`. example: false in: query name: git_apply_compatible schema: type: boolean - deprecated: true description: "Deprecated: use git_apply_compatible instead. When enabled, concatenate `files[].raw` in response order and apply the result against the selected base with `git apply`. Changes listed in `filtered_files` are not included in the patch. Defaults to false, preserving review-oriented whitespace suppression." in: query name: gitApplyCompatible schema: type: boolean responses: "200": content: application/json: example: base_sha: a2d127e6a4d54bb7390de828a99e36411f0c84df files: - bytes: 2048 is_eof: true path: src/main.go raw: |- diff --git a/src/main.go b/src/main.go ... state: M filtered_files: - bytes: 50000 is_eof: true path: package-lock.json state: M merge_base_sha: a2d127e6a4d54bb7390de828a99e36411f0c84df sha: b003fc78805954584e1ee364a4ad39d7c79e819a stats: additions: 50 changes: 60 deletions: 10 files: 3 schema: $ref: "#/components/schemas/ReposDiffGetResponse" description: Full diff for the requested commit, including file-level stats, line-level hunks, and merge base for explicit base comparisons. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: Get Commit Diff tags: - Commits x-deprecation-message: Use `/api/repos/{repo_name}/diff` instead. x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable /api/v1/repos/diff-commit: post: deprecated: true description: |- Create a commit by streaming a Git patch instead of individual file blobs. Use this when your workflow already produces unified diffs or generated patches. Scope: `git:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/diff-commit` instead. operationId: diff_commit_legacy requestBody: content: application/x-ndjson: example: | {"metadata":{"target_branch":"main","expected_target_sha":"d34db33fd34db33fd34db33fd34db33fd34db33f","commit_message":"Apply generated patch","author":{"name":"Diff Bot","email":"diff@example.com"}}} {"diff_chunk":{"data":"ZGlmZiAtLWdpdCBhL1JFQURNRS5tZCBiL1JFQURNRS5tZAo=","eof":false}} {"diff_chunk":{"data":"QEAgLTEsMSArMSwyIEBACi1IZWxsbworSGVsbG8gV29ybGQK","eof":true}} schema: contentSchema: items: additionalProperties: false properties: diff_chunk: $ref: "#/components/schemas/DiffChunk" required: - diff_chunk type: object minItems: 1 prefixItems: - additionalProperties: false properties: metadata: $ref: "#/components/schemas/ReposCommitsCreateFromDiffRequest" required: - metadata type: object type: array description: NDJSON stream. The first line must be `metadata`; subsequent lines must be `diff_chunk` payloads. Decoded diff chunks are limited to 4 MiB each. type: string description: Send newline-delimited JSON where the first line is a `metadata` object and each following line is a `diff_chunk`. The combined diff must be compatible with `git apply --cached --binary`. required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/CommitWriteResponse" description: Commit created from the supplied diff. "400": content: application/json: example: commit: null result: message: diff content missing new_sha: "" old_sha: "" status: invalid success: false target_branch: "" schema: $ref: "#/components/schemas/CommitWriteResponse" description: The NDJSON stream or diff payload was invalid. "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: example: commit: blob_count: 1 commit_sha: 7b3e9f2a1c4d5e6f708192a3b4c5d6e7f8091a2b pack_bytes: 1024 target_branch: main tree_sha: e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4 result: message: failed to update ref new_sha: 7b3e9f2a1c4d5e6f708192a3b4c5d6e7f8091a2b old_sha: d34db33fd34db33fd34db33fd34db33fd34db33f status: failed success: false target_branch: main schema: $ref: "#/components/schemas/CommitWriteResponse" application/problem+json: example: type: about:blank title: Conflict status: 409 detail: base_ref (d34db33fd34db33fd34db33fd34db33fd34db33f) does not match current head c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 code: ref_guard_failed error: base_ref (d34db33fd34db33fd34db33fd34db33fd34db33f) does not match current head c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 guard: expected_target_sha current_sha: c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 commit: null result: target_branch: main branch: main old_sha: c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 new_sha: "" success: false status: conflict message: base_ref (d34db33fd34db33fd34db33fd34db33fd34db33f) does not match current head c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 schema: $ref: "#/components/schemas/CommitWriteRefGuardProblemDetails" description: "The diff could not be applied cleanly or the target branch tip changed. When the diff does not apply, the body is `application/json` and `result.status` is `conflict`. When the branch moves after storage writes the commit, the body is `application/json`: `result.status` is `failed`, and `commit` is the commit that the branch did not get. When `expected_target_sha` is not the tip of the branch, the body is `application/problem+json` with the code `ref_guard_failed`: `guard` names the guard, and `current_sha` is the tip of the branch, which `result.old_sha` repeats. The body keeps the members of the failure body, and `result.status` is `conflict`." "412": content: application/json: example: commit: null result: message: no changes to commit new_sha: "" old_sha: "" status: precondition_failed success: false target_branch: "" schema: $ref: "#/components/schemas/CommitWriteResponse" description: "Applying the diff makes no changes to the branch. `result.status` is `precondition_failed` and `result.message` is `no changes to commit`. A malformed stream, such as a stream without its final `eof` chunk, also gets `412`, with another message. A repository with a GitHub upstream also gets `412` when the write cannot reach GitHub: the GitHub App has no usable private key, GitHub does not give the App access to the repository, or GitHub refuses the push with `401`, `403` or `404`. Then `result.status` is `failed` and `result.message` explains the failure." "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 "502": content: application/json: example: commit: null result: message: upstream Git server request failed; the push may or may not have been applied, check the branch before retrying new_sha: "" old_sha: "" status: internal success: false target_branch: "" schema: $ref: "#/components/schemas/CommitWriteResponse" description: A storage node, the upstream Git server or GitHub failed or could not be reached. When the push request to the upstream failed or got a server error, the write may have been applied; check the branch before retrying. `result.status` is `failed` when GitHub answers the push with a server error, and `commit` is the commit that the write tried to set. `result.status` is `internal` and `commit` is `null` when the push request fails, or when GitHub answers with a server error or cannot be reached while the gateway gets its GitHub token. `result.message` explains the failure. "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 summary: Create Commit from Diff tags: - Commits x-deprecation-message: Use `/api/repos/{repo_name}/diff-commit` instead. x-permission-scopes: - git:write x-requires-repo-scope: true x-stability: stable /api/v1/repos/file: get: deprecated: true description: |- Stream a file directly from the repository with byte ranges, ETag validators, and Last-Modified conditionals. Use `ref` to read from a branch, tag, or commit without cloning the repo locally. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/file` instead. operationId: get_file_legacy parameters: - description: Repository-relative file path to fetch. example: src/main.js in: query name: path required: true schema: type: string - description: Optional branch, tag, or commit SHA to read from. When omitted, the repository default branch is used. example: v1.0.0 in: query name: ref schema: type: string - description: Whether `ref` should be resolved from the ephemeral namespace. example: true in: query name: ephemeral schema: type: boolean - description: Standard HTTP byte-range header (`bytes=-`). Triggers a `206 Partial Content` response. in: header name: Range schema: type: string - description: "Conditional range request: when the supplied validator matches `ETag` or `Last-Modified`, the server returns `206 Partial Content`; otherwise the full body is returned with `200 OK`." in: header name: If-Range schema: type: string - description: Returns `412 Precondition Failed` when the current `ETag` does not match. in: header name: If-Match schema: type: string - description: Returns `304 Not Modified` when the current `ETag` matches. in: header name: If-None-Match schema: type: string - description: Returns `304 Not Modified` when `Last-Modified` is on or before this date. in: header name: If-Modified-Since schema: type: string - description: Returns `412 Precondition Failed` when `Last-Modified` is after this date. in: header name: If-Unmodified-Since schema: type: string responses: "200": content: application/octet-stream: schema: contentMediaType: application/octet-stream description: Raw file bytes exactly as stored in the Git blob. No transcoding or encoding is applied. format: binary type: string description: File content returned. headers: Accept-Ranges: description: Set to `bytes`; the endpoint accepts byte-range requests via `Range`. schema: type: string Content-Length: description: Full blob size in bytes for 200 responses, or range size for 206 responses. schema: type: string Content-Range: description: Returned for 206 responses; identifies the byte range served. schema: type: string Content-Type: description: Always `application/octet-stream`. schema: type: string ETag: description: Strong validator equal to the quoted blob object SHA. Use with `If-Match` / `If-None-Match`. schema: type: string Last-Modified: description: Committer date of the most recent commit reachable from `ref` that modified `path`. Use with `If-Modified-Since` / `If-Unmodified-Since`. schema: type: string X-Blob-Sha: description: Git blob object SHA of the served file. schema: type: string X-Last-Commit-Sha: description: SHA of the most recent commit reachable from `ref` that modified `path`. schema: type: string "206": content: application/octet-stream: schema: contentMediaType: application/octet-stream description: The requested slice of the raw file bytes. `Content-Range` identifies which bytes were served. format: binary type: string description: Byte range satisfied. Body contains only the requested bytes; `Content-Range` identifies the range. headers: Accept-Ranges: description: Set to `bytes`; the endpoint accepts byte-range requests via `Range`. schema: type: string Content-Length: description: Full blob size in bytes for 200 responses, or range size for 206 responses. schema: type: string Content-Range: description: Returned for 206 responses; identifies the byte range served. schema: type: string Content-Type: description: Always `application/octet-stream`. schema: type: string ETag: description: Strong validator equal to the quoted blob object SHA. Use with `If-Match` / `If-None-Match`. schema: type: string Last-Modified: description: Committer date of the most recent commit reachable from `ref` that modified `path`. Use with `If-Modified-Since` / `If-Unmodified-Since`. schema: type: string X-Blob-Sha: description: Git blob object SHA of the served file. schema: type: string X-Last-Commit-Sha: description: SHA of the most recent commit reachable from `ref` that modified `path`. schema: type: string "304": description: Cached representation still valid. Returned when `If-None-Match` matches the current `ETag` or `If-Modified-Since` is on or after `Last-Modified`. Body is empty. headers: ETag: description: Strong validator equal to the quoted blob object SHA. Use with `If-Match` / `If-None-Match`. schema: type: string Last-Modified: description: Committer date of the most recent commit reachable from `ref` that modified `path`. Use with `If-Modified-Since` / `If-Unmodified-Since`. schema: type: string X-Blob-Sha: description: Git blob object SHA of the served file. schema: type: string X-Last-Commit-Sha: description: SHA of the most recent commit reachable from `ref` that modified `path`. schema: type: string "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: Conflict "412": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" description: "Precondition from `If-Match` or `If-Unmodified-Since` failed: the resource has changed since the validator the client supplied." "416": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" description: Requested byte range is outside the blob size. "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:read summary: Get File tags: - Files x-deprecation-message: Use `/api/repos/{repo_name}/file` instead. x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable head: deprecated: true description: |- Return file metadata headers for a repository file without streaming the file body. Supports byte ranges, ETag validators, and Last-Modified conditionals. Use `ref` to inspect a branch, tag, or commit without cloning the repo locally. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/file` instead. operationId: head_file_legacy parameters: - description: Repository-relative file path to fetch. example: src/main.js in: query name: path required: true schema: type: string - description: Optional branch, tag, or commit SHA to read from. When omitted, the repository default branch is used. example: v1.0.0 in: query name: ref schema: type: string - description: Whether `ref` should be resolved from the ephemeral namespace. example: true in: query name: ephemeral schema: type: boolean - description: Standard HTTP byte-range header (`bytes=-`). Triggers a `206 Partial Content` response. in: header name: Range schema: type: string - description: "Conditional range request: when the supplied validator matches `ETag` or `Last-Modified`, the server returns `206 Partial Content`; otherwise the full body is returned with `200 OK`." in: header name: If-Range schema: type: string - description: Returns `412 Precondition Failed` when the current `ETag` does not match. in: header name: If-Match schema: type: string - description: Returns `304 Not Modified` when the current `ETag` matches. in: header name: If-None-Match schema: type: string - description: Returns `304 Not Modified` when `Last-Modified` is on or before this date. in: header name: If-Modified-Since schema: type: string - description: Returns `412 Precondition Failed` when `Last-Modified` is after this date. in: header name: If-Unmodified-Since schema: type: string responses: "200": description: File metadata headers returned. Body is empty. headers: Accept-Ranges: description: Set to `bytes`; the endpoint accepts byte-range requests via `Range`. schema: type: string Content-Length: description: Full blob size in bytes for 200 responses, or range size for 206 responses. schema: type: string Content-Range: description: Returned for 206 responses; identifies the byte range served. schema: type: string Content-Type: description: Always `application/octet-stream`. schema: type: string ETag: description: Strong validator equal to the quoted blob object SHA. Use with `If-Match` / `If-None-Match`. schema: type: string Last-Modified: description: Committer date of the most recent commit reachable from `ref` that modified `path`. Use with `If-Modified-Since` / `If-Unmodified-Since`. schema: type: string X-Blob-Sha: description: Git blob object SHA of the served file. schema: type: string X-Last-Commit-Sha: description: SHA of the most recent commit reachable from `ref` that modified `path`. schema: type: string "206": description: Byte range satisfied. Body is empty; `Content-Range` identifies the range. headers: Accept-Ranges: description: Set to `bytes`; the endpoint accepts byte-range requests via `Range`. schema: type: string Content-Length: description: Full blob size in bytes for 200 responses, or range size for 206 responses. schema: type: string Content-Range: description: Returned for 206 responses; identifies the byte range served. schema: type: string Content-Type: description: Always `application/octet-stream`. schema: type: string ETag: description: Strong validator equal to the quoted blob object SHA. Use with `If-Match` / `If-None-Match`. schema: type: string Last-Modified: description: Committer date of the most recent commit reachable from `ref` that modified `path`. Use with `If-Modified-Since` / `If-Unmodified-Since`. schema: type: string X-Blob-Sha: description: Git blob object SHA of the served file. schema: type: string X-Last-Commit-Sha: description: SHA of the most recent commit reachable from `ref` that modified `path`. schema: type: string "304": description: Cached representation still valid. Returned when `If-None-Match` matches the current `ETag` or `If-Modified-Since` is on or after `Last-Modified`. Body is empty. headers: ETag: description: Strong validator equal to the quoted blob object SHA. Use with `If-Match` / `If-None-Match`. schema: type: string Last-Modified: description: Committer date of the most recent commit reachable from `ref` that modified `path`. Use with `If-Modified-Since` / `If-Unmodified-Since`. schema: type: string X-Blob-Sha: description: Git blob object SHA of the served file. schema: type: string X-Last-Commit-Sha: description: SHA of the most recent commit reachable from `ref` that modified `path`. schema: type: string "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: Conflict "412": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" description: "Precondition from `If-Match` or `If-Unmodified-Since` failed: the resource has changed since the validator the client supplied." "416": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" description: Requested byte range is outside the blob size. "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:read summary: Get File Headers tags: - Files x-deprecation-message: Use `/api/repos/{repo_name}/file` instead. x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable /api/v1/repos/files: get: deprecated: true description: |- List files or direct child entries at a branch, tag, or commit without cloning the repository. Each entry includes its path, Git mode, and derived type (`blob`, `tree`, `symlink`, or `submodule`). Trees no longer carry a trailing `/`; branch on `type` instead. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/files` instead. operationId: list_files_legacy parameters: - description: Optional branch, tag, or commit SHA to list from. When omitted, the repository default branch is used. example: main in: query name: ref schema: type: string - description: Optional repository-relative subtree to list. Empty means the repository root. example: docs in: query name: path schema: type: string - description: When true, include descendants recursively. When false, only direct children are returned. Defaults to true. example: false in: query name: recursive schema: default: true type: boolean - description: Pagination cursor returned by a previous `list_files` response. example: docs/guide.md in: query name: cursor schema: type: string - description: Maximum number of paths to return. A call with no `limit` and no `cursor` returns every path in one response, with `has_more` false. A `limit` of 0 is the same as no `limit`. A call with a `cursor` and no `limit` returns up to 1000 paths. example: 1000 in: query name: limit schema: maximum: 5000 minimum: 0 type: integer - description: Whether `ref` should be resolved from the ephemeral namespace. example: true in: query name: ephemeral schema: type: boolean responses: "200": content: application/json: example: entries: - mode: "100644" path: src/main.go type: blob has_more: true next_cursor: MTcwNzU3MzQ1MTAwMDAwMDAwMHxyZXBvXzlhNGMyMWY paths: - README.md ref: main schema: $ref: "#/components/schemas/ReposFilesListResponse" description: Tree entries for the resolved revision. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: List Files tags: - Files x-deprecation-message: Use `/api/repos/{repo_name}/files` instead. x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable /api/v1/repos/files/metadata: get: deprecated: true description: |- Return a recursive file tree together with per-file commit metadata in one request. Each file also includes a derived `type` field for symmetry with `/files`. The server reads the last commit of each file under `path`, also when the call sends a `limit` or a `cursor`. When those files have more than 50,000 distinct last commits, the call fails with a 429 response, and a retry gets the same response. To list such a tree, send a narrower `path`. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/files/metadata` instead. operationId: list_files_metadata_legacy parameters: - description: Optional branch, tag, or commit SHA to list from. When omitted, the repository default branch is used. example: main in: query name: ref schema: type: string - description: Optional repository-relative subtree to list recursively. Empty means the repository root. example: docs in: query name: path schema: type: string - description: Accepted for API symmetry. Metadata listings are recursive regardless of this flag. example: true in: query name: recursive schema: type: boolean - description: Pagination cursor returned by a previous `list_files_with_metadata` response. example: docs/guide.md in: query name: cursor schema: type: string - description: Maximum number of files to return. A call with no `limit` and no `cursor` returns every file in one response, with `has_more` false. A `limit` of 0 is the same as no `limit`. A call with a `cursor` and no `limit` returns up to 200 files. example: 200 in: query name: limit schema: maximum: 1000 minimum: 0 type: integer - description: Whether `ref` should be resolved from the ephemeral namespace. example: true in: query name: ephemeral schema: type: boolean responses: "200": content: application/json: example: files: - last_commit_sha: a1b2c3d4e5f6 mode: "100644" path: README.md size: 2048 type: blob has_more: true next_cursor: MTcwNzU3MzQ1MTAwMDAwMDAwMHxyZXBvXzlhNGMyMWY ref: main schema: $ref: "#/components/schemas/ReposFilesMetadataListResponse" description: The repository tree plus deduplicated commit metadata for the latest change touching each file. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: List Files with Metadata tags: - Files x-deprecation-message: Use `/api/repos/{repo_name}/files/metadata` instead. x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable /api/v1/repos/git-credentials: delete: deprecated: true description: |- Delete a stored HTTPS credential for a generic Git upstream. Scope: `repo:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/git-credentials/{git_credential_id}` instead. operationId: delete_generic_git_credential_legacy requestBody: content: application/json: example: id: ggc_1234567890abcdef schema: $ref: "#/components/schemas/ReposGitCredentialsDeleteRequestLegacy" description: Delete the stored HTTPS credential for a repository's generic Git upstream. required: true responses: "204": description: Credential deleted successfully. "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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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: - repo:write summary: Delete Git Credential tags: - Repositories x-deprecation-message: Use `/api/repos/{repo_name}/git-credentials/{git_credential_id}` instead. x-permission-scopes: - repo:write x-request-validation-profile: delete_generic_git_credential x-requires-repo-scope: true x-stability: stable post: deprecated: true description: |- Create a stored HTTPS credential for a repository configured with a generic Git upstream. Scope: `repo:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/git-credentials` instead. operationId: create_generic_git_credential_legacy requestBody: content: application/json: example: password: glpat_xxxxxxxxxxxx repo_id: repo_7f2b3d9 username: oauth2 schema: $ref: "#/components/schemas/ReposGitCredentialsCreateRequestLegacy" description: Store HTTPS credentials for a generic Git upstream such as GitLab, Bitbucket, Gitea, Forgejo, Codeberg, or SourceHut. required: true responses: "201": content: application/json: example: created_at: "2026-03-12T15:04:05Z" id: ggc_1234567890abcdef schema: $ref: "#/components/schemas/GitCredential" description: Credential created successfully. "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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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: - repo:write summary: Create Git Credential tags: - Repositories x-deprecation-message: Use `/api/repos/{repo_name}/git-credentials` instead. x-permission-scopes: - repo:write x-request-validation-profile: create_generic_git_credential x-requires-repo-scope: true x-stability: stable put: deprecated: true description: |- Update a stored HTTPS credential for a generic Git upstream. Scope: `repo:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/git-credentials/{git_credential_id}` instead. operationId: update_generic_git_credential_legacy requestBody: content: application/json: example: id: ggc_1234567890abcdef password: glpat_rotated_token username: oauth2 schema: $ref: "#/components/schemas/ReposGitCredentialsUpdateRequestLegacy" description: Rotate or replace an existing generic Git credential. required: true responses: "200": content: application/json: example: created_at: "2026-03-12T15:04:05Z" id: ggc_1234567890abcdef schema: $ref: "#/components/schemas/GitCredential" description: Credential updated successfully. "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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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: - repo:write summary: Update Git Credential tags: - Repositories x-deprecation-message: Use `/api/repos/{repo_name}/git-credentials/{git_credential_id}` instead. x-permission-scopes: - repo:write x-request-validation-profile: update_generic_git_credential x-requires-repo-scope: true x-stability: stable /api/v1/repos/grep: post: deprecated: true description: |- Search a repository without cloning it. Results are paginated and can include surrounding context lines so downstream tools only fetch the relevant slices. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/grep` instead. operationId: grep_legacy requestBody: content: application/json: example: context: after: 1 before: 0 pagination: limit: 50 query: case_sensitive: true pattern: ephemeral branches ref: main schema: $ref: "#/components/schemas/ReposGrepRequest" description: Search repository contents by pattern. Optional file filters, context lines, and pagination let you retrieve only the relevant slices for agents and tools. required: true responses: "200": content: application/json: example: has_more: true incomplete_results: false matches: - path: app/blog/markdown/ephemeral-branches.md query: case_sensitive: true pattern: ephemeral branches repo: commit: b003fc78805954584e1ee364a4ad39d7c79e819a ref: main schema: $ref: "#/components/schemas/ReposGrepResponse" description: Search results for the requested pattern. headers: X-Cache: description: Indicates grep cache status (`HIT` or `MISS`). schema: type: string "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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: Grep tags: - Files x-deprecation-message: Use `/api/repos/{repo_name}/grep` instead. x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable /api/v1/repos/merge: post: deprecated: true description: |- Merge changes between branches without cloning the repository or shelling out to Git. This endpoint also supports promoting work from ephemeral branches into long-lived branches such as `main`. Set `expected_source_sha` to merge the exact source commit that a preview returned, even if the source branch advances. Omit `expected_target_sha` to merge into the current target tip and allow the gateway to retry stale target/repository movement internally; set `expected_target_sha` to require a strict target-tip precondition. GitHub-backed public targets currently do not use automatic retry. Scope: `git:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/merge` instead. operationId: merge_branch_legacy requestBody: content: application/json: example: author: email: review@example.com name: Review Bot commit_message: Merge feature/preview committer: email: review@example.com name: Review Bot expected_source_sha: 9eb378bdb5bf1944f6ba0bd5a2c4df3ce32f4df1 expected_target_sha: c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 source_branch: feature/preview source_is_ephemeral: true source_ref: feature/preview squash: false strategy: merge target_branch: main schema: $ref: "#/components/schemas/ReposMergeRequest" description: "Merge a source branch into a target branch using a merge commit, fast-forward only, or fast-forward preferred behaviour. Source and target can live in the default or ephemeral namespace. Set expected_source_sha to merge the source commit that a preview returned: the merge uses that commit, and fails if source_ref no longer contains it. When expected_target_sha is omitted, the gateway may retry stale target updates internally while keeping the originally resolved source commit pinned. Automatic stale-target retry is disabled for GitHub-backed public targets." required: true responses: "200": content: application/json: example: commit_sha: 41f0d5c6cc5f4d0fb4a3af2de27ccf9a80ab3b84 merge_base_sha: a2d127e6a4d54bb7390de828a99e36411f0c84df promoted_commits: 3 result: merged source: branch: feature/preview ephemeral: true ref: feature/preview sha: 9eb378bdb5bf1944f6ba0bd5a2c4df3ce32f4df1 target: branch: main new_sha: 41f0d5c6cc5f4d0fb4a3af2de27ccf9a80ab3b84 old_sha: c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 tree_sha: b9532c5d5be50d88e2f45d7c229566b2f1f99731 schema: $ref: "#/components/schemas/ReposMergeResponse" description: Merge result, including the source and target commit state after the operation. "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: example: conflict_type: merge_conflict error: merge conflict schema: $ref: "#/components/schemas/MergeConflict" application/problem+json: example: type: about:blank title: Conflict status: 409 detail: "source branch moved: the source branch does not contain commit 9eb378bdb5bf1944f6ba0bd5a2c4df3ce32f4df1" code: ref_guard_failed error: "source branch moved: the source branch does not contain commit 9eb378bdb5bf1944f6ba0bd5a2c4df3ce32f4df1" guard: expected_source_sha current_sha: c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 schema: $ref: "#/components/schemas/ProblemDetails" description: "The merge could not be completed. An `application/json` body reports file-level conflicts, or an automatic stale-target retry that could not absorb concurrent target/repository movement. Inspect conflict_type to distinguish merge_conflict, target_moved, and repo_changed. A problem body reports any other conflict. A failed guard has the code `ref_guard_failed`: the target no longer matches `expected_target_sha`, or the source branch no longer contains `expected_source_sha`. Its body is a `RefGuardProblemDetails`: `guard` names the guard, and `current_sha` is the tip of the guarded branch, or 40 zeros when the source branch does not exist." "412": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" description: "`412` has more than one cause. Storage returns `precondition_failed` for a write-specific reason, such as a merge with no common ancestor between source and target, a merge target that moved off a fast-forward under the `ff_only` strategy, or a branch creation whose target cannot be fast-forwarded. A repository with a GitHub upstream also gets `412` when the write cannot reach GitHub: the code is `github_app_not_configured` when the GitHub App has no usable private key, `github_repository_inaccessible` when GitHub does not give the App access to the repository, and `precondition_failed` when GitHub refuses the push for another reason, such as an archived repository. `detail` explains the failure." "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 "502": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" description: A storage node, the upstream Git server or GitHub failed or could not be reached. When the push request to the upstream failed or got a server error, the write may have been applied; check the branch before retrying. "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 summary: Merge Branch tags: - Branches x-deprecation-message: Use `/api/repos/{repo_name}/merge` instead. x-permission-scopes: - git:write x-request-validation-profile: merge_branch x-requires-repo-scope: true x-stability: stable /api/v1/repos/merge/preview: get: deprecated: true description: |- Preview merge conflicts without creating commits, updating refs, or touching a working tree. When requested, conflict content is rendered from Git objects produced in request-local scratch storage. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/merge/preview` instead. operationId: preview_merge_legacy parameters: - description: Source branch to merge from. example: feature/preview in: query name: source_branch required: true schema: type: string - description: Destination branch to preview merging into. example: main in: query name: target_branch required: true schema: type: string - description: Whether `source_branch` should be resolved from the ephemeral namespace. in: query name: source_is_ephemeral schema: type: boolean - description: Whether `target_branch` should be resolved from the ephemeral namespace. in: query name: target_is_ephemeral schema: type: boolean - description: When true, include bounded conflict content in the response. example: true in: query name: include_content schema: type: boolean responses: "200": content: application/json: example: conflicts: - base: binary: false oid: "1111111111111111111111111111111111111111" truncated: false ours: binary: false oid: "1111111111111111111111111111111111111111" truncated: false path: docs/conflict.txt result: binary: false oid: "1111111111111111111111111111111111111111" truncated: false theirs: binary: false oid: "1111111111111111111111111111111111111111" truncated: false filtered_conflicts: - path: src/app.ts reason: max_conflict_files_exceeded merge_base_sha: a2d127e6a4d54bb7390de828a99e36411f0c84df result: merge_commit source_branch: feature/preview source_tip_sha: 9eb378bdb5bf1944f6ba0bd5a2c4df3ce32f4df1 status: conflicted target_branch: main target_tip_sha: c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 schema: $ref: "#/components/schemas/ReposPreviewMergeResponse" description: Merge preview result. Conflicted previews return HTTP 200 with `status=conflicted`; request and storage failures use normal HTTP errors. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: Preview Merge tags: - Branches x-deprecation-message: Use `/api/repos/{repo_name}/merge/preview` instead. x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable /api/v1/repos/notes: delete: deprecated: true 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. Deprecated: Use `/api/repos/{repo_name}/notes` instead. operationId: notes_delete_legacy parameters: - 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: example: author: email: review@example.com name: Review Bot notes_ref: refs/notes/commits object_ref: b003fc78805954584e1ee364a4ad39d7c79e819a ref: refs/notes/commits sha: b003fc78805954584e1ee364a4ad39d7c79e819a 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 target_ref: refs/notes/commits 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 summary: Delete Note tags: - Notes x-deprecation-message: Use `/api/repos/{repo_name}/notes` instead. x-permission-scopes: - git:write x-requires-repo-scope: true x-stability: stable get: deprecated: true description: |- Read the Git note attached to a commit or other Git object SHA. Notes let you store review status, handoff details, or other context without changing repository contents. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/notes` instead. operationId: notes_read_legacy parameters: - description: Git object whose note should be fetched. A full object SHA today. Provide object_ref or the deprecated sha. example: b003fc78805954584e1ee364a4ad39d7c79e819a in: query name: object_ref schema: type: string - deprecated: true description: "Deprecated: use object_ref instead. Git object SHA whose note should be fetched." in: query name: sha schema: type: string - description: Optional notes ref to read 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. Provide notes_ref or the deprecated ref. example: refs/notes/commits in: query name: notes_ref schema: type: string - deprecated: true description: "Deprecated: use notes_ref instead. Optional notes ref to read from. Defaults to refs/notes/commits." in: query name: ref schema: type: string responses: "200": content: application/json: example: note: Reviewed. Ready for production. ref_sha: 0c8b5bb9d550d58fcfd651a4fdce8024ef7f1492 sha: b003fc78805954584e1ee364a4ad39d7c79e819a schema: $ref: "#/components/schemas/ReposNotesGetResponse" description: The note stored for the requested Git object. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: Get Note tags: - Notes x-deprecation-message: Use `/api/repos/{repo_name}/notes` instead. x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable post: deprecated: true description: |- 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. Deprecated: Use `/api/repos/{repo_name}/notes` instead. operationId: notes_write_legacy requestBody: content: application/json: example: author: email: review@example.com name: Review Bot note: Reviewed. Ready for production. notes_ref: refs/notes/commits object_ref: b003fc78805954584e1ee364a4ad39d7c79e819a ref: refs/notes/commits sha: b003fc78805954584e1ee364a4ad39d7c79e819a examples: create_note: description: Create a new note on a commit. summary: Create note value: author: email: review@example.com name: Review Bot note: Reviewed. Ready for production. object_ref: b003fc78805954584e1ee364a4ad39d7c79e819a schema: $ref: "#/components/schemas/ReposNotesCreateRequest" description: "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." required: true 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 target_ref: refs/notes/commits schema: $ref: "#/components/schemas/NotesWriteResponse" description: Note update applied to 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 summary: Create Note tags: - Notes x-deprecation-message: Use `/api/repos/{repo_name}/notes` instead. x-permission-scopes: - git:write x-requires-repo-scope: true x-stability: stable /api/v1/repos/notes/refs: get: deprecated: true description: |- List Git notes refs under a notes ref prefix with cursor pagination. Use this to discover custom notes namespaces before reading individual notes. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/notes/refs` instead. operationId: list_notes_refs_legacy parameters: - description: Notes ref prefix to enumerate. A bare prefix like reviews is placed under refs/notes/; a fully-qualified refs/notes/* prefix is also accepted. Defaults to refs/notes/. example: reviews/ in: query name: prefix schema: type: string - description: Pagination cursor returned by a previous `list_notes_refs` response. example: refs/notes/reviews/session-b in: query name: cursor schema: type: string - description: Maximum number of notes refs to return. Defaults to 20. example: 20 in: query name: limit schema: default: 20 type: integer responses: "200": content: application/json: example: has_more: true next_cursor: MTcwNzU3MzQ1MTAwMDAwMDAwMHxyZXBvXzlhNGMyMWY prefix: refs/notes/reviews/ refs: - cursor: refs/notes/reviews/session-a ref: refs/notes/reviews/session-a sha: a1b2c3d4e5f6 schema: $ref: "#/components/schemas/ReposNotesRefsListResponse" description: Notes refs in lexical order. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: List Notes Refs tags: - Notes x-deprecation-message: Use `/api/repos/{repo_name}/notes/refs` instead. x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable /api/v1/repos/pull-upstream: post: deprecated: true description: |- Trigger a sync from the configured upstream of the repository. This only works for repositories that have an `upstream`. `POST /api/repos/{repo_name}/upstream/pull` replaces this endpoint. It takes the same request body and returns the same response. Scope: `git:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/upstream/pull` instead. operationId: pull_upstream_legacy requestBody: content: application/json: schema: $ref: "#/components/schemas/ReposUpstreamPullRequest" description: "Deprecated: send no body. Its fields have no effect: a pull syncs every branch and tag of the upstream." responses: "202": content: application/json: example: message: Repository sync initiated successfully schema: $ref: "#/components/schemas/ReposUpstreamPullResponse" description: Sync trigger accepted. The repository sync runs asynchronously. "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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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 summary: Pull Upstream tags: - Repositories x-deprecation-message: Use `/api/repos/{repo_name}/upstream/pull` instead. x-permission-scopes: - git:write x-requires-repo-scope: true x-stability: stable /api/v1/repos/reset-commits: post: deprecated: true description: |- Create a new commit that resets a branch back to a specific commit SHA while preserving normal Git history. This is an alias of `restore-commit` and is served by the same handler; prefer `restore-commit` for new integrations. A successful reset responds with `201 Created`. Ref-level outcomes are reported in `result.status` and `result.success`, not by the status code alone, and failures raised by the restore itself come back in that same restore-result body. The problem-details schemas below describe gateway-level rejections such as `401`, `403` and `429`. Scope: `git:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/reset-commits` instead. operationId: reset_commits_legacy requestBody: content: application/x-ndjson: example: | {"metadata":{"target_branch":"main","base_ref":"abc123def4567890abc123def4567890abc123de","expected_target_sha":"0123456789abcdef0123456789abcdef01234567","commit_message":"Reset branch","author":{"name":"Docs Bot","email":"docs@example.com"}}} schema: contentSchema: maxItems: 1 minItems: 1 prefixItems: - additionalProperties: false properties: metadata: $ref: "#/components/schemas/ReposCommitsRestoreRequest" required: - metadata type: object type: array description: NDJSON stream containing one `metadata` object. type: string description: Send a single NDJSON metadata line describing the branch to restore and the commit SHA to restore it to. The handler requires this line and rejects an empty body with `400`, even though the published contract leaves it optional. responses: "200": content: application/json: schema: $ref: "#/components/schemas/ReposCommitsRestoreResponse" description: Documented for backwards compatibility with clients written against the original `reset-commits` contract. Successful resets return `201 Created`; see the `201` response. "201": content: application/json: schema: $ref: "#/components/schemas/ReposCommitsRestoreResponse" description: Restore commit created and the branch reset. This is the status a successful reset returns. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: base_ref (d34db33fd34db33fd34db33fd34db33fd34db33f) does not match current head c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 code: ref_guard_failed error: base_ref (d34db33fd34db33fd34db33fd34db33fd34db33f) does not match current head c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 guard: expected_target_sha current_sha: c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 commit: null result: target_branch: main branch: main old_sha: c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 new_sha: "" success: false status: conflict message: base_ref (d34db33fd34db33fd34db33fd34db33fd34db33f) does not match current head c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 schema: $ref: "#/components/schemas/RestoreCommitRefGuardProblemDetails" description: "Conflict. When `expected_target_sha` is not the tip of the branch, the body is `application/problem+json` with the code `ref_guard_failed`: `guard` names the guard, and `current_sha` is the tip of the branch, which `result.old_sha` repeats. The body keeps the members of the failure body, and `result.status` is `conflict`." "412": content: application/json: example: commit: null result: message: branch already matches target commit new_sha: "" old_sha: "" status: precondition_failed success: false target_branch: "" schema: $ref: "#/components/schemas/ReposCommitsRestoreResponse" description: "Storage rejected the restore because the branch cannot move as requested: the branch already points at `base_ref`, the restore would produce no change, or `base_ref` is not an ancestor of the current tip. The body carries the restore result with `result.status` set to `precondition_failed`. A repository with a GitHub upstream also gets `412` when the write cannot reach GitHub: the GitHub App has no usable private key, GitHub does not give the App access to the repository, or GitHub refuses the push with `401`, `403` or `404`. Then `result.status` is `failed` and `result.message` explains the failure." "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 "502": content: application/json: example: commit: null result: message: upstream Git server request failed; the push may or may not have been applied, check the branch before retrying new_sha: "" old_sha: "" status: internal success: false target_branch: "" schema: $ref: "#/components/schemas/ReposCommitsRestoreResponse" description: A storage node, the upstream Git server or GitHub failed or could not be reached. When the push request to the upstream failed or got a server error, the write may have been applied; check the branch before retrying. `result.status` is `failed` when GitHub answers the push with a server error, and `commit` is the commit that the write tried to set. `result.status` is `internal` and `commit` is `null` when the push request fails, or when GitHub answers with a server error or cannot be reached while the gateway gets its GitHub token. `result.message` explains the failure. "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 summary: Reset Branch to Commit tags: - Commits x-deprecation-message: Use `/api/repos/{repo_name}/reset-commits` instead. x-permission-scopes: - git:write x-requires-repo-scope: true x-stability: stable /api/v1/repos/restore-commit: post: deprecated: true description: |- Create a new commit that resets a branch back to a specific commit SHA while preserving normal Git history. Ref-level outcomes are reported in `result.status` and `result.success`, not by the status code alone, and failures raised by the restore itself come back in that same restore-result body. The problem-details schemas below describe gateway-level rejections such as `401`, `403` and `429`. Scope: `git:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/restore-commit` instead. operationId: restore_commit_legacy requestBody: content: application/x-ndjson: example: | {"metadata":{"target_branch":"main","base_ref":"abc123def4567890abc123def4567890abc123de","expected_target_sha":"0123456789abcdef0123456789abcdef01234567","commit_message":"Reset branch","author":{"name":"Docs Bot","email":"docs@example.com"}}} schema: contentSchema: maxItems: 1 minItems: 1 prefixItems: - additionalProperties: false properties: metadata: $ref: "#/components/schemas/ReposCommitsRestoreRequest" required: - metadata type: object type: array description: NDJSON stream containing one `metadata` object. type: string description: Send a single NDJSON metadata line describing the branch to restore and the commit SHA to restore it to. required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/ReposCommitsRestoreResponse" description: Restore commit created successfully. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: base_ref (d34db33fd34db33fd34db33fd34db33fd34db33f) does not match current head c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 code: ref_guard_failed error: base_ref (d34db33fd34db33fd34db33fd34db33fd34db33f) does not match current head c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 guard: expected_target_sha current_sha: c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 commit: null result: target_branch: main branch: main old_sha: c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 new_sha: "" success: false status: conflict message: base_ref (d34db33fd34db33fd34db33fd34db33fd34db33f) does not match current head c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 schema: $ref: "#/components/schemas/RestoreCommitRefGuardProblemDetails" description: "Conflict. When `expected_target_sha` is not the tip of the branch, the body is `application/problem+json` with the code `ref_guard_failed`: `guard` names the guard, and `current_sha` is the tip of the branch, which `result.old_sha` repeats. The body keeps the members of the failure body, and `result.status` is `conflict`." "412": content: application/json: example: commit: null result: message: branch already matches target commit new_sha: "" old_sha: "" status: precondition_failed success: false target_branch: "" schema: $ref: "#/components/schemas/ReposCommitsRestoreResponse" description: "Storage rejected the restore because the branch cannot move as requested: the branch already points at `base_ref`, the restore would produce no change, or `base_ref` is not an ancestor of the current tip. The body carries the restore result with `result.status` set to `precondition_failed`. A repository with a GitHub upstream also gets `412` when the write cannot reach GitHub: the GitHub App has no usable private key, GitHub does not give the App access to the repository, or GitHub refuses the push with `401`, `403` or `404`. Then `result.status` is `failed` and `result.message` explains the failure." "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 "502": content: application/json: example: commit: null result: message: upstream Git server request failed; the push may or may not have been applied, check the branch before retrying new_sha: "" old_sha: "" status: internal success: false target_branch: "" schema: $ref: "#/components/schemas/ReposCommitsRestoreResponse" description: A storage node, the upstream Git server or GitHub failed or could not be reached. When the push request to the upstream failed or got a server error, the write may have been applied; check the branch before retrying. `result.status` is `failed` when GitHub answers the push with a server error, and `commit` is the commit that the write tried to set. `result.status` is `internal` and `commit` is `null` when the push request fails, or when GitHub answers with a server error or cannot be reached while the gateway gets its GitHub token. `result.message` explains the failure. "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 summary: Restore Commit tags: - Commits x-deprecation-message: Use `/api/repos/{repo_name}/restore-commit` instead. x-permission-scopes: - git:write x-requires-repo-scope: true x-stability: stable /api/v1/repos/tags: delete: deprecated: true description: |- Delete a tag from the repository. The server resolves the stored ref correctly for both lightweight and annotated tags. Scopes: `git:read` and `git:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/tags/{tag_name}` instead. operationId: delete_tag_legacy requestBody: content: application/json: example: name: v1.0.0 schema: $ref: "#/components/schemas/ReposTagsDeleteRequestLegacy" description: Delete a lightweight or annotated tag by name. required: true responses: "200": content: application/json: example: message: tag deleted name: v1.0.0 schema: $ref: "#/components/schemas/ReposTagsDeleteResponse" description: Tag deletion result. "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: schema: $ref: "#/components/schemas/ProblemDetails" description: Conflict "412": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" description: "`412` has more than one cause. Storage returns `precondition_failed` for a write-specific reason, such as a merge with no common ancestor between source and target, a merge target that moved off a fast-forward under the `ff_only` strategy, or a branch creation whose target cannot be fast-forwarded. A repository with a GitHub upstream also gets `412` when the write cannot reach GitHub: the code is `github_app_not_configured` when the GitHub App has no usable private key, `github_repository_inaccessible` when GitHub does not give the App access to the repository, and `precondition_failed` when GitHub refuses the push for another reason, such as an archived repository. `detail` explains the failure." "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 "502": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" description: A storage node, the upstream Git server or GitHub failed or could not be reached. When the push request to the upstream failed or got a server error, the write may have been applied; check the branch before retrying. "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:read - git:write summary: Delete Tag tags: - Tags x-deprecation-message: Use `/api/repos/{repo_name}/tags/{tag_name}` instead. x-permission-scopes: - git:read - git:write x-request-validation-profile: delete_tag x-requires-repo-scope: true x-stability: stable get: deprecated: true description: |- List tags in lexical order with cursor pagination. The returned `sha` is the dereferenced commit SHA, even for annotated tags. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/tags` instead. operationId: list_tags_legacy parameters: - description: Pagination cursor returned by a previous `list_tags` response. example: t_def456 in: query name: cursor schema: type: string - description: Maximum number of tags to return. Defaults to 20. example: 20 in: query name: limit schema: default: 20 type: integer responses: "200": content: application/json: example: has_more: true next_cursor: MTcwNzU3MzQ1MTAwMDAwMDAwMHxyZXBvXzlhNGMyMWY tags: - cursor: t_abc123 name: v1.0.0 sha: a1b2c3d4e5f6 schema: $ref: "#/components/schemas/ReposTagsListResponse" description: Repository tags in lexical order. "400": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" 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: schema: $ref: "#/components/schemas/ProblemDetails" description: 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:read summary: List Tags tags: - Tags x-deprecation-message: Use `/api/repos/{repo_name}/tags` instead. x-permission-scopes: - git:read x-requires-repo-scope: true x-stability: stable post: deprecated: true description: |- Create a lightweight tag pointing to a specific commit. Annotated tags are not created through this endpoint. Scope: `git:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/tags` instead. operationId: create_tag_legacy requestBody: content: application/json: example: name: v1.0.0 ref: main target: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2 schema: $ref: "#/components/schemas/ReposTagsCreateRequest" description: Create a lightweight tag that points to an exact commit SHA. required: true responses: "200": content: application/json: example: message: tag created name: v1.0.0 sha: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2 schema: $ref: "#/components/schemas/ReposTagsCreateResponse" description: Tag creation result. "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: schema: $ref: "#/components/schemas/ProblemDetails" description: Conflict "412": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" description: "`412` has more than one cause. Storage returns `precondition_failed` for a write-specific reason, such as a merge with no common ancestor between source and target, a merge target that moved off a fast-forward under the `ff_only` strategy, or a branch creation whose target cannot be fast-forwarded. A repository with a GitHub upstream also gets `412` when the write cannot reach GitHub: the code is `github_app_not_configured` when the GitHub App has no usable private key, `github_repository_inaccessible` when GitHub does not give the App access to the repository, and `precondition_failed` when GitHub refuses the push for another reason, such as an archived repository. `detail` explains the failure." "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 "502": content: application/json: schema: $ref: "#/components/schemas/ProblemDetails" application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" description: A storage node, the upstream Git server or GitHub failed or could not be reached. When the push request to the upstream failed or got a server error, the write may have been applied; check the branch before retrying. "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 summary: Create Tag tags: - Tags x-deprecation-message: Use `/api/repos/{repo_name}/tags` instead. x-permission-scopes: - git:write x-request-validation-profile: create_tag x-requires-repo-scope: true x-stability: stable 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. 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 webhooks: push: post: description: Sent when a Git ref is updated in a repository. Each updated ref produces a separate event. operationId: webhooks-push parameters: - description: The event type for this delivery. in: header name: X-Pierre-Event required: true schema: enum: - push type: string - description: Signature in the form t=,sha256=. Verify HMAC-SHA256 with the subscription secret over the timestamp, a period, and the raw request body. Check the timestamp to reject old deliveries. in: header name: X-Pierre-Signature required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/GitPushEvent" description: The push event payload. required: true responses: 2XX: description: The receiver accepted the delivery. Return any 2xx status to acknowledge it. security: [] summary: Git ref updated tags: - Webhooks repo.sync.failed: post: description: Sent when a repository sync run fails, including failures after retries are exhausted and infrastructure failures. Internal cancellations do not produce this event. run_count includes the run that just finished. operationId: webhooks-repo-sync-failed parameters: - description: The event type for this delivery. in: header name: X-Pierre-Event required: true schema: enum: - repo.sync.failed type: string - description: Signature in the form t=,sha256=. Verify HMAC-SHA256 with the subscription secret over the timestamp, a period, and the raw request body. Check the timestamp to reject old deliveries. in: header name: X-Pierre-Signature required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/GitSyncFailedEvent" description: The repo.sync.failed event payload. required: true responses: 2XX: description: The receiver accepted the delivery. Return any 2xx status to acknowledge it. security: [] summary: Repository sync failed tags: - Webhooks repo.sync.started: post: description: Sent when a repository sync run begins, before the upstream fetch starts. run_count counts previously completed runs. operationId: webhooks-repo-sync-started parameters: - description: The event type for this delivery. in: header name: X-Pierre-Event required: true schema: enum: - repo.sync.started type: string - description: Signature in the form t=,sha256=. Verify HMAC-SHA256 with the subscription secret over the timestamp, a period, and the raw request body. Check the timestamp to reject old deliveries. in: header name: X-Pierre-Signature required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/GitSyncStartedEvent" description: The repo.sync.started event payload. required: true responses: 2XX: description: The receiver accepted the delivery. Return any 2xx status to acknowledge it. security: [] summary: Repository sync started tags: - Webhooks repo.sync.succeeded: post: description: Sent when a repository sync run completes successfully. run_count includes the run that just finished. operationId: webhooks-repo-sync-succeeded parameters: - description: The event type for this delivery. in: header name: X-Pierre-Event required: true schema: enum: - repo.sync.succeeded type: string - description: Signature in the form t=,sha256=. Verify HMAC-SHA256 with the subscription secret over the timestamp, a period, and the raw request body. Check the timestamp to reject old deliveries. in: header name: X-Pierre-Signature required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/GitSyncSucceededEvent" description: The repo.sync.succeeded event payload. required: true responses: 2XX: description: The receiver accepted the delivery. Return any 2xx status to acknowledge it. security: [] summary: Repository sync succeeded tags: - Webhooks