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

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": {
      "id": "external%2Fbison",
      "description": "GNU parser generator"
    },
    "external/gcc": {
      "id": "external%2Fgcc"
    },
    "external/openssl": {
      "id": "external%2Fopenssl",
      "description": "encryption\ncrypto routines"
    },
    "test": {
      "id": "test",
      "description": "\u003chtml\u003e is escaped"
    }
  }

Project Options

Branch(b)

Limit the results to the projects having the specified branch and include the sha1 of the branch in the results.

Get projects that have a 'master' branch:

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

  )]}'
  {
    "some-project": {
      "id": "some-project",
      "branches": {
        "master": "c5ed9dfcbf002ca0e432d788dab6ca2387829ca7"
      }
    },
    "some-other-project": {
      "id": "some-other-project",
      "branches": {
        "master": "ef1c270142f9581ecf768f4193fc8f8a81102ec2"
      }
    },
  }
Description(d)

Include project description in the results.

Get all the projects with their description:

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

  )]}'
  {
    "some-project": {
      "id": "some-project",
      "description": "Description of some project."
    },
    "some-other-project": {
      "id": "some-other-project",
       "description": "Description of some other project."
      }
    },
  }
Limit(n)

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

Query the first project in the project list:

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

  )]}'
  {
    "some-project": {
      "id": "some-project"
    }
  }
Prefix(p)

Limit 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": {
      "id": "platform%2Fdrivers"
    },
    "platform/tools": {
      "id": "platform%2Ftools"
    }
  }

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

Regex(r)

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

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

List all projects that match regex test.*project:

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

  )]}'
  {
    "test/some-project": {
      "id": "test%2Fsome-project"
    },
    "test/some-other-project": {
      "id": "test%2Fsome-other-project"
    }
  }
Skip(S)

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

Query the second project in the project list:

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

  )]}'
  {
    "some-other-project": {
      "id": "some-other-project"
    }
  }
Substring(m)

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

List all projects that match substring test/:

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

  )]}'
  {
    "test/some-project": {
      "id": "test%2Fsome-project"
    },
    "some-path/test/some-other-project": {
      "id": "some-path%2Ftest%2Fsome-other-project"
    }
  }
Tree(t)

Get projects inheritance in a tree-like format. This option does not work together with the branch option.

Get all the projects with tree option:

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

  )]}'
  {
    "All-Projects" {
      "id": "All-Projects"
    },
    "child-project": {
      "id": "child-project",
      "parent":"parent-project"
    },
    "parent-project": {
      "id": "parent-project",
      "parent":"All-Projects"
    }
  }
Type(type)

Get projects with specified type: ALL, CODE, PERMISSIONS.

Get all the projects of type 'PERMISSIONS':

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

  )]}'
  {
    "All-Projects" {
      "id": "All-Projects"
    },
    "some-parent-project": {
      "id": "some-parent-project"
    }
  }

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

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

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

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

Get Config

'GET /projects/{project-name}/config'

Gets some configuration information about a project. Note that this config info is not simply the contents of project.config; it generally contains fields that may have been inherited from parent projects.

Request
  GET /projects/myproject/config

A ConfigInfo entity is returned that describes the project configuration. Some fields are only visible to users that have read access to refs/meta/config.

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

  )]}'
  {
    "description": "demo project",
    "use_contributor_agreements": {
      "value": true,
      "configured_value": "TRUE",
      "inherited_value": false
    },
    "use_content_merge": {
      "value": true,
      "configured_value": "INHERIT",
      "inherited_value": true
    },
    "use_signed_off_by": {
      "value": false,
      "configured_value": "INHERIT",
      "inherited_value": false
    },
    "create_new_change_for_all_not_in_target": {
      "value": false,
      "configured_value": "INHERIT",
      "inherited_value": false
    },
    "require_change_id": {
      "value": false,
      "configured_value": "FALSE",
      "inherited_value": true
    },
    "max_object_size_limit": {
      "value": "15m",
      "configured_value": "15m",
      "inherited_value": "20m"
    },
    "submit_type": "MERGE_IF_NECESSARY",
    "state": "ACTIVE",
    "commentlinks": {},
    "plugin_config": {
      "helloworld": {
        "language": {
          "display_name": "Preferred Language",
          "type": "STRING",
          "value": "en"
        }
      }
    },
    "actions": {
      "cookbook~hello-project": {
        "method": "POST",
        "label": "Say hello",
        "title": "Say hello in different languages",
        "enabled": true
      }
    }
  }

