API reference

Pull requests

Open, comment on, merge and close pull requests.

Read the Guide

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: A person's token or an API key, as Authorization: Bearer.
Scope: git:read

Get an API key

Path parameters

orgId
Organization id (org_…).
name
Repository name.
number
Issue or pull request number, or under pipelines a run number.

Errors

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

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/repos/{name}/pulls/{number}/review' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

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: "new" | "old"
    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
    }[]
  }[]
}

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: A person's token or an API key, as Authorization: Bearer.
Scope: git:read

Get an API key

Path parameters

orgId
Organization id (org_…).
name
Repository name.
number
Issue or pull request number, or under pipelines a run number.

Request body

bodystringrequired
1–10,240 characters. Trimmed.
inReplyTostring
1–256 characters.
pathstring
1–4,096 characters.
lineinteger
≥ 1.
side"old" | "new"
Default "new".
basestring
Matches ^[0-9a-f]{40}$.
headstring
Matches ^[0-9a-f]{40}$.

Errors

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

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/repos/{name}/pulls/{number}/review/comments' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "body": "example"
  }'

Send it from this page with your session or a key.

Response 201

{
  comment: {
    id: null | string
  }
}

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: A person's token or an API key, as Authorization: Bearer.
Scopes: git:read, git:write

Get an API key

Path parameters

orgId
Organization id (org_…).
name
Repository name.
number
Issue or pull request number, or under pipelines a run number.

Request body

approvebooleanrequired
revisionIdstring
At least 1 character.

Errors

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

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/repos/{name}/pulls/{number}/approval' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "approve": true
  }'

Send it from this page with your session or a key.

Response 200

{
  approved: boolean
}

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: A person's token or an API key, as Authorization: Bearer.
Scope: git:read
Allowed: Author, or git:write

Get an API key

Path parameters

orgId
Organization id (org_…).
name
Repository name.
number
Issue or pull request number, or under pipelines a run number.

Errors

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

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/repos/{name}/pulls/{number}/reopen' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  state: string
}

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: A person's token or an API key, as Authorization: Bearer.
Scope: git:read

Get an API key

Path parameters

orgId
Organization id (org_…).
name
Repository name.

Query parameters

state"open" | "closed" | "merged"
Default "open".
cursorstring
labelstring
Up to 50 characters.
authorstring
Up to 64 characters.
assigneestring
Up to 64 characters.

Errors

404Repository not found
404Not found
404Pull request not found

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/repos/{name}/pulls' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  pulls: {
    number: number
    createdAt?: number
    updatedAt?: number
    orgId: string
    title: string
    labels?: string[]
    repoId: 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
    reviewers?: string[]
    previousPullRequestIds?: string[]
  }[]
  cursor: null | string
}
| {
  pulls: {
    number: number
    createdAt?: number
    updatedAt?: number
    orgId: string
    title: string
    labels?: string[]
    repoId: 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
    reviewers?: string[]
    previousPullRequestIds?: string[]
  }[]
  cursor: null
}

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

Opens a pull request that merges source into target.

Auth: A person's token or an API key, as Authorization: Bearer.
Scopes: git:read, git:write

Get an API key

Path parameters

orgId
Organization id (org_…).
name
Repository name.

Request body

titlestringrequired
1–150 characters. Trimmed.
descriptionstring
Default "". Up to 10,240 characters.
sourcestringrequired
1–255 characters.
targetstringrequired
1–255 characters.
labelsstring[]
Default []. Up to 10 items. Each 1–50 characters, trimmed.
assigneesstring[]
Default []. Up to 10 items. Each 1–64 characters.
reviewersstring[]
Default []. Up to 10 items. Each 1–64 characters.

Errors

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

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/repos/{name}/pulls' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Example",
    "source": "example",
    "target": "example"
  }'

Send it from this page with your session or a key.

Response 201

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

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

A pull request with its commit range, the merge strategies available now, its comments, and codeowners: the owners each changed path needs an approval from (null without a CODEOWNERS file).

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: git:read

Get an API key

Path parameters

orgId
Organization id (org_…).
name
Repository name.
number
Issue or pull request number, or under pipelines a run number.

Errors

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

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/repos/{name}/pulls/{number}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

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
    labels?: string[]
    repoId: string
    assignees?: string[]
    comments?: number
    closedAt?: number
    closedBy?: string
    authorId: string
    authorEmail?: string
    authorName?: string
    pullRequestId: string
    sourceBranch: string
    targetBranch: string
    reviewers?: string[]
    previousPullRequestIds?: string[]
  }
  mergeOptions: ("fast-forward" | "squash" | "three-way")[]
  conflicts: {
    path: string
    conflicts: number
    binary: boolean
    kind: "type" | "mode" | "content"
  }[]
  comments: {
    number: number
    createdAt?: number
    updatedAt?: number
    orgId: string
    repoId: string
    body: string
    authorId: string
    authorEmail?: string
    authorName?: string
    commentId: string
  }[]
  codeowners: null | {
    required: {
      pattern: string
      owners: string[]
      satisfied: boolean
    }[]
    satisfied: boolean
  }
}

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

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

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: git:read
Allowed: Author, or git:write

