description
Access Aviator's JSON API reference documentation.

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

{% tabs %} {% tab title="200: OK Success" %}

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

{% endtab %} {% endtabs %}

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.

{% tabs %} {% tab title="200: OK " %}

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

{% endtab %} {% endtabs %}

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.

{% tabs %} {% tab title="200: OK " %}

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

{% endtab %} {% endtabs %}

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-*`

{% tabs %} {% tab title="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"
    }
}

{% endtab %} {% endtabs %}

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

{% tabs %} {% tab title="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"
    }
  }
}

{% endtab %} {% endtabs %}

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

{% tabs %} {% tab title="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"
}

{% endtab %} {% endtabs %}

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.

{% tabs %} {% tab title="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"
}

{% endtab %} {% endtabs %}

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

{% tabs %} {% tab title="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"
        }
    ]
}

{% endtab %} {% endtabs %}

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

{% tabs %} {% tab title="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"
    }
  ]
}

{% endtab %} {% endtabs %}

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.

{% tabs %} {% tab title="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'

{% endtab %} {% endtabs %}

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.

{% tabs %} {% tab title="200: OK " %}

{
  "success": true
}

{% endtab %}

{% tab title="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
}

{% endtab %} {% endtabs %}

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.

{% tabs %} {% tab title="200: OK Success" %}

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

{% endtab %} {% endtabs %}

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

{% tabs %} {% tab title="200: OK Success" %} {% tabs %} {% tab title="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

{% endtab %}

{% tab title="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
      },
      {...},
      {...}
    ]
  }

{% endtab %} {% endtabs %} {% endtab %} {% endtabs %}

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.

{% tabs %} {% tab title="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
  }
}

{% endtab %} {% endtabs %}

User actions

{% hint style="info" %} This API is only available in Enterprise plan. {% endhint %}

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

{% tabs %} {% tab title="200" %}

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

{% endtab %} {% endtabs %}

Files

json-api.md

Latest commit

History

json-api.md

File metadata and controls

JSON API

Repository

Pause / unpause the merging of PRs on a repository.

Request Body

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

Query Parameters

Branches

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

Request Body

Get base branches and their statuses (paused / unpaused)

Query Parameters

PullRequest

Queue or Dequeue a Pull Request

Request Body

Request to backport a PR on the specified target branch.

Request Body

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

Query Parameters

Fetch information of PRs that are in the queued state

Query Parameters

BotPullRequest

Fetch information of PRs associated with a provided Bot PullRequest

Query Parameters

Config

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

Query Parameters

Change the YAML config associated with the given GitHub repository.

Query Parameters

Config Change

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

Query Parameters

Analytics

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

Query Parameters

Queue

Get live statistics about the state of the merge queue

Query Parameters

User actions

Query parameters