Set Config

'PUT /projects/{project-name}/config'

Sets the configuration of a project.

The new configuration must be provided in the request body as a ConfigInput entity.

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

  {
    "description": "demo project",
    "use_contributor_agreements": "FALSE",
    "use_content_merge": "INHERIT",
    "use_signed_off_by": "INHERIT",
    "create_new_change_for_all_not_in_target": "INHERIT",
    "require_change_id": "TRUE",
    "max_object_size_limit": "10m",
    "submit_type": "REBASE_IF_NECESSARY",
    "state": "ACTIVE"
  }

As response the new configuration is returned as a ConfigInfo entity.

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

  )]}'
  {
    "use_contributor_agreements": {
      "value": false,
      "configured_value": "FALSE",
      "inherited_value": false
    },
    "use_content_merge": {
      "value": true,
      "configured_value": "INHERIT",
      "inherited_value": true
    },
    "use_signed_off_by": {
      "value": false,
      "configured_value": "INHERIT",
      "inherited_value": false
    },
    "create_new_change_for_all_not_in_target": {
      "value": true,
      "configured_value": "INHERIT",
      "inherited_value": false
    },
    "require_change_id": {
      "value": true,
      "configured_value": "TRUE",
      "inherited_value": true
    },
    "max_object_size_limit": {
      "value": "10m",
      "configured_value": "10m",
      "inherited_value": "20m"
    },
    "submit_type": "REBASE_IF_NECESSARY",
    "state": "ACTIVE",
    "commentlinks": {}
  }

Run GC

'POST /projects/{project-name}/gc'

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

Options for the Git garbage collection can be specified in the request body as a GCInput entity.

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

  {
    "show_progress": true
  }

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.

Ban Commit

'PUT /projects/{project-name}/ban'

Marks commits as banned for the project. If a commit is banned Gerrit rejects every push that includes this commit with contains banned commit …​.

Note
 This REST endpoint only marks the commits as banned, but it does not remove the commits from the history of any central branch. This needs to be done manually.

The commits to be banned must be specified in the request body as a BanInput entity.

The caller must be project owner.

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

  {
    "commits": [
      "a8a477efffbbf3b44169bb9a1d3a334cbbd9aa96",
      "cf5b56541f84b8b57e16810b18daca9c3adc377b"
    ],
    "reason": "Violates IP"
  }

As response a BanResultInfo entity is returned.

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

  )]}'
  {
    "newly_banned": [
      "a8a477efffbbf3b44169bb9a1d3a334cbbd9aa96",
      "cf5b56541f84b8b57e16810b18daca9c3adc377b"
    ]
  }

Branch Endpoints

List Branches

'GET /projects/{project-name}/branches/'

List the branches of a project.

As result a list of BranchInfo entries is returned.

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

  )]}'
  [
    {
      "ref": "HEAD",
      "revision": "master"
    },
    {
      "ref": "refs/meta/config",
      "revision": "76016386a0d8ecc7b6be212424978bb45959d668"
    },
    {
      "ref": "refs/heads/master",
      "revision": "67ebf73496383c6777035e374d2d664009e2aa5c"
    },
    {
      "ref": "refs/heads/stable",
      "revision": "64ca533bd0eb5252d2fee83f63da67caae9b4674",
      "can_delete": true
    }
  ]

Branch Options

Limit(n)

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

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

  )]}'
  [
    {
      "ref": "HEAD",
      "revision": "master",
      "can_delete": false
    }
  ]
Skip(s)

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

Request
  GET /projects/testproject/branches?n=1&s=0 HTTP/1.0
Response
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json; charset=UTF-8

  )]}'
  [
    {
      "ref": "HEAD",
      "revision": "master",
      "can_delete": false
    }
  ]
Substring(m)

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