Get an API key

Path parameters

orgId
Organization id (org_…).
name
Repository name.
number
Issue or pull request number, or under pipelines a run number.

Request body

titlestring
1–150 characters. Trimmed.
descriptionstring
Up to 10,240 characters.
labelsstring[]
Up to 10 items. Each 1–50 characters, trimmed.
assigneesstring[]
Up to 10 items. Each 1–64 characters.
reviewersstring[]
Up to 10 items. Each 1–64 characters.

Errors

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

curl -X PATCH 'https://api.cactive.com.au/v1/orgs/{orgId}/repos/{name}/pulls/{number}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Example",
    "description": "example",
    "labels": [
      "example"
    ]
  }'

Send it from this page with your session or a key.

Response 200

{
  pull: {
    number: number
    createdAt?: number
    updatedAt?: number
    orgId: string
    title: string
    labels?: string[]
    repoId: 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
    reviewers?: string[]
    previousPullRequestIds?: string[]
  }
}

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

Commits the pull request adds to its target.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: git:read

Get an API key

Path parameters

orgId
Organization id (org_…).
name
Repository name.
number
Issue or pull request number, or under pipelines a run number.

Errors

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

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/repos/{name}/pulls/{number}/commits' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

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

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

Changed files with unified diffs.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: git:read

Get an API key

Path parameters

orgId
Organization id (org_…).
name
Repository name.
number
Issue or pull request number, or under pipelines a run number.

Errors

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

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/repos/{name}/pulls/{number}/files' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  files: []
  total: number
  truncated: false
  base: null
  head: null
}
| {
  base: null | string
  head: string
  files: {
    path: string
    previousPath?: string
    change: "added" | "deleted" | "modified" | "renamed"
    similarity?: number
    additions: number
    deletions: number
    binary?: boolean
    collapsed?: boolean
    hunks: {
      oldStart: number
      oldLines: number
      newStart: number
      newLines: number
      lines: string[]
    }[]
  }[]
  total: number
  truncated: boolean
}

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. Into a ruled branch it needs the rule's approvals and code owner reviews (409 otherwise) and a clean secret scan (422); bypass: true merges without the reviews for people on the bypass list, audited.

Auth: A person's token or an API key, as Authorization: Bearer.
Scopes: git:read, git:write

Get an API key

Path parameters

orgId
Organization id (org_…).
name
Repository name.
number
Issue or pull request number, or under pipelines a run number.

Request body

strategy"squash" | "fast-forward" | "three-way"required
messagestring
Up to 4,096 characters. Trimmed.
sourceCommitIdstring
Matches ^[0-9a-f]{40}$.
bypassboolean

Errors

400… has no branch rule to bypass.
400These branches are too far apart to compare.
403Only people on …'s bypass list can merge without required reviews.
404Repository not found
404Pull request not found
404Not found
404Branch or commit not found.
409This pull request is already closed.
409This pull request needs … approval… before it can be merged into ….
409This pull request needs a review from a code owner of ….
409This pull request can't be merged automatically with that strategy.
409The source branch changed. Reload and try again.
409The target branch changed. Try again.
409The branches have diverged too far to merge.
409This pull request needs more approvals before it can be merged.

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/repos/{name}/pulls/{number}/merge' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "strategy": "squash"
  }'

Send it from this page with your session or a key.

Response 200

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

Response 202

{
  status: string
  scanned: number
}

Response 422

{
  error: string
  code: string
  findings: {
    line: number
    fingerprint: string
    preview: string
    path?: string
    rule: "aws_access_key" | "aws_secret_key" | "stripe_key" | "private_key" | "si_token" | "github_token"
    label: string
  }[]
}

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

Closes the pull request without merging.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: git:read
Allowed: Author, or git:write

Get an API key

Path parameters

orgId
Organization id (org_…).
name
Repository name.
number
Issue or pull request number, or under pipelines a run number.

Errors

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

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/repos/{name}/pulls/{number}/close' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

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

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

Adds a comment to a pull request.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: git:read

Get an API key

Path parameters

orgId
Organization id (org_…).
name
Repository name.
number
Issue or pull request number, or under pipelines a run number.

Request body

bodystringrequired
1–65,536 characters. Trimmed.

Errors

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

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/repos/{name}/pulls/{number}/comments' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "body": "example"
  }'

Send it from this page with your session or a key.

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
  }
}