JSON API

Access Aviator's JSON API reference documentation.

Repository

Pause / unpause the merging of PRs on a repository.

POST https://api.aviator.co/api/v1/repo

Example:

curl -X POST -H "Authorization: Bearer <aviator_token>" -H "Content-Type: application/json" -d '{"org": "org_name", "name": "repo_name", "paused": true }' https://api.aviator.co/api/v1/repo/

Request Body

Name

Type

Description

org*

String

Name of the GitHub organization.

name*

String

Name of the repository in the GitHub organization.

paused*

Boolean

Whether to pause or unpause the queue

{
  "org": "ankitjaindce",
  "name": "testrepo",
  "paused": false
}

Fetch the list of repositories along with their pause and active status.

GET https://api.aviator.co/api/v1/repo

The results are paginated with maximum 10 results in every request.

Query Parameters

Name

Type

Description

page

Integer

page number. Defaults to 1.

[
    {
        "active": false,
        "name": "public-test",
        "org": "aviator-co",
        "paused": false
    },
    {
        "active": true,
        "name": "testrepo",
        "org": "aviator-co",
        "paused": false
    }
]

Branches

Pause / unpause the merging of PRs for specific base branches.

POST https://api.aviator.co/api/v1/branches

You can specify a glob pattern of base branches to pause or activate the Aviator queue. This ensures that you can continue merging branches to other base branches. You can override to pause / unpause all branches by using the Repository endpoint described above.

Example:

curl -X POST -H "Authorization: Bearer <aviator_token>" -H "Content-Type: application/json" -d '{ "pattern": "release-*", "repository": {"org": "aviator", "name": "av-demo-release"}, "paused": true, "paused_message": "This release branch has been paused."}' https://api.aviator.co/api/v1/branches

Request Body

Name

Type

Description

repository*

Object

Repository object associated with the branch

> org*

String

Organization associated with the repository

> name*

String

Name of the repository

pattern*

String

Glob pattern representing the base branch. E.g. master or release-*

paused*

Boolean

Whether to pause or unpause the queue

paused_message

String

A customized message to post on the top PR when this branch is paused.

{
    "pattern": "release-*",
    "repository": {
      "org": "aviator",
      "name": "av-demo-release"
    },
    "paused": true
}

Get base branches and their statuses (paused / unpaused)

GET https://api.aviator.co/api/v1/branches

You can specify a glob pattern of base branches to fetch the status of. If not provided, it will fetch the status of all base branches for a specific repository. Example:

curl -H "Authorization: Bearer <aviator_token>" -H "Content-Type: application/json" -d '{ "repository": {"org": "aviator", "name": "av-demo-release"}, "pattern": "release-*"}' https://api.aviator.co/api/v1/branches

Query Parameters

Name

Type

Description

repository*

Object

Repository object associated with the branch

> org *

String

Organization associated with the repository

> name*

String

Name of the repository

pattern

String

Glob pattern representing the base branch. E.g. master or release-*

{
    "branches": [
        {
            "pattern": "release-*",
            "paused": true
            "paused_message": "This branch is currently paused for the release"
        }
    ],
    "repository": {
        "name": "av-demo-release"
        "org": "aviator"
    }
}

PullRequest

Queue, Dequeue, Refresh, or Sync a Pull Request

POST https://api.aviator.co/api/v1/pull_request

curl -X POST -H "Authorization: Bearer <aviator_token>" -H "Content-Type: application/json" -d '{"action": "queue", "pull_request": {"number": 1234, "repository": {"name": "repo_name", "org": "org_name"}, "head_commit_sha": "69f4404fda48aa2932abfbcb6956a9ccd473b17d", "affected_targets": ["targetA", "targetB"], "merge_commit_message": {"title": "This is where title goes", "body": "This is where body goes"}}}' https://api.aviator.co/api/v1/pull_request/

To queue with skip-line:

curl -X POST -H "Authorization: Bearer <aviator_token>" -H "Content-Type: application/json" -d '{"action": "queue", "pull_request": {"number": 1234, "repository": {"name": "repo_name", "org": "org_name"}, "skip_line": true, "skip_line_reason": "hotfix for production outage"}}' https://api.aviator.co/api/v1/pull_request/

