API reference
Repository contents
A repository's settings, files, commits, diffs and insights.
The routes behind the Git portal. To clone and push, use Git over HTTPS.
GET /v1/orgs/:orgId/repos/:name/branches
Branches with their last commit.
Auth: user access token or platform agent key · Scope: git:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:name | Repository name. |
Response 200
{
defaultBranch: null | string
branches: {
name: string
commit: {
id: string
message: string
author: {
name?: string
email?: string
date?: number
}
committedAt: null | number
}
isDefault: boolean
protected: boolean
openPull: null | number
}[]
}Errors
| Status | Message |
|---|---|
404 | Repository not found |
GET /v1/orgs/:orgId/repos/:name/branches/divergence
Commits ahead of / behind the default branch, per name (repeatable), bounded.
Auth: user access token or platform agent key · Scope: git:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:name | Repository name. |
Response 200
{
base: null | string
divergence: {}
}
| {
base: null | string
divergence: {
[key: string]: null | {
ahead: number
behind: number
exact: boolean
}
}
}Errors
| Status | Message |
|---|---|
404 | Repository not found |
404 | Not found |
404 | Commit not found |
POST /v1/orgs/:orgId/repos/:name/branches
Creates a branch from a branch, tag or commit.
Auth: user access token or platform agent key · Scopes: git:read, git:write
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:name | Repository name. |
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | Yes | 1–256 characters; trimmed |
from | string | Yes | 1–256 characters |
Response 201
{
branch: {
name: string
commitId: string
}
}Errors
| Status | Message |
|---|---|
400 | That commit doesn't exist. |
404 | Repository not found |
404 | Not found |
404 | Branch or tag not found |
409 | A branch with this name already exists. |
409 | A tag with this name already exists. |
DELETE /v1/orgs/:orgId/repos/:name/branches
Deletes the branch name. The default branch can't be deleted.
Auth: user access token or platform agent key · Scopes: git:read, git:write
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:name | Repository name. |
| Query parameter | Type | Required | Notes |
|---|---|---|---|
name | string | Yes | 1–256 characters |
Response 200
{
deleted: string
commitId: null | string
}Errors
| Status | Message |
|---|---|
400 | The default branch can't be deleted. |
404 | Repository not found |
404 | Branch not found. |
GET /v1/orgs/:orgId/repos/:name/tags
Tags and their commits. Create tags by pushing them with git.
Auth: user access token or platform agent key · Scope: git:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:name | Repository name. |
Response 200
{
tags: {
name: string
annotated: boolean
object: string
commit: {
id: string
message: string
author: {
name?: string
email?: string
date?: number
}
committedAt: null | number
}
}[]
}Errors
| Status | Message |
|---|---|
404 | Repository not found |
POST /v1/orgs/:orgId/repos/:name/contents
Commits file changes from the web: add or replace (base64 content), move or delete files, on branch or a newBranch. Fails if the branch moved since parentCommitId.
Auth: user access token or platform agent key · Scopes: git:read, git:write
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:name | Repository name. |
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
branch | string | Yes | 1–256 characters |
parentCommitId | string | No | matches ^[0-9a-f]{40}$ |
message | string | Yes | 1–1,000 characters; trimmed |
description | string | No | up to 20,000 characters |
newBranch | string | No | up to 256 characters; trimmed |
changes | (object | object | object)[] | Yes | 1–100 items |
Response 201
{
commitId?: string
branch: string
}Errors
| Status | Message |
|---|---|
400 | …: … |
400 | … is changed more than once. |
400 | parentCommitId is required. |
403 | … is protected. Commit to a new branch and open a pull request. |
404 | Repository not found |
404 | Branch … not found. |
409 | A branch named … already exists. |
409 | A tag named … already exists. |
413 | Web commits can change up to 100 files and 4 MB of content. Push larger changes with git. |
GET /v1/orgs/:orgId/repos/:name/contents/raw
File bytes; the portal's /raw route serves them with the right type.
Auth: user access token or platform agent key · Scope: git:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:name | Repository name. |
| Query parameter | Type | Required | Notes |
|---|---|---|---|
ref | string | Yes | at least 1 character |
path | string | Yes | at least 1 character |
Response 200 with no body.
Errors
| Status | Message |
|---|---|
404 | Repository not found |
404 | Not found |
413 | This file is too large to show here. Clone the repository to get it. |
GET /v1/orgs/:orgId/repos/:name/contents/files
Every file path at a ref (for the file finder and archives), bounded.
Auth: user access token or platform agent key · Scope: git:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:name | Repository name. |
| Query parameter | Type | Required | Notes |
|---|---|---|---|
ref | string | Yes | at least 1 character |
Response 200
{
files: {
path: string
blobId: string
mode: string
type: "file" | "link"
}[]
truncated: boolean
commitId: string
}Errors
| Status | Message |
|---|---|
404 | Repository not found |
404 | Not found |
404 | Branch or tag not found |
POST /v1/orgs/:orgId/repos/:name/contents/blobs
Blob contents (base64) in request order, as many as fit in one response; the caller asks again for the rest. Blobs too large for a response are marked tooLarge.
Auth: user access token or platform agent key · Scope: git:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:name | Repository name. |
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
ids | string[] | Yes | 1–50 items; each matches ^[0-9a-f]{40}$ |
Response 200
{
blobs: {
id: string
content?: string
tooLarge?: true
}[]
}Errors
| Status | Message |
|---|---|
404 | Repository not found |
GET /v1/orgs/:orgId/repos/:name/compare
Commits and changed files on head since it diverged from base, whether it merges cleanly, and any open pull request between them.
Auth: user access token or platform agent key · Scope: git:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:name | Repository name. |
| Query parameter | Type | Required | Notes |
|---|---|---|---|
base | string | Yes | 1–256 characters |
head | string | Yes | 1–256 characters |
Response 200
{
mergeBase: string
status: string
aheadBy: number
behindBy: number
exact: true
commits: []
commitsTruncated: false
files: []
total: number
truncated: false
mergeOptions: []
conflicts: []
base: {
ref: string
commitId: string
}
head: {
ref: string
commitId: string
}
pull: null | number
}
| {
mergeOptions: ("fast-forward" | "squash" | "three-way")[]
conflicts: {
path: string
conflicts: number
binary: boolean
kind: "type" | "content" | "mode"
}[]
files: {
path: string
change: "deleted" | "added" | "modified"
additions: number
deletions: number
binary?: boolean
collapsed?: boolean
hunks: {
oldStart: number
oldLines: number
newStart: number
newLines: number
lines: string[]
}[]
}[]
total: number
truncated: boolean
mergeBase: null | string
status: string
aheadBy: number
behindBy: number
exact: boolean
commits: {
id: string
message: string
author: {
name?: string
email?: string
date?: number
}
parents: string[]
committedAt?: number
}[]
commitsTruncated: boolean
base: {
ref: string
commitId: string
}
head: {
ref: string
commitId: string
}
pull: null | number
}Errors
| Status | Message |
|---|---|
400 | These branches are too far apart to compare. |
404 | Repository not found |
404 | Not found |
404 | Branch or tag not found |
404 | Branch or commit not found. |
404 | Commit not found |
GET /v1/orgs/:orgId/repos/:name/labels
The repository's labels.
Auth: user access token or platform agent key · Scope: git:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:name | Repository name. |
Response 200
{
labels: {
name: string
color: string
description: string
}[]
}Errors
| Status | Message |
|---|---|
404 | Repository not found |
PUT /v1/orgs/:orgId/repos/:name/labels
Creates or updates a label by name.
Auth: user access token or platform agent key · Scopes: git:read, git:write
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:name | Repository name. |
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | Yes | 1–50 characters; trimmed |
color | "chart-1" | "chart-2" | "chart-3" | "chart-4" | "chart-5" | "destructive" | "primary" | "muted-foreground" | Yes | |
description | string | No | up to 100 characters; trimmed |
Response 200
{
label: {
name: string
color: string
description: string
}
}Errors
| Status | Message |
|---|---|
400 | A repository can have up to 100 labels. |
404 | Repository not found |
DELETE /v1/orgs/:orgId/repos/:name/labels
Deletes the label name and removes it from issues and pull requests.
Auth: user access token or platform agent key · Scopes: git:read, git:write
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:name | Repository name. |
| Query parameter | Type | Required | Notes |
|---|---|---|---|
name | string | Yes | 1–50 characters |
Response 204 with no body.
Errors
| Status | Message |
|---|---|
404 | Repository not found |
GET /v1/orgs/:orgId/repos
The organization's repositories with their default branch, language and last update.
Auth: user access token or platform agent key · Scope: git:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
Response 200
{
repos: {
name: string
resourceId: string
description: null | string
defaultBranch: null | string
createdAt?: number
updatedAt?: number
language?: null | string
}[]
}GET /v1/orgs/:orgId/repos/-/available
Whether name can be used for a new repository, and why not.
Auth: user access token or platform agent key · Scope: git:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
| Query parameter | Type | Required | Notes |
|---|---|---|---|
name | string | Yes | up to 100 characters |
Response 200
{
name: string
available: boolean
reason: null | string
}GET /v1/orgs/:orgId/repos/-/people
Org members, for assignees and @mentions.
Auth: user access token or platform agent key · Scope: git:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
Response 200
{
people: {
userId: string
name: null | string
email: string
handle: string
}[]
}POST /v1/orgs/:orgId/repos
Creates a repository, optionally with a first commit holding a README, a .gitignore template (Node, Next.js, Python, Go or Rust) and a license (MIT or Apache 2.0).
Auth: user access token or platform agent key · Scope: git:write
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
Request body
| Field | Type | Required | Default | Notes |
|---|---|---|---|---|
name | string | Yes | matches ^[a-z0-9][a-z0-9-]{1,38}[a-z0-9]$ | |
description | string | No | up to 1,000 characters; trimmed | |
readme | boolean | No | false | |
gitignore | `` | No | ||
license | `` | No | ||
defaultBranch | string | No | "main" | trimmed |
Response 201
{
repo: {
defaultBranch: string
empty: boolean
type: "repository" | "database" | "bucket"
name: string
status?: "error" | "active" | "creating" | "deleting"
createdAt?: number
updatedAt?: number
region: string
orgId: string
createdBy: string
projectId?: string
location: string
resourceId: string
arn?: string
physicalName: string
}
}Errors
| Status | Message |
|---|---|
400 | Unknown location: undefined |
409 | A repository with this name already exists. |
502 | Could not create the repository. |
502 | Could not create the initial commit. |
POST /v1/orgs/:orgId/repos/:name/rename
Renames a repository. Clone URLs change with it.
Auth: user access token or platform agent key · Scope: git:write
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:name | Repository name. |
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | Yes | matches ^[a-z0-9][a-z0-9-]{1,38}[a-z0-9]$ |
Response 200
{
name: string
}Errors
| Status | Message |
|---|---|
404 | Repository not found |
409 | A repository with this name already exists. |
DELETE /v1/orgs/:orgId/repos/:name
Deletes a repository with its history. confirm must be the repository name.
Auth: user access token or platform agent key · Scope: git:write
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:name | Repository name. |
| Query parameter | Type | Required | Notes |
|---|---|---|---|
confirm | string | Yes |
Response 204 with no body.
Errors
| Status | Message |
|---|---|
400 | Type the repository name to confirm. |
404 | Repository not found |
GET /v1/orgs/:orgId/repos/:name/protection
The default branch's protection: how many approvals pull requests into it need.
Auth: user access token or platform agent key · Scope: git:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:name | Repository name. |
Response 200
{
requiredApprovals: number
branch: null | string
}Errors
| Status | Message |
|---|---|
404 | Repository not found |
PUT /v1/orgs/:orgId/repos/:name/protection
Sets how many approvals (0–10) pull requests into the default branch need before they can be merged. 0 removes the rule.
Auth: user access token or platform agent key · Scope: git:write
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:name | Repository name. |
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
requiredApprovals | integer | Yes | 0–10 |
Response 200
{
requiredApprovals: number
branch: string
}Errors
| Status | Message |
|---|---|
400 | Push a branch before protecting it. |
404 | Repository not found |
GET /v1/orgs/:orgId/repos/:name
Repository details: description, default branch, branches and open issue and pull request counts.
Auth: user access token or platform agent key · Scope: git:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:name | Repository name. |
Response 200
{
resourceId: string
description: null | string
defaultBranch: null | string
branches: string[]
tags: string[]
initialBranch: null | string
protectedBranch: null | string
createdAt?: string
updatedAt?: string
openIssues: number
openPulls: number
}Errors
| Status | Message |
|---|---|
404 | Repository not found |
404 | Not found |
PATCH /v1/orgs/:orgId/repos/:name
Updates the description or the default branch.
Auth: user access token or platform agent key · Scopes: git:read, git:write
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:name | Repository name. |
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
description | string | No | up to 1,000 characters |
defaultBranch | string | No | 1–255 characters |
Response 200
{
ok: true
}Errors
| Status | Message |
|---|---|
400 | Branch not found. |
404 | Repository not found |
GET /v1/orgs/:orgId/repos/:name/tree
Lists a directory at a branch or commit.
Auth: user access token or platform agent key · Scope: git:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:name | Repository name. |
| Query parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
ref | string | No | "main" | |
path | string | No | "/" |
Response 200
{
commitId?: string
path: string
entries: {
type: "dir"
name: string
path: string
} | {
type: "file"
name: string
path: string
} | {
type: "link"
name: string
path: string
} | {
type: "submodule"
name: string
path: string
}[]
}Errors
| Status | Message |
|---|---|
404 | Repository not found |
404 | Not found |
GET /v1/orgs/:orgId/repos/:name/blob
A file at a branch or commit. text is null for binary files and files over 1 MB. path is required.
Auth: user access token or platform agent key · Scope: git:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:name | Repository name. |
| Query parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
path | string | No | ||
ref | string | No | "main" |
Response 200
{
path: string
size: number
commitId?: string
blobId?: string
mode?: "EXECUTABLE" | "NORMAL" | "SYMLINK"
text: null | string
}Errors
| Status | Message |
|---|---|
400 | path is required |
404 | Repository not found |
404 | Not found |
GET /v1/orgs/:orgId/repos/:name/commits
First-parent history, newest first. With path, only commits that touch that file or folder (scanned reports how far the search went). Pass the returned next as cursor to continue.
Auth: user access token or platform agent key · Scope: git:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:name | Repository name. |
| Query parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
ref | string | No | "main" | at least 1 character |
cursor | string | No | matches ^[0-9a-f]{40}$ | |
limit | integer | No | 20 | 1–50; coerced from a string |
path | string | No |
Response 200
{
commits: {
id: string
message: string
author: {
name?: string
email?: string
date?: number
}
parents: string[]
committedAt?: number
}[]
next: null | string
scanned: number
}
| {
commits: {
id: string
message: string
author: {
name?: string
email?: string
date?: number
}
parents: string[]
committedAt?: number
}[]
next: null | string
}Errors
| Status | Message |
|---|---|
404 | Repository not found |
404 | Not found |
404 | Branch or tag not found |
404 | Commit not found |
GET /v1/orgs/:orgId/repos/:name/last-commits
The last commit that touched each entry of a folder. complete is false while more entries can be resolved by asking again; null means older than the search reached.
Auth: user access token or platform agent key · Scope: git:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:name | Repository name. |
| Query parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
ref | string | No | "main" | at least 1 character |
path | string | No | "" |
Response 200
{
head: string
latest: null | {
id: string
message: string
author: {
name?: string
date?: number
}
}
entries: {
[key: string]: null | {
id: string
message: string
author: {
name?: string
date?: number
}
}
}
complete: boolean
scanned: number
path: string
}Errors
| Status | Message |
|---|---|
404 | Repository not found |
404 | Not found |
404 | Branch or tag not found |
404 | Commit not found |
GET /v1/orgs/:orgId/repos/:name/last-commit
The last commit that touched a file.
Auth: user access token or platform agent key · Scope: git:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:name | Repository name. |
| Query parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
ref | string | No | "main" | at least 1 character |
path | string | Yes | at least 1 character |
Response 200
{
head: string
commit: null | {
id: string
message: string
author: {
name?: string
date?: number
}
}
complete: boolean
scanned: number
path: string
}Errors
| Status | Message |
|---|---|
404 | Repository not found |
404 | Not found |
404 | Branch or tag not found |
404 | File not found |
GET /v1/orgs/:orgId/repos/:name/commits/:sha
A commit and its changes against its first parent.
Auth: user access token or platform agent key · Scope: git:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:name | Repository name. |
:sha | Full commit id or branch name. |
Response 200
{
files: {
path: string
change: "deleted" | "added" | "modified"
additions: number
deletions: number
binary?: boolean
collapsed?: boolean
hunks: {
oldStart: number
oldLines: number
newStart: number
newLines: number
lines: string[]
}[]
}[]
total: number
truncated: boolean
commit: {
id: string
message: string
author: {
name?: string
email?: string
date?: number
}
parents: string[]
committedAt?: number
}
}Errors
| Status | Message |
|---|---|
404 | Repository not found |
404 | Not found |
404 | Commit not found |
404 | Branch or tag not found |
GET /v1/orgs/:orgId/repos/:name/insights
Contributors, weekly commit activity and languages for a branch (the default branch when ref is omitted).
Auth: user access token or platform agent key · Scope: git:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:name | Repository name. |
| Query parameter | Type | Required | Notes |
|---|---|---|---|
ref | string | No |
Response 200
{
ref: string
head: string
commitsAnalyzed: number
historyComplete: boolean
since: null | number
contributors: {
name: string
email?: string
commits: number
lastAt?: number
}[]
weeks: {
week: number
commits: number
}[]
languages: {
language: string
files: number
share: number
}[]
languagesComplete: boolean
}Errors
| Status | Message |
|---|---|
404 | Repository not found |
404 | Not found |
404 | Branch or tag not found |
404 | Commit not found |