List all projects that match substring test:

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

  )]}'
  [
    {
      "ref": "refs/heads/test1",
      "revision": "9c9d08a438e55e52f33b608415e6dddd9b18550d",
      "can_delete": true
    }
  ]
Regex(r)

Limit the results to those branches that match the specified regex. Boundary matchers '^' and '$' are implicit. For example: the regex 't*' will match any branches that start with 'test' and regex '*t' will match any branches that end with 'test'.

List all branches that match regex t.*1:

Request
  GET /projects/testproject/branches?r=t.*1 HTTP/1.0
Response
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json; charset=UTF-8

  )]}'
  [
    {
      "ref": "refs/heads/test1",
      "revision": "9c9d08a438e55e52f33b608415e6dddd9b18550d",
      "can_delete": true
    }
  ]

Get Branch

'GET /projects/{project-name}/branches/{branch-id}'

Retrieves a branch of a project.

Request
  GET /projects/work%2Fmy-project/branches/master HTTP/1.0

As response a BranchInfo entity is returned that describes the branch.

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

  )]}'
  {
    "ref": "refs/heads/master",
    "revision": "67ebf73496383c6777035e374d2d664009e2aa5c"
  }

Create Branch

'PUT /projects/{project-name}/branches/{branch-id}'

Creates a new branch.

In the request body additional data for the branch can be provided as BranchInput.

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

  {
    "revision": "76016386a0d8ecc7b6be212424978bb45959d668"
  }

As response a BranchInfo entity is returned that describes the created branch.

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

  )]}'
  {
    "ref": "refs/heads/stable",
    "revision": "76016386a0d8ecc7b6be212424978bb45959d668",
    "can_delete": true
  }

Delete Branch

'DELETE /projects/{project-name}/branches/{branch-id}'

Deletes a branch.

Request
  DELETE /projects/MyProject/branches/stable HTTP/1.0
Response
  HTTP/1.1 204 No Content

Delete Branches

'POST /projects/{project-name}/branches:delete'

Delete one or more branches.

The branches to be deleted must be provided in the request body as a DeleteBranchesInput entity.

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

  {
    "branches": [
      "stable-1.0",
      "stable-2.0"
    ]
  }
Response
  HTTP/1.1 204 No Content

If some branches could not be deleted, the response is “409 Conflict” and the error message is contained in the response body.

Get Content

'GET /projects/{project-name}/branches/{branch-id}/files/{file-id}/content'

Gets the content of a file from the HEAD revision of a certain branch.

Request
  GET /projects/gerrit/branches/master/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/content HTTP/1.0

The content is returned as base64 encoded string.

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

  Ly8gQ29weXJpZ2h0IChDKSAyMDEwIFRoZSBBbmRyb2lkIE9wZW4gU291cmNlIFByb2plY...

Get Reflog

'GET /projects/{project-name}/branches/{branch-id}/reflog'

Gets the reflog of a certain branch.

The caller must be project owner.

Request
  GET /projects/gerrit/branches/master/reflog HTTP/1.0

As response a list of ReflogEntryInfo entities is returned that describe the reflog entries. The reflog entries are returned in reverse order.

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

  )]}'
  [
    {
      "old_id": "976ced8f4fc0909d7e1584d18455299545881d60",
      "new_id": "2eaa94bac536654eb592c941e33b91f925698d16",
      "who": {
        "name": "Jane Roe",
        "email": "jane.roe@example.com",
        "date": "2014-06-30 11:53:43.000000000",
        "tz": 120
      },
      "comment": "merged: fast forward"
    },
    {
      "old_id": "c271c6a7161b74f85560c5899c8c73ee89ca5e29",
      "new_id": "976ced8f4fc0909d7e1584d18455299545881d60",
      "who": {
        "name": "John Doe",
        "email": "john.doe@example.com",
        "date": "2013-10-02 10:45:26.000000000",
        "tz": 120
      },
      "comment": "merged: fast forward"
    },
    {
      "old_id": "0000000000000000000000000000000000000000",
      "new_id": "c271c6a7161b74f85560c5899c8c73ee89ca5e29",
      "who": {
        "name": "John Doe",
        "email": "john.doe@example.com",
        "date": "2013-09-30 19:08:44.000000000",
        "tz": 120
      },
      "comment": ""
    }
  ]