To refresh a PR:

curl -X POST -H "Authorization: Bearer <aviator_token>" -H "Content-Type: application/json" -d '{"action": "refresh", "pull_request": {"number": 1234, "repository": {"name": "repo_name", "org": "org_name"}}}' https://api.aviator.co/api/v1/pull_request/

To sync a PR with its base branch:

curl -X POST -H "Authorization: Bearer <aviator_token>" -H "Content-Type: application/json" -d '{"action": "sync", "pull_request": {"number": 1234, "repository": {"name": "repo_name", "org": "org_name"}}}' https://api.aviator.co/api/v1/pull_request/

Request Body

Name

Type

Description

action*

String

Action taken. Valid options: queue, update, dequeue, refresh, or sync

pull_request*

Object

PullRequest object representing the PR that is queued.

> number*

String

> repository*

Object

Repository object associated with the PR

> > name*

String

Name of the repository

> > org*

String

Organization associated with the repository

> head_commit_sha

String

Representing the commit SHA of the head of the PR.

> affected_targets

List[String]

Affected targets for the PR. Please see affected targets section for more details

> merge_commit_message

Object

CommitMessage object

> > title

String

Title of merge commit message

> > body

String

Body of merge commit message

> skip_line

Boolean

Optional. When true, the PR skips to the front of the queue. Only valid with the queue action. Requires skip-line authorization.

> skip_line_reason

String

Optional. Reason for skipping the line. Required if the repository has require_skip_line_reason enabled.

> skip_validation

Boolean

Optional. When true, skips CI validation for the PR. Only valid with the queue action.

> merge_commit_sha

String

Optional. Represents the SHA associated with the commit on the mainline generated after the PR was merged.

{
  "pull_request": {
    "number": 1234,
    "status": "queued",
    "queued": true,
    "title": "[TASK-123] This is a new bug",
    "author": "av_user",
    "head_branch": "av/new_fix",
    "base_branch": "main",
    "repository": {
      "name": "av-demo",
      "org": "aviator-co"
    }
  }
}

The refresh and sync actions are processed asynchronously and always return a 202 response.

refresh — re-fetches the latest CI statuses, PR state from GitHub, and triggers FlexReview processing.

sync — synchronizes the PR branch with its base branch. For stacked PRs, this performs a restack using niche-git.

{
  "pull_request": {
    "number": 1234,
    "status": "open",
    ...
  },
  "status": "processing",
  "message": "Refresh request accepted. Processing asynchronously."
}

// Missing skip_line_reason when required
{
  "error": "This repository requires a reason for skipping the line. Please provide skip_line_reason."
}

// Sync on a merged/closed PR
{
  "error": "Cannot sync a pull request that is already merged or closed."
}

Request to backport a PR on the specified target branch.

POST https://api.aviator.co/api/v1/pull_request/backport

Example:

curl -X POST -H "Authorization: Bearer <aviator_token>" -H "Content-Type: application/json" -d '{"target_branch": "release-v1", "source_pull": {"number": 1234, "repository": {"name": "repo_name", "org": "org_name"}}}' https://api.aviator.co/api/v1/pull_request/backport

Request Body

Name

Type

Description

target_branch*

String

Name of the base branch to backport this PR to

source_pull*

Object

PullRequest object for the current branch

> number*

Integer

PullRequest number

> repository*

Object

GitHub repository associated with the PullRequest

> > org*

String

Organization associated with the repository

> > name

String

Name of the repository

{
    "source_pull": {
      "number": 1234,
      "repository": {
        "org": "aviator",
        "name": "av-demo-release"
      }
    },
    "target_branch": "release-v1",
    "message": "Backporting initiated for 1234 to release-v1. Check comments in the PR #1234 for the status"
}

Fetch information of a PR based on the branch name or number

GET https://api.aviator.co/api/v1/pull_request

Example:

