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

Endpoints

Project Endpoints

List Projects

GET /projects/

Lists the projects accessible by the caller. This is the same as using the ls-projects command over SSH, and accepts the same options as query parameters.

As result a map is returned that maps the project names to ProjectInfo entries. The entries in the map are sorted by project name.

Request
  GET /projects/?d HTTP/1.0
Response
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json;charset=UTF-8

  )]}'
  {
    "external/bison": {
      "kind": "gerritcodereview#project",
      "id": "external%2Fbison",
      "description": "GNU parser generator"
    },
    "external/gcc": {
      "kind": "gerritcodereview#project",
      "id": "external%2Fgcc",
    },
    "external/openssl": {
      "kind": "gerritcodereview#project",
      "id": "external%2Fopenssl",
      "description": "encryption\ncrypto routines"
    },
    "test": {
      "kind": "gerritcodereview#project",
      "id": "test",
      "description": "\u003chtml\u003e is escaped"
    }
  }
Get all projects with their description
GET /projects/?d HTTP/1.0

The /projects/ URL also accepts a prefix string in the p parameter. This limits the results to those projects that start with the specified prefix. List all projects that start with platform/:

Request
  GET /projects/?p=platform%2F HTTP/1.0
Response
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json;charset=UTF-8

  )]}'
  {
    "platform/drivers": {
      "kind": "gerritcodereview#project",
      "id": "platform%2Fdrivers",
    },
    "platform/tools": {
      "kind": "gerritcodereview#project",
      "id": "platform%2Ftools",
    }
  }

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

Get Project

GET /projects/{project-name}

Retrieves a project.

Request
  GET /projects/plugins%2Freplication HTTP/1.0

As response a ProjectInfo entity is returned that describes the project.

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

  )]}'
  {
    "kind": "gerritcodereview#project",
    "id": "plugins%2Freplication",
    "name": "plugins/replication",
    "parent": "Public-Plugins",
    "description": "Copies to other servers using the Git protocol"
  }

Create Project

PUT /projects/{project-name}

Creates a new project.

In the request body additional data for the project can be provided as ProjectInput.

Request
  PUT /projects/MyProject HTTP/1.0
  Content-Type: application/json;charset=UTF-8

  {
    "description": "This is a demo project.",
    "submit_type": "CHERRY_PICK",
    "owners": [
      "MyProject-Owners"
    ]
  }

As response the ProjectInfo entity is returned that describes the created project.

Response
  HTTP/1.1 201 Created
  Content-Disposition: attachment
  Content-Type: application/json;charset=UTF-8

  )]}'
  {
    "kind": "gerritcodereview#project",
    "id": "MyProject",
    "name": "MyProject",
    "parent": "All-Projects",
    "description": "This is a demo project."
  }

Get Project Description

GET /projects/{project-name}/description

Retrieves the description of a project.

Request
  GET /projects/plugins%2Freplication/description HTTP/1.0
Response
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json;charset=UTF-8

  )]}'
  "Copies to other servers using the Git protocol"

If the project does not have a description an empty string is returned.

Set Project Description

PUT /projects/{project-name}/description

Sets the description of a project.

The new project description must be provided in the request body inside a ProjectDescriptionInput entity.

Request
  PUT /projects/plugins%2Freplication/description HTTP/1.0
  Content-Type: application/json;charset=UTF-8

  {
    "description": "Plugin for Gerrit that handles the replication.",
    "commit_message": "Update the project description"
  }

As response the new project description is returned.

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

  )]}'
  "Plugin for Gerrit that handles the replication."

If the description was deleted the response is "204 No Content".

Delete Project Description

DELETE /projects/{project-name}/description

Deletes the description of a project.

The request body does not need to include a ProjectDescriptionInput entity if no commit message is specified.

Please note that some proxies prohibit request bodies for DELETE requests. In this case, if you want to specify a commit message, use PUT to delete the description.

Request
  DELETE /projects/plugins%2Freplication/description HTTP/1.0
Response
  HTTP/1.1 204 No Content

Get Project Parent

GET /projects/{project-name}/parent