The get reflog endpoint also accepts a limit integer in the n parameter. This limits the results to show the last n reflog entries.

Query the last 25 reflog entries.

  GET /projects/gerrit/branches/master/reflog?n=25 HTTP/1.0

The reflog can also be filtered by timestamp by specifying the from and to parameters. The timestamp for from and to must be given as UTC in the following format: yyyyMMdd_HHmm.

  GET /projects/gerrit/branches/master/reflog?from=20130101_0000&to=20140101_0000=25 HTTP/1.0

Child Project Endpoints

List Child Projects

'GET /projects/{project-name}/children/'

List the direct child projects of a project.

Request
  GET /projects/Public-Plugins/children/ HTTP/1.0

As result a list of ProjectInfo entries is returned that describe the child projects.

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

  )]}'
  [
    {
      "id": "plugins%2Freplication",
      "name": "plugins/replication",
      "parent": "Public-Plugins",
      "description": "Copies to other servers using the Git protocol"
    },
    {
      "id": "plugins%2Freviewnotes",
      "name": "plugins/reviewnotes",
      "parent": "Public-Plugins",
      "description": "Annotates merged commits using notes on refs/notes/review."
    },
    {
      "id": "plugins%2Fsingleusergroup",
      "name": "plugins/singleusergroup",
      "parent": "Public-Plugins",
      "description": "GroupBackend enabling users to be directly added to access rules"
    }
  ]

To resolve the child projects of a project recursively the parameter recursive can be set.

Child projects that are not visible to the calling user are ignored and are not resolved further.

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

  )]}'
  [
    {
      "id": "gerrit",
      "name": "gerrit",
      "parent": "Public-Projects",
      "description": "Gerrit Code Review"
    },
    {
      "id": "plugins%2Freplication",
      "name": "plugins/replication",
      "parent": "Public-Plugins",
      "description": "Copies to other servers using the Git protocol"
    },
    {
      "id": "plugins%2Freviewnotes",
      "name": "plugins/reviewnotes",
      "parent": "Public-Plugins",
      "description": "Annotates merged commits using notes on refs/notes/review."
    },
    {
      "id": "plugins%2Fsingleusergroup",
      "name": "plugins/singleusergroup",
      "parent": "Public-Plugins",
      "description": "GroupBackend enabling users to be directly added to access rules"
    },
    {
      "id": "Public-Plugins",
      "name": "Public-Plugins",
      "parent": "Public-Projects",
      "description": "Parent project for plugins/*"
    }
  ]

Get Child Project

'GET /projects/{project-name}/children/{project-name}'

Retrieves a child project. If a non-direct child project should be retrieved the parameter recursive must be set.

Request
  GET /projects/Public-Plugins/children/plugins%2Freplication HTTP/1.0

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

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

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

Tag Endpoints

List Tags

'GET /projects/{project-name}/tags/'

List the tags of a project.

As result a list of TagInfo entries is returned.

Only includes tags under the refs/tags/ namespace.

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

  )]}'
  [
    {
      "ref": "refs/tags/v1.0",
      "revision": "49ce77fdcfd3398dc0dedbe016d1a425fd52d666",
      "object": "1624f5af8ae89148d1a3730df8c290413e3dcf30",
      "message": "Annotated tag",
      "tagger": {
        "name": "David Pursehouse",
        "email": "david.pursehouse@sonymobile.com",
        "date": "2014-10-06 07:35:03.000000000",
        "tz": 540
      }
    },
    {
      "ref": "refs/tags/v2.0",
      "revision": "1624f5af8ae89148d1a3730df8c290413e3dcf30"
    },
    {
      "ref": "refs/tags/v3.0",
      "revision": "c628685b3c5a3614571ecb5c8fceb85db9112313",
      "object": "1624f5af8ae89148d1a3730df8c290413e3dcf30",
      "message": "Signed tag\n-----BEGIN PGP SIGNATURE-----\nVersion: GnuPG v1.4.11 (GNU/Linux)\n\niQEcBAABAgAGBQJUMlqYAAoJEPI2qVPgglptp7MH/j+KFcittFbxfSnZjUl8n5IZ\nveZo7wE+syjD9sUbMH4EGv0WYeVjphNTyViBof+stGTNkB0VQzLWI8+uWmOeiJ4a\nzj0LsbDOxodOEMI5tifo02L7r4Lzj++EbqtKv8IUq2kzYoQ2xjhKfFiGjeYOn008\n9PGnhNblEHZgCHguGR6GsfN8bfA2XNl9B5Ysl5ybX1kAVs/TuLZR4oDMZ/pW2S75\nhuyNnSgcgq7vl2gLGefuPs9lxkg5Fj3GZr7XPZk4pt/x1oiH7yXxV4UzrUwg2CC1\nfHrBlNbQ4uJNY8TFcwof52Z0cagM5Qb/ZSLglHbqEDGA68HPqbwf5z2hQyU2/U4\u003d\n\u003dZtUX\n-----END PGP SIGNATURE-----",
      "tagger": {
        "name": "David Pursehouse",
        "email": "david.pursehouse@sonymobile.com",
        "date": "2014-10-06 09:02:16.000000000",
        "tz": 540
      }
    }
  ]