curl -H "Authorization: Bearer <aviator_token>" -H "Content-Type: application/json" https://api.aviator.co/api/v1/pull_request?org=orgname&repo=reponame&branch=branchname

Query Parameters

Name

Type

Description

org*

String

Organization associated with the repository

repo*

String

Name of the repository

branch*

String

Feature branch associated with PR. One of branch or number must be present.

number*

Integer

PR number to fetch. One of branch or number must be present.

{
    "author": "author-name",
    "base_branch": "master",
    "head_branch": "mq-qa-8440-1",
    "number": 89,
    "queued": true,
    "queued_at": "2022-11-16T17:21:41.350499",
    "merged_at": null,
    "created_at": "2022-11-16T17:20:00.000000",
    "repository": {
        "name": "repo-name",
        "org": "org-name"
    },
    "skip_line": false,
    "status": "queued",
    "title": "mq-qa-8440-1",
    "bot_pull_request": {
        "number": 201,
        "github_url": "https://github.com/org-name/repo-name/pull/201",
        "target_branch": "master",
        "head_commit_sha": "acffa575c02f2cf000aabe69f44e8905bc04c25d",
        "head_branch_oid": "acffa575c02f2cf000aabe69f44e8905bc04c25d",
        "codemix_pre_batch_sha": "08d30e0141d9f9253a228dac05173c4f383e1444"
    }
}

Response parameters

Name

Type

Description

queued_at

String

ISO 8601 timestamp for when the PR most recently entered the queue. Only populated when the PR's status is queued, tagged, merged, or blocked; null otherwise (e.g. pending, open, closed).

merged_at

String

ISO 8601 timestamp for when the PR was merged, or null if it has not been merged.

created_at

String

ISO 8601 timestamp for when Aviator first observed the PR.

bot_pull_request

Object | null

The latest Bot PR associated with this PR (parallel mode), or null if no Bot PR has been created. See the BotPullRequest schema for the fields returned.

Fetch information of PRs that are in the queued state

GET https://api.aviator.co/api/v1/pull_request/queued

Example:

curl -H "Authorization: Bearer <aviator_token>" -H "Content-Type: application/json" https://api.aviator.co/api/v1/pull_request/queued?org=orgname&repo=reponame&base_branch=master

Query Parameters

Name

Type

Description

org*

String

Organization associated with the repository

repo*

String

Name of the repository

base_branch

String

Target branch to fetch queued PRs for

{
    "pull_requests": [
        {
            "author": "ohcnivek",
            "base_branch": "master",
            "head_branch": "mq-qa-8440-1",
            "number": 89,
            "queued": true,
            "queued_at": "2022-11-16T17:21:41.350499",
            "merged_at": null,
            "created_at": "2022-11-16T17:20:00.000000",
            "repository": {
                "name": "kevin-test",
                "org": "ohcnivek"
            },
            "skip_line": false,
            "status": "queued",
            "title": "mq-qa-8440-1"
        },
        {
            "author": "ohcnivek",
            "base_branch": "master",
            "head_branch": "mq-qa-8440-2",
            "number": 90,
            "queued": true,
            "queued_at": "2022-11-16T17:21:50.001884",
            "merged_at": null,
            "created_at": "2022-11-16T17:20:10.000000",
            "repository": {
                "name": "kevin-test",
                "org": "ohcnivek"
            },
            "skip_line": false,
            "status": "queued",
            "title": "mq-qa-8440-2"
        },
        {
            "author": "ohcnivek",
            "base_branch": "master",
            "head_branch": "mq-qa-8440-3",
            "number": 91,
            "queued": true,
            "queued_at": "2022-11-16T17:22:00.185823",
            "merged_at": null,
            "created_at": "2022-11-16T17:20:20.000000",
            "repository": {
                "name": "kevin-test",
                "org": "ohcnivek"
            },
            "skip_line": false,
            "status": "queued",
            "title": "mq-qa-8440-3"
        }
    ]
}

BotPullRequest

Fetch information of PRs associated with a provided Bot PullRequest

GET https://api.aviator.co/api/v1/bot_pull_request

