# Gerrit Code Review - /plugins/ REST API

version v3.4.4

This page describes the plugin related REST endpoints. Please also take note of the general information on the REST API.

## Plugin Endpoints

Gerrit REST endpoints for installed plugins are available under '/plugins/{plugin-id}/gerrit~<endpoint-id>'. The `gerrit~` prefix ensures that the Gerrit REST endpoints for plugins do not clash with any REST endpoint that a plugin may offer under its namespace.

### List Plugins

'GET /plugins/'

Lists the plugins installed on the Gerrit server. Only the enabled plugins are returned unless the `all` option is specified.

To be allowed to see the installed plugins, a user must be a member of a group that is granted the 'View Plugins' capability or the 'Administrate Server' capability.

As result a map is returned that maps the plugin IDs to PluginInfo entries. The entries in the map are sorted by plugin ID.

Request

      GET /plugins/ HTTP/1.0

Response

      HTTP/1.1 200 OK
      Content-Disposition: attachment
      Content-Type: application/json; charset=UTF-8

      )]}'
      {
        "delete-project": {
          "id": "delete-project",
          "index_url": "plugins/delete-project/",
          "filename": "delete-project.jar",
          "api_version": "2.9.3-SNAPSHOT",
          "version": "2.9-SNAPSHOT"
        }
      }

#### Plugin Options

All(a)

  List all plugins including those that are disabled.

Request

      GET /plugins/?all HTTP/1.0

Response

      HTTP/1.1 200 OK
      Content-Disposition: attachment
      Content-Type: application/json; charset=UTF-8

      )]}'
      {
        "delete-project": {
          "id": "delete-project",
          "index_url": "plugins/delete-project/",
          "filename": "delete-project.jar",
          "version": "2.9-SNAPSHOT"
        },
        "reviewers-by-blame": {
          "id": "reviewers-by-blame",
          "index_url": "plugins/reviewers-by-blame/",
          "filename": "reviewers-by-blame.jar",
          "version": "2.9-SNAPSHOT",
          "disabled": true
        }
      }

Limit(n)

  Limit the number of plugins to be included in the results.

  Query the first plugin in the plugin list:

  Request

        GET /plugins/?n=1 HTTP/1.0

  Response

        HTTP/1.1 200 OK
        Content-Disposition: attachment
        Content-Type: application/json; charset=UTF-8

        )]}'
        {
          "delete-project": {
            "id": "delete-project",
            "index_url": "plugins/delete-project/",
            "filename": "delete-project.jar",
            "version": "2.9-SNAPSHOT"
          }
        }

Prefix(p)

  Limit the results to those plugins that start with the specified prefix.

  The match is case sensitive. May not be used together with `m` or `r`.

  List all plugins that start with `delete`:

  Request

        GET /plugins/?p=delete HTTP/1.0

  Response

        HTTP/1.1 200 OK
        Content-Disposition: attachment
        Content-Type: application/json; charset=UTF-8

        )]}'
        {
          "delete-project": {
            "id": "delete-project",
            "index_url": "plugins/delete-project/",
            "filename": "delete-project.jar",
            "version": "2.9-SNAPSHOT"
          }
        }

  E.g. this feature can be used by suggestion client UI’s to limit results.

Regex(r)

  Limit the results to those plugins that match the specified regex.

  Boundary matchers '^' and '$' are implicit. For example: the regex 'test.*' will match any plugins that start with 'test' and regex '.*test' will match any project that end with 'test'.

  The match is case sensitive. May not be used together with `m` or `p`.

  List all plugins that match regex `some.*plugin`:

  Request

        GET /plugins/?r=some.*plugin HTTP/1.0

  Response

        HTTP/1.1 200 OK
        Content-Disposition: attachment
        Content-Type: application/json; charset=UTF-8

        )]}'
        {
          "some-plugin": {
            "id": "some-plugin",
            "index_url": "plugins/some-plugin/",
            "filename": "some-plugin.jar",
            "version": "2.9-SNAPSHOT"
          },
          "some-other-plugin": {
            "id": "some-other-plugin",
            "index_url": "plugins/some-other-plugin/",
            "filename": "some-other-plugin.jar",
            "version": "2.9-SNAPSHOT"
          }
        }

Skip(S)

  Skip the given number of plugins from the beginning of the list.

  Query the second plugin in the plugin list:

  Request

        GET /plugins/?all&n=1&S=1 HTTP/1.0

  Response

        HTTP/1.1 200 OK
        Content-Disposition: attachment
        Content-Type: application/json; charset=UTF-8

        )]}'
        {
          "reviewers-by-blame": {
            "id": "reviewers-by-blame",
            "index_url": "plugins/reviewers-by-blame/",
            "filename": "reviewers-by-blame.jar",
            "version": "2.9-SNAPSHOT",
            "disabled": true
          }
        }