Get Tag

'GET /projects/{project-name}/tags/{tag-id}'

Retrieves a tag of a project.

Request
  GET /projects/work%2Fmy-project/tags/v1.0 HTTP/1.0

As response a TagInfo entity is returned that describes the tag.

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

  )]}'
  {
    "ref": "refs/tags/v1.0",
    "revision": "49ce77fdcfd3398dc0dedbe016d1a425fd52d666",
    "object": "1624f5af8ae89148d1a3730df8c290413e3dcf30",
    "message": "Annotated tag",
    "tagger": {
      "name": "David Pursehouse",
      "email": "david.pursehouse@sonymobile.com",
      "date": "2014-10-06 07:35:03.000000000",
      "tz": 540
    }
  }

Commit Endpoints

Get Commit

'GET /projects/{project-name}/commits/{commit-id}'

Retrieves a commit of a project.

The commit must be visible to the caller.

Request
  GET /projects/work%2Fmy-project/commits/a8a477efffbbf3b44169bb9a1d3a334cbbd9aa96 HTTP/1.0

As response a CommitInfo entity is returned that describes the commit.

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

  )]}'
  {
    "commit": "184ebe53805e102605d11f6b143486d15c23a09c",
    "parents": [
      {
        "commit": "1eee2c9d8f352483781e772f35dc586a69ff5646",
        "subject": "Migrate contributor agreements to All-Projects."
      }
    ],
    "author": {
      "name": "Shawn O. Pearce",
      "email": "sop@google.com",
      "date": "2012-04-24 18:08:08.000000000",
      "tz": -420
    },
    "committer": {
      "name": "Shawn O. Pearce",
      "email": "sop@google.com",
      "date": "2012-04-24 18:08:08.000000000",
      "tz": -420
    },
    "subject": "Use an EventBus to manage star icons",
    "message": "Use an EventBus to manage star icons\n\nImage widgets that need to ..."
  }

Get Content

'GET /projects/{project-name}/commits/{commit-id}/files/{file-id}/content'

Gets the content of a file from a certain commit.

Request
  GET /projects/work%2Fmy-project/commits/a8a477efffbbf3b44169bb9a1d3a334cbbd9aa96/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/content HTTP/1.0

The content is returned as base64 encoded string.

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

  Ly8gQ29weXJpZ2h0IChDKSAyMDEwIFRoZSBBbmRyb2lkIE9wZW4gU291cmNlIFByb2plY...

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

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

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

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

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

{branch-id}

The name of a branch or HEAD. The prefix refs/heads/ can be omitted.

{commit-id}

Commit ID.

{tag-id}

The name of a tag. The prefix refs/tags/ can be omitted.

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

If the name ends with .git, the suffix will be automatically removed.

JSON Entities

BanInput

The BanInput entity contains information for banning commits in a project.

Field Name Description

commits

List of commits to be banned.

reason

optional

Reason for banning the commits.

BanResultInfo

The BanResultInfo entity describes the result of banning commits.

Field Name Description

newly_banned

optional

List of newly banned commits.