A Bot PR is a draft PR created during parallel mode to validate the CI.

Example:

curl -H "Authorization: Bearer <aviator_token>" -H "Content-Type: application/json" https://api.aviator.co/api/v1/bot_pull_request?org=orgname&repo=reponame&number=1234

Query Parameters

Name

Type

Description

org*

String

Organization associated with the repository

repo*

String

Name of the repository

number*

Integer

PR number associated with the Bot PR

{
  "number": 201,
  "github_url": "https://github.com/org-name/repo-name/pull/201",
  "target_branch": "master",
  "head_commit_sha": "acffa575c02f2cf000aabe69f44e8905bc04c25d",
  "head_branch_oid": "acffa575c02f2cf000aabe69f44e8905bc04c25d",
  "codemix_pre_batch_sha": "08d30e0141d9f9253a228dac05173c4f383e1444",
  "pull_requests": [
    {
      "author": "author-name",
      "base_branch": "master",
      "head_branch": "mq-qa-8440-1",
      "number": 89,
      "queued": true,
      "queued_at": "2022-11-16T17:21:41.350499",
      "merged_at": null,
      "created_at": "2022-11-16T17:20:00.000000",
      "repository": {
          "name": "repo-name",
          "org": "org-name"
      },
      "skip_line": false,
      "status": "queued",
      "title": "mq-qa-8440-1"
    }
  ]
}

Response parameters

Name

Type

Description

number

Integer

PR number of the Bot PR.

github_url

String

GitHub URL of the Bot PR.

target_branch

String

The branch the Bot PR targets.

head_commit_sha

String

Represents the head SHA of the bot pull request.

head_branch_oid

String

Legacy alias for head_commit_sha. Retained for existing consumers; new integrations should prefer head_commit_sha.

codemix_pre_batch_sha

String

Represents the commit SHA right before the validating pull requests were added to the bot PR branch. This commit SHA includes changes from the dependent PRs, but does not include the validating PRs.

pull_requests

List

List of PRs that are validating in this bot pull request.

Config

Fetch the current YAML config associated with the given GitHub repository.

GET https://api.aviator.co/api/v1/config

Example:

curl -H "Authorization: Bearer <aviator_token>" -H "Content-Type: application/json" https://api.aviator.co/api/v1/config?org=orgname&repo=reponame

Query Parameters

Name

Type

Description

org*

String

Organization associated with the GitHub repository.

repo*

String

Name of the GitHub repository.

merge_rules:
   labels:
     trigger: "mergequeue"
   merge_mode:
    type: "parallel"
    parallel_mode:
      max_parallel_builds: 10
      override_required_checks:
        - build_and_test
        - 'ci/circleci: build'

Change the YAML config associated with the given GitHub repository.

POST https://api.aviator.co/api/v1/config

The request accepts the payload as the raw string YAML format, and returns back response in a JSON format.

Example:

curl -X POST --data-raw "$(cat /Users/aviator-demo/config.text)" -H "Authorization: Bearer <API_TOKEN>" "https://api.aviator.co/api/v1/config?repo=repo_name&org=org_name"

Query Parameters

Name

Type

Description

org*

String

Organization associated with a GitHub repository

repo*

String

Name of the GitHub repository.

{
  "success": true
}

{
    "errors": [
        "mergeRules -> mergeMode -> parallelMode -> updateBeforeRequeue: value could not be parsed to a boolean",
        "mergeRules -> mergeMode -> parallelMode -> checkMergeabilityToQueue: value could not be parsed to a boolean"
    ],
    "success": false
}

Config Change

Fetch the history of config changes associated with a given repository.

GET https://api.aviator.co/api/v1/config/history

Returns a list of config history events as diffs of changes. repo and org must be provided.

Example:

curl -H "Authorization: Bearer <aviator_token>" -H "Content-Type: application/json" https://api.aviator.co/api/v1/config/history?org=orgname&repo=reponame

Query Parameters

Name

Type

Description

org*

String

Organization associated with the repository

repo*

String

Name of the repository

start

String

