Gerrit Code Review - /projects/ REST API

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