Retrieves the name of a project’s parent project. For the All-Projects root project an empty string is returned.

Request
  GET /projects/plugins%2Freplication/parent HTTP/1.0
Response
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json;charset=UTF-8

  )]}'
  "All-Projects"

Set Project Parent

PUT /projects/{project-name}/parent

Sets the parent project for a project.

The new name of the parent project must be provided in the request body inside a ProjectParentInput entity.

Request
  PUT /projects/plugins%2Freplication/parent HTTP/1.0
  Content-Type: application/json;charset=UTF-8

  {
    "parent": "Public-Plugins",
    "commit_message": "Update the project parent"
  }

As response the new parent project name is returned.

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

  )]}'
  "Public-Plugins"

Get HEAD

GET /projects/{project-name}/HEAD

Retrieves for a project the name of the branch to which HEAD points.

Request
  GET /projects/plugins%2Freplication/HEAD HTTP/1.0
Response
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json;charset=UTF-8

  )]}'
  "refs/heads/master"

Set HEAD

PUT /projects/{project-name}/HEAD

Sets HEAD for a project.

The new ref to which HEAD should point must be provided in the request body inside a HeadInput entity.

Request
  PUT /projects/plugins%2Freplication/HEAD HTTP/1.0
  Content-Type: application/json;charset=UTF-8

  {
    "ref": "refs/heads/stable"
  }

As response the new ref to which HEAD points is returned.

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

  )]}'
  "refs/heads/stable"

Get Repository Statistics

GET /projects/{project-name}/statistics.git

Return statistics for the repository of a project.

Request
  GET /projects/plugins%2Freplication/statistics.git HTTP/1.0

The repository statistics are returned as a RepositoryStatisticsInfo entity.

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

  )]}'
  {
    "number_of_loose_objects": 127,
    "number_of_loose_refs": 15,
    "number_of_pack_files": 15,
    "number_of_packed_objects": 67,
    "number_of_packed_refs": 0,
    "size_of_loose_objects": 29466,
    "size_of_packed_objects": 9646
  }

Run GC

POST /projects/{project-name}/gc

Run the Git garbage collection for the repository of a project.

Request
  POST /projects/plugins%2Freplication/gc HTTP/1.0

The response is the streamed output of the garbage collection.

Response
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: text/plain;charset=UTF-8

  collecting garbage for "plugins/replication":
  Pack refs:              100% (21/21)
  Counting objects:       20
  Finding sources:        100% (20/20)
  Getting sizes:          100% (13/13)
  Compressing objects:     83% (5/6)
  Writing objects:        100% (20/20)
  Selecting commits:      100% (7/7)
  Building bitmaps:       100% (7/7)
  Finding sources:        100% (41/41)
  Getting sizes:          100% (25/25)
  Compressing objects:     52% (12/23)
  Writing objects:        100% (41/41)
  Prune loose objects also found in pack files: 100% (36/36)
  Prune loose, unreferenced objects: 100% (36/36)
  done.

Dashboard Endpoints

List Dashboards

GET /projects/{project-name}/dashboards/

List custom dashboards for a project.

As result a list of DashboardInfo entries is returned.

List all dashboards for the work/my-project project:

Request
  GET /projects/work%2Fmy-project/dashboards/ HTTP/1.0
Response
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json;charset=UTF-8

  )]}'
  [
    {
      "kind": "gerritcodereview#dashboard",
      "id": "main:closed",
      "ref": "main",
      "path": "closed",
      "description": "Merged and abandoned changes in last 7 weeks",
      "url": "/dashboard/?title\u003dClosed+changes\u0026Merged\u003dstatus:merged+age:7w\u0026Abandoned\u003dstatus:abandoned+age:7w",
      "default": true,
      "title": "Closed changes",
      "sections": [
        {
          "name": "Merged",
          "query": "status:merged age:7w"
        },
        {
          "name": "Abandoned",
          "query": "status:abandoned age:7w"
        }
      ]
    }
  ]
Get all dashboards of the All-Projects project
GET /projects/All-Projects/dashboards/ HTTP/1.0

Get Dashboard

GET /projects/{project-name}/dashboards/{dashboard-id}