UTC Start date in YYYY-MM-DD format. Example: 2021-07-21

end

String

UTC End date in YYYY-MM-DD format. Example: 2021-07-21

page

Integer

Page number. Defaults to 1.

{
  "repository": {
    "name": "mergeit",
    "org": "aviator"
  },
  "history": [{
      "applied_by": {
        "email": "[email protected]",
        "gh_username": "jainankit"
      },
      "applied_at": "2022-11-16T17:21:41.350499Z"
      "commit_sha": "85d419bbca585f04456083fd98b7858c0f1e4d13",
      "diff": "-     publish: \"always\"\n+     publish: \"ready\"",
    },
    {
      ..
    }
  ]
}

The modified_by property contains email and gh_username. If the config was modified from the Dashboard, email of the user would be present, and if the config was modified from the GitHub repo change, a gh_username would be present. commit_sha property may also be only present if the change was made from the GitHub repository.

Analytics

Get list of analytics objects representing statistics on a daily basis.

GET https://api.aviator.co/api/v1/analytics

Example:

curl -H "Authorization: Bearer <aviator_token>" -H "Content-Type: application/json" https://api.aviator.co/api/v1/analytics/?start=2021-07-14&end=2021-07-21&timezone=America/Los_Angeles&repo=orgname/reponame

Query Parameters

Name

Type

Description

start

String

UTC Start date in YYYY-MM-DD format. Example: 2021-07-21

end

String

UTC End date in YYYY-MM-DD format. Example: 2021-07-21

repo*

String

Name of the GitHub repo, in the format: orgname/reponame

timezone

String

Standard tz format string. Defaults to account timezone. Example: America/Los_Angeles

Parameter

Description

time_in_queue

List of objects representing time spent by PRs in queue

>date

UTC End date in YYYY-MM-DD format. Example: 2021-07-14

>min

Minimum time in seconds

>avg

Average time in seconds

>p50

50th percentile in seconds

>p75

75th percentile in seconds

>p90

90th percentile in seconds

>p100

100th percentile in seconds

mergequeue_usage

List of objects representing the Aviator bot usage compared to total PRs merged.

>date

UTC End date in YYYY-MM-DD format. Example: 2021-07-14

>total

Total number of PRs merged

>merged_by_bot

Total number of PRs merged by Aviator bot

blocked_reason

List of objects representing the blocked reasons identified by the Aviator bot while processing queued PRs.

>date

UTC End date in YYYY-MM-DD format. Example: 2021-07-14

>merge_conflict

Failed due to merge conflict

>ci_failure

Failed due to CI status check failure. This only accounts for required check failures.

>manual_dequeue

A PR was manually removed from the queue

>ci_timeout

CI timed out based on the configuration in MergeQueue rules

>other

Failed due to any other reason

sync_frequency

List of objects representing how many times a PR fetched a base branch on an aggregate basis.

>date

UTC End date in YYYY-MM-DD format. Example: 2021-07-14

>min

Minimum sync times

>avg

Average sync times

>p50

50th percentile of number of sync times

>p75

75th percentile of number of sync times

>p90

90th percentile of number of sync times

>p100

100th percentile of number of sync times

wait_times_to_queue

Time it takes for a PR to get added to a batch in parallel mode after all the pre-queue validations pass.

>date

UTC End date in YYYY-MM-DD format. Example: 2021-07-14

>min

Minimum wait time that day

>avg

Average time that day

>p50

50th percentile

>p75

75th percentile

>p90

90th percentile

>p100

100th percentile