already_banned

optional

List of commits that were already banned.

ignored

optional

List of object IDs that were ignored.

BranchInfo

The BranchInfo entity contains information about a branch.

Field Name Description

ref

The ref of the branch.

revision

The revision to which the branch points.

can_delete

false if not set

Whether the calling user can delete this branch.

web_links

optional

Links to the branch in external sites as a list of WebLinkInfo entries.

BranchInput

The BranchInput entity contains information for the creation of a new branch.

Field Name Description

ref

optional

The name of the branch. The prefix refs/heads/ can be omitted.
If set, must match the branch ID in the URL.

revision

optional

The base revision of the new branch.
If not set, HEAD will be used as base revision.

ConfigInfo

The ConfigInfo entity contains information about the effective project configuration.

Field Name Description

description

optional

The description of the project.

use_contributor_agreements

optional

InheritedBooleanInfo that tells whether authors must complete a contributor agreement on the site before pushing any commits or changes to this project.

use_content_merge

optional

InheritedBooleanInfo that tells whether Gerrit will try to perform a 3-way merge of text file content when a file has been modified by both the destination branch and the change being submitted. This option only takes effect if submit type is not FAST_FORWARD_ONLY.

use_signed_off_by

optional

InheritedBooleanInfo that tells whether each change must contain a Signed-off-by line from either the author or the uploader in the commit message.

create_new_change_for_all_not_in_target

optional

InheritedBooleanInfo that tells whether a new change is created for every commit not in target branch.

require_change_id

optional

InheritedBooleanInfo that tells whether a valid Change-Id footer in any commit uploaded for review is required. This does not apply to commits pushed directly to a branch or tag.

max_object_size_limit

The max object size limit of this project as a MaxObjectSizeLimitInfo entity.

submit_type

The default submit type of the project, can be MERGE_IF_NECESSARY, FAST_FORWARD_ONLY, REBASE_IF_NECESSARY, MERGE_ALWAYS or CHERRY_PICK.

state

optional

The state of the project, can be ACTIVE, READ_ONLY or HIDDEN.
Not set if the project state is ACTIVE.

commentlinks

Map with the comment link configurations of the project. The name of the comment link configuration is mapped to the comment link configuration, which has the same format as the commentlink section of gerrit.config.

theme

optional

The theme that is configured for the project as a ThemeInfo entity.

plugin_config

optional

Plugin configuration as map which maps the plugin name to a map of parameter names to ConfigParameterInfo entities.

actions

optional

Actions the caller might be able to perform on this project. The information is a map of view names to ActionInfo entities.

ConfigInput

The ConfigInput entity describes a new project configuration.

Field Name Description

description

optional

The new description of the project.
If not set, the description is removed.

use_contributor_agreements

optional

Whether authors must complete a contributor agreement on the site before pushing any commits or changes to this project.
Can be TRUE, FALSE or INHERIT.
If not set, this setting is not updated.

use_content_merge

optional

Whether Gerrit will try to perform a 3-way merge of text file content when a file has been modified by both the destination branch and the change being submitted. This option only takes effect if submit type is not FAST_FORWARD_ONLY.
Can be TRUE, FALSE or INHERIT.
If not set, this setting is not updated.

use_signed_off_by

optional

Whether each change must contain a Signed-off-by line from either the author or the uploader in the commit message.
Can be TRUE, FALSE or INHERIT.
If not set, this setting is not updated.

create_new_change_for_all_not_in_target

optional

Whether a new change will be created for every commit not in target branch.
Can be TRUE, FALSE or INHERIT.
If not set, this setting is not updated.

require_change_id

optional

Whether a valid Change-Id footer in any commit uploaded for review is required. This does not apply to commits pushed directly to a branch or tag.
Can be TRUE, FALSE or INHERIT.
If not set, this setting is not updated.

max_object_size_limit

optional

The max object size limit of this project as a MaxObjectSizeLimitInfo entity.
If set to 0, the max object size limit is removed.
If not set, this setting is not updated.

submit_type

optional

The default submit type of the project, can be MERGE_IF_NECESSARY, FAST_FORWARD_ONLY, REBASE_IF_NECESSARY, MERGE_ALWAYS or CHERRY_PICK.
If not set, the submit type is not updated.