Substring(m)

  Limit the results to those plugins that match the specified substring.

  The match is case insensitive. May not be used together with `r` or `p`.

  List all plugins that match substring `project`:

  Request

        GET /plugins/?m=project HTTP/1.0

  Response

        HTTP/1.1 200 OK
        Content-Disposition: attachment
        Content-Type: application/json; charset=UTF-8

        )]}'
        {
          "delete-project": {
            "id": "delete-project",
            "index_url": "plugins/delete-project/",
            "filename": "delete-project.jar",
            "version": "2.9-SNAPSHOT"
          }
        }

### Install Plugin

'PUT /plugins/{plugin-id}.jar'

Installs a new plugin on the Gerrit server. If a plugin with the specified name already exists it is overwritten. Note: if the plugin provides its own name in the MANIFEST file, then the plugin name from the MANIFEST file has precedence over the {plugin-id} above.

The plugin jar can either be sent as binary data in the request body or a URL to the plugin jar must be provided in the request body inside a PluginInput entity.

Request

      PUT /plugins/delete-project.jar HTTP/1.0
      Content-Type: application/json; charset=UTF-8

      {
        "url": "file:///gerrit/plugins/delete-project/delete-project-2.8.jar"
      }

To provide the plugin jar as binary data in the request body the following curl command can be used:

      curl --user admin:TNNuLkWsIV8w -X PUT -H "Content-Type:application/octet-stream" --data-binary @delete-project.jar 'http://gerrit:8080/a/plugins/delete-project.jar'

As response a PluginInfo entity is returned that describes the plugin.

Response

      HTTP/1.1 201 Created
      Content-Disposition: attachment
      Content-Type: application/json;charset=utf-8
      Content-Length: 150

      )]}'
      {
        "id": "delete-project",
        "version": "v2.16-221-g35bb8bbac4",
        "index_url": "plugins/delete-project/",
        "filename": "delete-project.jar"
      }

If an existing plugin was overwritten the response is “200 OK”.

### Get Plugin Status

'GET /plugins/{plugin-id}/gerrit~status'

Retrieves the status of a plugin on the Gerrit server.

Request

      GET /plugins/delete-project/gerrit~status HTTP/1.0

As response a PluginInfo entity is returned that describes the plugin.

Response

      HTTP/1.1 200 OK
      Content-Disposition: attachment
      Content-Type: application/json; charset=UTF-8

      )]}'
      {
        "id": "delete-project",
        "version": "2.8"
      }

### Enable Plugin

'POST /plugins/{plugin-id}/gerrit~enable'

Enables a plugin on the Gerrit server.

Request

      POST /plugins/delete-project/gerrit~enable HTTP/1.0

As response a PluginInfo entity is returned that describes the plugin.

Response

      HTTP/1.1 200 OK
      Content-Disposition: attachment
      Content-Type: application/json; charset=UTF-8

      )]}'
      {
        "id": "delete-project",
        "version": "2.8"
      }

### Disable Plugin

'POST /plugins/{plugin-id}/gerrit~disable'

OR

'DELETE /plugins/{plugin-id}'

Disables a plugin on the Gerrit server.

Request

      POST /plugins/delete-project/gerrit~disable HTTP/1.0

As response a PluginInfo entity is returned that describes the plugin.

Response

      HTTP/1.1 200 OK
      Content-Disposition: attachment
      Content-Type: application/json; charset=UTF-8

      )]}'
      {
        "id": "delete-project",
        "version": "2.8",
        "disabled": true
      }

Disabling of a mandatory plugin is rejected:

Request

      DELETE /plugins/replication HTTP/1.0

Response

      HTTP/1.1 405 Method Not Allowed
      Content-Disposition: attachment
      Content-Type: application/json; charset=UTF-8

      )]}'
      Plugin replication is mandatory

### Reload Plugin

'POST /plugins/{plugin-id}/gerrit~reload'

Reloads a plugin on the Gerrit server.

Request

      POST /plugins/delete-project/gerrit~reload HTTP/1.0

As response a PluginInfo entity is returned that describes the plugin.

Response

      HTTP/1.1 200 OK
      Content-Disposition: attachment
      Content-Type: application/json; charset=UTF-8

      )]}'
      {
        "id": "delete-project",
        "version": "2.8",
        "disabled": true
      }

## IDs

### {plugin-id}

The ID of the plugin.

## JSON Entities

### PluginInfo

The `PluginInfo` entity describes a plugin.

Field Name |  | Description
--- | --- | ---
`id` |  | The ID of the plugin.
`version` |  | The version of the plugin.
`api_version` | optional | The version of the Gerrit Api used by the plugin.
`index_url` | optional | URL of the plugin’s default page.
`filename` | optional | The plugin’s filename.
`disabled` | not set if `false` | Whether the plugin is disabled.

### PluginInput

The `PluginInput` entity describes a plugin that should be installed.

Field Name | Description
--- | ---
`url` | URL to the plugin jar.

Part of Gerrit Code Review