Retrieves a project dashboard. The dashboard can be defined on that project or be inherited from a parent project.

Request
  GET /projects/work%2Fmy-project/dashboards/main:closed HTTP/1.0

As response a DashboardInfo entity is returned that describes the dashboard.

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

  )]}'
  {
    "kind": "gerritcodereview#dashboard",
    "id": "main:closed",
    "ref": "main",
    "path": "closed",
    "description": "Merged and abandoned changes in last 7 weeks",
    "url": "/dashboard/?title\u003dClosed+changes\u0026Merged\u003dstatus:merged+age:7w\u0026Abandoned\u003dstatus:abandoned+age:7w",
    "default": true,
    "title": "Closed changes",
    "sections": [
      {
        "name": "Merged",
        "query": "status:merged age:7w"
      },
      {
        "name": "Abandoned",
        "query": "status:abandoned age:7w"
      }
    ]
  }

To retrieve the default dashboard of a project use default as dashboard-id.

Request
  GET /projects/work%2Fmy-project/dashboards/default HTTP/1.0
Response
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json;charset=UTF-8

  )]}'
  {
    "kind": "gerritcodereview#dashboard",
    "id": "main:closed",
    "ref": "main",
    "path": "closed",
    "description": "Merged and abandoned changes in last 7 weeks",
    "url": "/dashboard/?title\u003dClosed+changes\u0026Merged\u003dstatus:merged+age:7w\u0026Abandoned\u003dstatus:abandoned+age:7w",
    "default": true,
    "title": "Closed changes",
    "sections": [
      {
        "name": "Merged",
        "query": "status:merged age:7w"
      },
      {
        "name": "Abandoned",
        "query": "status:abandoned age:7w"
      }
    ]
  }

Set Dashboard

PUT /projects/{project-name}/dashboards/{dashboard-id}

Updates/Creates a project dashboard.

Currently only supported for the default dashboard.

The creation/update information for the dashboard must be provided in the request body as a DashboardInput entity.

Request
  PUT /projects/work%2Fmy-project/dashboards/default HTTP/1.0
  Content-Type: application/json;charset=UTF-8

  {
    "id": "main:closed",
    "commit_message": "Define the default dashboard"
  }

As response the new/updated dashboard is returned as a DashboardInfo entity.

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

  )]}'
  {
    "kind": "gerritcodereview#dashboard",
    "id": "main:closed",
    "ref": "main",
    "path": "closed",
    "description": "Merged and abandoned changes in last 7 weeks",
    "url": "/dashboard/?title\u003dClosed+changes\u0026Merged\u003dstatus:merged+age:7w\u0026Abandoned\u003dstatus:abandoned+age:7w",
    "default": true,
    "title": "Closed changes",
    "sections": [
      {
        "name": "Merged",
        "query": "status:merged age:7w"
      },
      {
        "name": "Abandoned",
        "query": "status:abandoned age:7w"
      }
    ]
  }

Delete Dashboard

DELETE /projects/{project-name}/dashboards/{dashboard-id}

Deletes a project dashboard.

Currently only supported for the default dashboard.

The request body does not need to include a DashboardInput entity if no commit message is specified.

Please note that some proxies prohibit request bodies for DELETE requests.

Request
  DELETE /projects/work%2Fmy-project/dashboards/default HTTP/1.0
Response
  HTTP/1.1 204 No Content

IDs

{dashboard-id}

The ID of a dashboard in the format <ref>:<path>.

A special dashboard ID is default which represents the default dashboard of a project.

{project-name}

The name of the project.

JSON Entities

DashboardInfo

The DashboardInfo entity contains information about a project dashboard.

Field Name Description

kind

gerritcodereview#dashboard

id

The ID of the dashboard. The ID has the format <ref>:<path>, where ref and path are URL encoded.

project

The name of the project for which this dashboard is returned.

defining_project

The name of the project in which this dashboard is defined. This is different from project if the dashboard is inherited from a parent project.

ref

The name of the ref in which the dashboard is defined, without the refs/meta/dashboards/ prefix, which is common for all dashboard refs.

path