state

optional

The state of the project, can be ACTIVE, READ_ONLY or HIDDEN.
Not set if the project state is ACTIVE.
If not set, the project state is not updated.

plugin_config_values

optional

Plugin configuration values as map which maps the plugin name to a map of parameter names to values.

ConfigParameterInfo

The ConfigParameterInfo entity describes a project configuration parameter.

Field Name Description

display_name

optional

The display name of the configuration parameter.

description

optional

The description of the configuration parameter.

warning

optional

Warning message for the configuration parameter.

type

The type of the configuration parameter. Can be STRING, INT, LONG, BOOLEAN, LIST or ARRAY.

value

optional

The value of the configuration parameter as string. If the parameter is inheritable this is the effective value which is deduced from configured_value and inherited_value.

values

optional

The list of values. Only set if the type is ARRAY. editable

false if not set

Whether the value is editable.

permitted_values

optional

The list of permitted values. Only set if the type is LIST.

inheritable

false if not set

Whether the configuration parameter can be inherited.

configured_value

optional

The value of the configuration parameter that is configured on this project, only set if inheritable is true.

inherited_value

optional

The inherited value of the configuration parameter, only set if inheritable is true.

permitted_values

DashboardInfo

The DashboardInfo entity contains information about a project dashboard.

Field Name Description

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 Web UI.
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.

DeleteBranchesInput

The DeleteBranchesInput entity contains information about branches that should be deleted.

Field Name Description

branches

A list of branch names that identify the branches that should be deleted.

GCInput

The GCInput entity contains information to run the Git garbage collection.

Field Name Description

show_progress

false if not set

Whether progress information should be shown.

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.

InheritedBooleanInfo

A boolean value that can also be inherited.

Field Name Description

value

The effective boolean value.

configured_value

The configured value, can be TRUE, FALSE or INHERITED.

inherited_value

optional

The boolean value inherited from the parent.
Not set if there is no parent.

MaxObjectSizeLimitInfo

The MaxObjectSizeLimitInfo entity contains information about the max object size limit of a project.

Field Name Description

value

optional

The effective value of the max object size limit as a formatted string.
Not set if there is no limit for the object size.

configured_value

optional

The max object size limit that is configured on the project as a formatted string.
Not set if there is no limit for the object size configured on project level.

inherited_value

optional

The max object size limit that is inherited as a formatted string.
Not set if there is no global limit for the object size.

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

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.

state

optional

ACTIVE, READ_ONLY or HIDDEN.

branches

optional

Map of branch names to HEAD revisions.

web_links

optional

Links to the project in external sites as a list of WebLinkInfo entries.

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.
If name ends with .git the suffix will be automatically removed.

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 unless repository.<name>.defaultSubmitType is set to a different value.

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).

create_new_change_for_all_not_in_target

INHERIT if not set

Whether a new change is created for every commit not in target branch 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).

max_object_size_limit

optional

Max allowed Git object size for this project. Common unit suffixes of 'k', 'm', or 'g' are supported.

plugin_config_values

optional

Plugin configuration values as map which maps the plugin name to a map of parameter names to values.

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.

ReflogEntryInfo

The ReflogEntryInfo entity describes an entry in a reflog.

Field Name Description

old_id

The old commit ID.

new_id

The new commit ID.

who

The user performing the change as a GitPersonInfo entity.

comment

Comment of the reflog entry.

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.

TagInfo

The TagInfo entity contains information about a tag.

Field Name Description

ref

The ref of the tag.

revision

For lightweight tags, the revision of the commit to which the tag points. For annotated tags, the revision of the tag object.

object

Only set for annotated tags.

The revision of the object to which the tag points.

message

Only set for annotated tags.

The tag message. For signed tags, includes the signature.

tagger

Only set for annotated tags.

The tagger as a GitPersonInfo entity.

ThemeInfo

The ThemeInfo entity describes a theme.

Field Name Description

css

optional

The path to the GerritSite.css file.

header

optional

The path to the GerritSiteHeader.html file.

footer

optional

The path to the GerritSiteFooter.html file.

Part of Gerrit Code Review