API reference

Pull requests

Open, comment on, merge and close pull requests.

`GET /v1/orgs/:orgId/repos/:name/pulls/:number/review`

Inline review comments with their file and line, approvals, and how many approvals the pull request still needs.

Auth: user access token or platform agent key · Scope: git:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:name`	Repository name.
`:number`	Issue or pull request number.

Response 200

{
  revisionId: string
  base: null | string
  head: null | string
  approvals: {
    id: null | string
    name: string
    email: null | string
  }[]
  required: number
  rules: {
    name: string
    required: number
    fromTemplate: boolean
    satisfied: boolean
  }[]
  approved: boolean
  overridden: boolean
  viewerApproved: boolean
  threads: {
    id: string
    path: null | string
    line: null | number
    side: "old" | "new"
    beforeCommitId: null | string
    afterCommitId: null | string
    outdated: boolean
    comments: {
      id: string
      body: string
      author: {
        id: null | string
        name: string
        email: null | string
      }
      createdAt: null | number
      updatedAt: null | number
      deleted: boolean
    }[]
  }[]
}

Errors

Status	Message
`400`	These branches are too far apart to compare.
`404`	Repository not found
`404`	Pull request not found
`404`	Not found
`404`	Branch or commit not found.

`POST /v1/orgs/:orgId/repos/:name/pulls/:number/review/comments`

Adds a review comment: a new thread on a line of the diff (path, line, side), or a reply (inReplyTo).

Auth: user access token or platform agent key · Scope: git:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:name`	Repository name.
`:number`	Issue or pull request number.

Request body

Field	Type	Required	Default	Notes
`body`	`string`	Yes		1–10,240 characters; trimmed
`inReplyTo`	`string`	No		1–256 characters
`path`	`string`	No		1–4,096 characters
`line`	`integer`	No		≥ 1
`side`	`"old" \| "new"`	No	`"new"`
`base`	`string`	No		matches `^[0-9a-f]{40}$`
`head`	`string`	No		matches `^[0-9a-f]{40}$`

Response 201

{
  comment: {
    id: null | string
  }
}

Errors

Status	Message
`400`	These branches are too far apart to compare.
`400`	Choose a line to comment on.
`404`	Repository not found
`404`	Pull request not found
`404`	Not found
`404`	Branch or commit not found.
`409`	This pull request has no changes to comment on.

`POST /v1/orgs/:orgId/repos/:name/pulls/:number/approval`

Approves the pull request's current revision, or withdraws your approval. Authors can't approve their own.

Auth: user access token or platform agent key · Scopes: git:read, git:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:name`	Repository name.
`:number`	Issue or pull request number.

Request body

Field	Type	Required	Notes
`approve`	`boolean`	Yes
`revisionId`	`string`	No	at least 1 character

Response 200

{
  approved: boolean
}

Errors

Status	Message
`403`	You can't approve your own pull request.
`404`	Repository not found
`404`	Pull request not found
`404`	Not found
`409`	This pull request is closed.
`409`	New commits were pushed. Review the latest changes, then approve.
`409`	This pull request has the maximum number of approvals.

`POST /v1/orgs/:orgId/repos/:name/pulls/:number/reopen`

CodeCommit can't reopen a closed pull request; a new one replaces it under the same number.

Auth: user access token or platform agent key · Scope: git:read · Allowed: Author, or git:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:name`	Repository name.
`:number`	Issue or pull request number.

Response 200

{
  state: string
}

Errors

Status	Message
`403`	Only the author or members with git:write can reopen this pull request.
`404`	Repository not found
`404`	Pull request not found
`404`	Not found
`409`	Merged pull requests can't be reopened.
`409`	Pull request #… is already open for these branches.
`409`	The branch … or … no longer exists. Push it again to reopen.
`409`	The branches point at the same commit; there is nothing to merge.
`409`	Too many open pull requests in this repository.
`409`	The pull request changed. Reload and try again.

`GET /v1/orgs/:orgId/repos/:name/pulls`

Lists pull requests in one state, newest first. Listing open pull requests also settles any that were merged or closed outside the portal.

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
`state`	`"open" \| "closed" \| "merged"`	No	`"open"`
`cursor`	`string`	No
`label`	`string`	No		up to 50 characters
`author`	`string`	No		up to 64 characters
`assignee`	`string`	No		up to 64 characters

Response 200