The path of the file in which the dashboard is defined.

description

optional

The description of the dashboard.

foreach

optional

Subquery that applies to all sections in the dashboard.
Tokens such as ${project} are not resolved.

url

The URL under which the dashboard can be opened in the Gerrit WebUI.
The URL is relative to the canonical web URL.
Tokens in the queries such as ${project} are resolved.

default

not set if false

Whether this is the default dashboard of the project.

title

optional

The title of the dashboard.

sections

The list of sections in the dashboard.

DashboardInput

The DashboardInput entity contains information to create/update a project dashboard.

Field Name Description

id

optional

URL encoded ID of a dashboard to which this dashboard should link to.

commit_message

optional

Message that should be used to commit the change of the dashboard.

DashboardSectionInfo

The DashboardSectionInfo entity contains information about a section in a dashboard.

Field Name Description

name

The title of the section.

query

The query of the section.
Tokens such as ${project} are not resolved.

HeadInput

The HeadInput entity contains information for setting HEAD for a project.

Field Name Description

ref

The ref to which HEAD should be set, the refs/heads prefix can be omitted.

ProjectDescriptionInput

The ProjectDescriptionInput entity contains information for setting a project description.

Field Name Description

description

optional

The project description.
The project description will be deleted if not set.

commit_message

optional

Message that should be used to commit the change of the project description in the project.config file to the refs/meta/config branch.

ProjectInfo

The ProjectInfo entity contains information about a project.

Field Name Description

kind

gerritcodereview#project

id

The URL encoded project name.

name

not set if returned in a map where the project name is used as map key

The name of the project.

parent

optional

The name of the parent project.
?-<n> if the parent project is not visible (<n> is a number which is increased for each non-visible project).

description

optional

The description of the project.

branches

optional

Map of branch names to HEAD revisions.

ProjectInput

The ProjectInput entity contains information for the creation of a new project.

Field Name Description

name

optional

The name of the project (not encoded).
If set, must match the project name in the URL.

parent

optional

The name of the parent project.
If not set, the All-Projects project will be the parent project.

description

optional

The description of the project.

permissions_only

false if not set

Whether a permission-only project should be created.

create_empty_commit

false if not set

Whether an empty initial commit should be created.

submit_type

optional

The submit type that should be set for the project (MERGE_IF_NECESSARY, REBASE_IF_NECESSARY, FAST_FORWARD_ONLY, MERGE_ALWAYS, CHERRY_PICK).
If not set, MERGE_IF_NECESSARY is set as submit type.

branches

optional

A list of branches that should be initially created.
For the branch names the refs/heads/ prefix can be omitted.

owners

optional

A list of groups that should be assigned as project owner.
Each group in the list must be specified as group-id.
If not set, the groups that are configured as default owners are set as project owners.

use_contributor_agreements

INHERIT if not set

Whether contributor agreements should be used for the project (TRUE, FALSE, INHERIT).

use_signed_off_by

INHERIT if not set

Whether the usage of Signed-Off-By footers is required for the project (TRUE, FALSE, INHERIT).

use_content_merge

INHERIT if not set

Whether content merge should be enabled for the project (TRUE, FALSE, INHERIT).
FALSE, if the submit_type is FAST_FORWARD_ONLY.

require_change_id

INHERIT if not set

Whether the usage of Change-Ids is required for the project (TRUE, FALSE, INHERIT).

ProjectParentInput

The ProjectParentInput entity contains information for setting a project parent.

Field Name Description

parent

The name of the parent project.

commit_message

optional

Message that should be used to commit the change of the project parent in the project.config file to the refs/meta/config branch.

RepositoryStatisticsInfo

The RepositoryStatisticsInfo entity contains information about statistics of a Git repository.

Field Name Description

number_of_loose_objects

Number of loose objects.

number_of_loose_refs

Number of loose refs.

number_of_pack_files

Number of pack files.

number_of_packed_objects

Number of packed objects.

number_of_packed_refs

Number of packed refs.

size_of_loose_objects

Size of loose objects in bytes.

size_of_packed_objects

Size of packed objects in bytes.


Part of Gerrit Code Review