{
    "time_in_queue" : [
      {
        "date": "2021-07-14",
        "min": 12,
        "avg": 24,
        "p50": 23,
        "p75": 28,
        "p90": 32,
        "p100": 40
      },
      {
        "date": "2021-07-15",
        "min": 12,
        "avg": 24,
        "p50": 23,
        "p75": 28,
        "p90": 32,
        "p100": 40
      },
      {...},
      {...}
    ],
    "wait_times_to_queue" : [
      {
        "date": "2021-07-14",
        "min": 5,
        "avg": 8.4,
        "p50": 8.2,
        "p75": 9.1,
        "p90": 9.8,
        "p100": 12.5
      },
      {
        "date": "2021-07-15",
        "min": 5,
        "avg": 8.4,
        "p50": 8.2,
        "p75": 9.1,
        "p90": 9.8,
        "p100": 12.5
      },
      {...},
      {...}
    ],
    "mergequeue_usage": [
      {
        "date": "2021-07-14",
        "total": 52,
        "merged_by_bot": 40
      },
      {
        "date": "2021-07-15",
        "total": 52,
        "merged_by_bot": 40
      },
      {...},
      {...}
    ],
    "blocked_reason": [
      {
        "date": "2021-07-14",
        "merge_conflict": 2,
        "ci_failure": 4,
        "manual_dequeue": 6,
        "ci_timeout": 1,
        "other": 0
      },
      {
        "date": "2021-07-15",
        "merge_conflict": 2,
        "ci_failure": 4,
        "manual_dequeue": 6,
        "ci_timeout": 1,
        "other": 0
      },
      {...},
      {...}
    ],
    "sync_frequency": [
      {
        "date": "2021-07-14",
        "min": 1,
        "avg": 1,
       "p50": 2.34,
        "p75": 2.6,
        "p90": 3.2,
        "p100": 4
      },
      {
        "date": "2021-07-15",
        "min": 1,
        "avg": 1.2,
        "p50": 2.34,
        "p75": 2.6,
        "p90": 3.2,
        "p100": 4
      },
      {...},
      {...}
    ]
  }

Queue

Get live statistics about the state of the merge queue

GET https://api.aviator.co/api/v1/queue/stats

Currently this endpoint only reports statistics about the depth of the queue.

Query Parameters

Name

Type

Description

org*

String

The GitHub organization that the repo belongs to.

repo*

String

The name of the GitHub repo.

{
  // Stats about the current depth of the queue.
  "depth": {
    // The total number of PRs that are in the queue.
    // Excludes PRs that have not been queued yet or that have been
    // marked as blocked.
    "queued": 8, 
    // The number of PRs actively being processed.
    // In serial mode, this value is always equal to the "queued" value.
    // In parallel mode, this will be at most the "max_parallel_builds" setting
    // and indicates the numbers of PRs that have draft PRs created.
    "processing": 2, 
    // The number of PRs that are queued but not yet being processed.
    // In parallel mode, this is equal to queued - processing.
    // In serial mode, this is always zero.
    "waiting": 6
  }
}

User actions

This API is only available in Enterprise plan.

Fetch the actions performed by the users on the Aviator web app dashboard (audit logs). The results returned are ordered reverse chronologically.

GET https://api.aviator.co/api/v1/user_actions

Example:

curl -H "Authorization: Bearer <aviator_token>" -H "Content-Type: application/json" https://api.aviator.co/api/v1/user_actions/?page=2&entity=user&action=user_removed

Query parameters

Name

Type

Description

entity

String

Represents the entity type that is changed. Currently supported entities are user, merge_queue, repository, account, billing, integrations and flexreview

action

String

The type of action performed by the user.

page

Number

Page number

Response

The query returns a list of user actions with the following properties.

Name

Type

Description

action

String

The type of action performed by the user

actor

String

The email address of the user who performed the action

entity

String

The entity type that has changed.

target

String

Optional. Represents the target entity that has changed. It could be null if not applicable. E.g. it will be null for entity type account or integrations

timestamp

String

ISO timestamp representing the time with timezone

[
    {
        "action": "user_removed",
        "actor": "[email protected]",
        "entity": "user",
        "target": "[email protected]",
        "timestamp": "2024-10-02T00:45:05.881726+00:00"
    },
    {
        "action": "queue_config_changed",
        "actor": "[email protected]",
        "entity": "merge_queue",
        "target": "aviator-staging-testing/release-testing",
        "timestamp": "2024-10-02T00:31:46.471689+00:00"
    }
]

PreviousReference NextGraphQL

Last updated 26 days ago

Was this helpful?