{
  pulls: {
    number: number
    createdAt?: number
    updatedAt?: number
    orgId: string
    repoId: string
    labels?: string[]
    title: string
    state?: "open" | "closed" | "merged"
    assignees?: string[]
    comments?: number
    closedAt?: number
    closedBy?: string
    authorId: string
    authorEmail?: string
    authorName?: string
    pullRequestId: string
    sourceBranch: string
    targetBranch: string
    mergeCommitId?: string
    previousPullRequestIds?: string[]
  }[]
  cursor: null | string
}
| {
  pulls: {
    number: number
    createdAt?: number
    updatedAt?: number
    orgId: string
    repoId: string
    labels?: string[]
    title: string
    state?: "open" | "closed" | "merged"
    assignees?: string[]
    comments?: number
    closedAt?: number
    closedBy?: string
    authorId: string
    authorEmail?: string
    authorName?: string
    pullRequestId: string
    sourceBranch: string
    targetBranch: string
    mergeCommitId?: string
    previousPullRequestIds?: string[]
  }[]
  cursor: null
}

Errors

Status	Message
`404`	Repository not found
`404`	Not found
`404`	Pull request not found

`POST /v1/orgs/:orgId/repos/:name/pulls`

Opens a pull request that merges source into target.

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	Default	Notes
`title`	`string`	Yes		1–150 characters; trimmed
`description`	`string`	No	`""`	up to 10,240 characters
`source`	`string`	Yes		1–255 characters
`target`	`string`	Yes		1–255 characters
`labels`	`string[]`	No	`[]`	up to 10 items; each 1–50 characters, trimmed
`assignees`	`string[]`	No	`[]`	up to 10 items; each 1–64 characters

Response 201

{
  pull: {
    authorId: string
    authorEmail: string
    authorName?: string
    repoId: string
    orgId: string
    number: number
    pullRequestId: string
    title: string
    sourceBranch: string
    targetBranch: string
    labels: string[]
    assignees: string[]
  } | {
    authorId: string
    authorEmail?: undefined
    authorName?: undefined
    repoId: string
    orgId: string
    number: number
    pullRequestId: string
    title: string
    sourceBranch: string
    targetBranch: string
    labels: string[]
    assignees: string[]
  }
}

Errors

Status	Message
`400`	Choose two different branches.
`400`	Assignees must be members of this organization.
`400`	Branch not found.
`400`	The branches have diverged too far to compare.
`404`	Repository not found
`409`	Pull request #… is already open for these branches.
`409`	Too many open pull requests in this repository.
`409`	Could not create the pull request. Try again.

`GET /v1/orgs/:orgId/repos/:name/pulls/:number`

A pull request with its commit range, the merge strategies available now, and its comments.

Auth: user access token or platform agent key · Scope: git:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:name`	Repository name.
`:number`	Issue or pull request number.

Response 200

{
  pull: {
    state?: "open" | "closed" | "merged"
    title: string
    description: string
    base: null | string
    head: null | string
    mergeCommitId: null | string
    revisionId: null | string
    sourceBranchExists: boolean | null
    number: number
    createdAt?: number
    updatedAt?: number
    orgId: string
    repoId: string
    labels?: string[]
    assignees?: string[]
    comments?: number
    closedAt?: number
    closedBy?: string
    authorId: string
    authorEmail?: string
    authorName?: string
    pullRequestId: string
    sourceBranch: string
    targetBranch: string
    previousPullRequestIds?: string[]
  }
  mergeOptions: ("fast-forward" | "squash" | "three-way")[]
  conflicts: {
    path: string
    conflicts: number
    binary: boolean
    kind: "type" | "content" | "mode"
  }[]
  comments: {
    number: number
    createdAt?: number
    updatedAt?: number
    orgId: string
    repoId: string
    body: string
    authorId: string
    authorEmail?: string
    authorName?: string
    commentId: string
  }[]
}

Errors

Status	Message
`400`	These branches are too far apart to compare.
`404`	Repository not found
`404`	Pull request not found
`404`	Not found
`404`	Branch or commit not found.

`PATCH /v1/orgs/:orgId/repos/:name/pulls/:number`

Changes a pull request's title, description, labels or assignees.

Auth: user access token or platform agent key · Scope: git:read · Allowed: Author, or git:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:name`	Repository name.
`:number`	Issue or pull request number.

Request body

Field	Type	Required	Notes
`title`	`string`	No	1–150 characters; trimmed
`description`	`string`	No	up to 10,240 characters
`labels`	`string[]`	No	up to 10 items; each 1–50 characters, trimmed
`assignees`	`string[]`	No	up to 10 items; each 1–64 characters

