JSON API

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

200: OK Success

{
  "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.

200: OK

[
    {
        "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.

200: OK

{
    "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-*

200: OK Success

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

PullRequest

Queue or Dequeue 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/

Request Body

Name	Type	Description
action*	String	Action taken. Valid options: update, queue or dequeue
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

200: OK

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

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

200: OK

{
    "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.

200: OK Success

{
    "author": "author-name",
    "base_branch": "master",
    "head_branch": "mq-qa-8440-1",
    "number": 89,
    "queued": true,
    "queued_at": "2022-11-16T17:21:41.350499",
    "repository": {
        "name": "repo-name",
        "org": "org-name"
    },
    "skip_line": false,
    "status": "queued",
    "title": "mq-qa-8440-1"
}

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

200: OK Success

{
    "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",
            "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",
            "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",
            "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

200: OK Success

{
  "head_commit_sha": "acffa575c02f2cf000aabe69f44e8905bc04c25d",
  "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",
      "repository": {
          "name": "repo-name",
          "org": "org-name"
      },
      "skip_line": false,
      "status": "queued",
      "title": "mq-qa-8440-1"
    }
  ]
}

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.

200: OK

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.

200: OK

{
  "success": true
}

400: Bad Request

{
    "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.

200: OK Success

{
  "repository": {
    "name": "mergeit",
    "org": "aviator"
  },
  "history": [{
      "applied_by": {
        "email": "[e-mail]",
        "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

200: OK Success

Parameters

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

Example

{
    "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
      },
      {...},
      {...}
    ],
    "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.

200: OK Success

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