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

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

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

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

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

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

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
}

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@email.com",
        "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

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": "ankit@aviator.co",
        "entity": "user",
        "target": "heeju@aviator.co",
        "timestamp": "2024-10-02T00:45:05.881726+00:00"
    },
    {
        "action": "queue_config_changed",
        "actor": "ankit+masaya-demo@aviator.co",
        "entity": "merge_queue",
        "target": "aviator-staging-testing/release-testing",
        "timestamp": "2024-10-02T00:31:46.471689+00:00"
    }
]

Last updated