Response 200

{
  pull: {
    number: number
    createdAt?: number
    updatedAt?: number
    orgId: string
    repoId: string
    labels?: string[]
    title: string
    state?: "open" | "closed" | "merged"
    assignees?: string[]
    comments?: number
    closedAt?: number
    closedBy?: string
    authorId: string
    authorEmail?: string
    authorName?: string
    pullRequestId: string
    sourceBranch: string
    targetBranch: string
    mergeCommitId?: string
    previousPullRequestIds?: string[]
  }
}

Errors

Status	Message
`400`	Assignees must be members of this organization.
`403`	Only the author or members with git:write can edit this pull request.
`404`	Repository not found
`404`	Pull request not found
`404`	Not found

`GET /v1/orgs/:orgId/repos/:name/pulls/:number/commits`

Commits the pull request adds to its target.

Auth: user access token or platform agent key · Scope: git:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:name`	Repository name.
`:number`	Issue or pull request number.

Response 200

{
  commits: {
    id: string
    message: string
    author: {
      name?: string
      email?: string
      date?: number
    }
    parents: string[]
    committedAt?: number
  }[]
  truncated: boolean
}

Errors

Status	Message
`400`	These branches are too far apart to compare.
`404`	Repository not found
`404`	Pull request not found
`404`	Not found
`404`	Branch or commit not found.
`404`	Commit not found

`GET /v1/orgs/:orgId/repos/:name/pulls/:number/files`

Changed files with unified diffs.

Auth: user access token or platform agent key · Scope: git:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:name`	Repository name.
`:number`	Issue or pull request number.

Response 200

{
  files: []
  total: number
  truncated: false
  base: null
  head: null
}
| {
  base: null | string
  head: string
  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
}

Errors

Status	Message
`400`	These branches are too far apart to compare.
`404`	Repository not found
`404`	Pull request not found
`404`	Not found
`404`	Branch or commit not found.

`POST /v1/orgs/:orgId/repos/:name/pulls/:number/merge`

Merges the pull request. Pass sourceCommitId (the head you reviewed) to fail if the branch has moved since.

Auth: user access token or platform agent key · Scopes: git:read, git:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:name`	Repository name.
`:number`	Issue or pull request number.

Request body

Field	Type	Required	Notes
`strategy`	`"squash" \| "fast-forward" \| "three-way"`	Yes
`message`	`string`	No	up to 4,096 characters; trimmed
`sourceCommitId`	`string`	No	matches `^[0-9a-f]{40}$`

Response 200

{
  merged: true
  mergeCommitId: null | string
  closedIssues: number[]
}

Errors

Status	Message
`404`	Repository not found
`404`	Pull request not found
`404`	Not found
`409`	This pull request is already closed.
`409`	This pull request can't be merged automatically with that strategy.
`409`	The source branch changed. Reload and try again.
`409`	The target branch changed. Try again.
`409`	The branches have diverged too far to merge.
`409`	This pull request needs more approvals before it can be merged.

`POST /v1/orgs/:orgId/repos/:name/pulls/:number/close`

Closes the pull request without merging.

Auth: user access token or platform agent key · Scope: git:read · Allowed: Author, or git:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:name`	Repository name.
`:number`	Issue or pull request number.

Response 200

{
  state?: "closed" | "merged"
}
| {
  state: string
}
| {
  state?: "open" | "closed" | "merged"
}

Errors

Status	Message
`403`	Only the author or members with git:write can close this pull request.
`404`	Repository not found
`404`	Pull request not found
`404`	Not found

`POST /v1/orgs/:orgId/repos/:name/pulls/:number/comments`

Adds a comment to a pull request.

Auth: user access token or platform agent key · Scope: git:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:name`	Repository name.
`:number`	Issue or pull request number.

Request body

Field	Type	Required	Notes
`body`	`string`	Yes	1–65,536 characters; trimmed

Response 201

{
  comment: {
    authorId: string
    authorEmail: string
    authorName?: string
    repoId: string
    orgId: string
    number: number
    commentId: string
    body: string
  } | {
    authorId: string
    authorEmail?: undefined
    authorName?: undefined
    repoId: string
    orgId: string
    number: number
    commentId: string
    body: string
  }
}

Errors

Status	Message
`404`	Repository not found
`404`	Pull request not found
`404`	Not found
`409`	Could not add the comment. Try again.

Pull requests

On this page