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

Change Endpoints

Query Changes

GET /changes/

Queries changes visible to the caller. The query string must be provided by the q parameter. The n parameter can be used to limit the returned results.

As result a list of ChangeInfo entries is returned. The change output is sorted by the last update time, most recently updated to oldest updated.

Query for open changes of watched projects:

Request
  GET /changes/?q=status:open+is:watched&n=2 HTTP/1.0
Response
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json;charset=UTF-8

  )]}'
  [
    {
      "kind": "gerritcodereview#change",
      "id": "demo~master~Idaf5e098d70898b7119f6f4af5a6c13343d64b57",
      "project": "demo",
      "branch": "master",
      "change_id": "Idaf5e098d70898b7119f6f4af5a6c13343d64b57",
      "subject": "One change",
      "status": "NEW",
      "created": "2012-07-17 07:18:30.854000000",
      "updated": "2012-07-17 07:19:27.766000000",
      "reviewed": true,
      "mergeable": true,
      "_sortkey": "001e7057000006dc",
      "_number": 1756,
      "owner": {
        "name": "John Doe"
      },
    },
    {
      "kind": "gerritcodereview#change",
      "id": "demo~master~I09c8041b5867d5b33170316e2abc34b79bbb8501",
      "project": "demo",
      "branch": "master",
      "change_id": "I09c8041b5867d5b33170316e2abc34b79bbb8501",
      "subject": "Another change",
      "status": "NEW",
      "created": "2012-07-17 07:18:30.884000000",
      "updated": "2012-07-17 07:18:30.885000000",
      "mergeable": true,
      "_sortkey": "001e7056000006dd",
      "_number": 1757,
      "owner": {
        "name": "John Doe"
      },
      "_more_changes": true
    }
  ]

If the n query parameter is supplied and additional changes exist that match the query beyond the end, the last change object has a _more_changes: true JSON field set. Callers can resume a query with the N query parameter, supplying the last change’s _sortkey field as the value. When going in the reverse direction with the P query parameter a _more_changes: true is put in the first change object if there are results before the first change returned.

Clients are allowed to specify more than one query by setting the q parameter multiple times. In this case the result is an array of arrays, one per query in the same order the queries were given in.

Query for the 25 most recent open changes of the projects that you watch
GET /changes/?q=status:open+is:watched&n=25 HTTP/1.0

Query that retrieves changes for a user’s dashboard:

Request
  GET /changes/?q=is:open+owner:self&q=is:open+reviewer:self+-owner:self&q=is:closed+owner:self+limit:5&o=LABELS HTTP/1.0
Response
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json;charset=UTF-8

  )]}'
  [
    [
      {
        "kind": "gerritcodereview#change",
        "id": "demo~master~Idaf5e098d70898b7119f6f4af5a6c13343d64b57",
        "project": "demo",
        "branch": "master",
        "change_id": "Idaf5e098d70898b7119f6f4af5a6c13343d64b57",
        "subject": "One change",
        "status": "NEW",
        "created": "2012-07-17 07:18:30.854000000",
        "updated": "2012-07-17 07:19:27.766000000",
        "reviewed": true,
        "mergeable": true,
        "_sortkey": "001e7057000006dc",
        "_number": 1756,
        "owner": {
          "name": "John Doe"
        },
        "labels": {
          "Verified": {},
          "Code-Review": {}
        }
      }
    ],
    [],
    []
  ]
Query the changes for your user dashboard
GET /changes/?q=is:open+owner:self&q=is:open+reviewer:self+-owner:self&q=is:closed+owner:self+limit:5&o=LABELS HTTP/1.0

Additional fields can be obtained by adding o parameters, each option requires more database lookups and slows down the query response time to the client so they are generally disabled by default. Optional fields are:

  • LABELS: a summary of each label required for submit, and approvers that have granted (or rejected) with that label.

  • DETAILED_LABELS: detailed label information, including numeric values of all existing approvals, recognized label values, values permitted to be set by the current user, and reviewers that may be removed by the current user.

  • CURRENT_REVISION: describe the current revision (patch set) of the change, including the commit SHA-1 and URLs to fetch from.

  • ALL_REVISIONS: describe all revisions, not just current.

  • CURRENT_COMMIT: parse and output all header fields from the commit object, including message. Only valid when the current revision or all revisions are selected.

  • ALL_COMMITS: parse and output all header fields from the output revisions. If only CURRENT_REVISION was requested then only the current revision’s commit data will be output.

  • CURRENT_FILES: list files modified by the commit, including basic line counts inserted/deleted per file. Only valid when the current revision or all revisions are selected.

  • ALL_FILES: list files modified by the commit, including basic line counts inserted/deleted per file. If only the CURRENT_REVISION was requested the only that commit’s modified files will be output.

  • DETAILED_ACCOUNTS: include _account_id and email fields when referencing accounts.

Request
  GET /changes/?q=97&o=CURRENT_REVISION&o=CURRENT_COMMIT&o=CURRENT_FILES HTTP/1.0
Response
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json;charset=UTF-8

  )]}'
  [
    {
      "kind": "gerritcodereview#change",
      "id": "demo~master~I7ea46d2e2ee5c64c0d807677859cfb7d90b8966a",
      "project": "gerrit",
      "branch": "master",
      "change_id": "I7ea46d2e2ee5c64c0d807677859cfb7d90b8966a",
      "subject": "Use an EventBus to manage star icons",
      "status": "NEW",
      "created": "2012-04-25 00:52:25.580000000",
      "updated": "2012-04-25 00:52:25.586000000",
      "mergeable": true,
      "_sortkey": "001c9bf400000061",
      "_number": 97,
      "owner": {
        "name": "Shawn Pearce"
      },
      "current_revision": "184ebe53805e102605d11f6b143486d15c23a09c",
      "revisions": {
        "184ebe53805e102605d11f6b143486d15c23a09c": {
          "_number": 1,
          "fetch": {
            "git": {
              "url": "git://localhost/gerrit",
              "ref": "refs/changes/97/97/1"
            },
            "http": {
              "url": "http://127.0.0.1:8080/gerrit",
              "ref": "refs/changes/97/97/1"
            }
          },
          "commit": {
            "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 ..."
          },
          "files": {
            "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeCache.java": {
              "lines_deleted": 8
            },
            "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeDetailCache.java": {
              "lines_inserted": 1
            },
            "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeScreen.java": {
              "lines_inserted": 11,
              "lines_deleted": 19
            },
            "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeTable.java": {
              "lines_inserted": 23,
              "lines_deleted": 20
            },
            "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/StarCache.java": {
              "status": "D",
              "lines_deleted": 139
            },
            "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/StarredChanges.java": {
              "status": "A",
              "lines_inserted": 204
            },
            "gerrit-gwtui/src/main/java/com/google/gerrit/client/ui/Screen.java": {
              "lines_deleted": 9
            }
          }
        }
      }
    }
  ]

Get Change

GET /changes/{change-id}

Retrieves a change.

Request
  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940 HTTP/1.0

As response a ChangeInfo entity is returned that describes the change.

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

  )]}'
  {
    "kind": "gerritcodereview#change",
    "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940",
    "project": "myProject",
    "branch": "master",
    "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940",
    "subject": "Implementing Feature X",
    "status": "NEW",
    "created": "2013-02-01 09:59:32.126000000",
    "updated": "2013-02-21 11:16:36.775000000",
    "reviewed": true,
    "mergeable": true,
    "_sortkey": "0023412400000f7d",
    "_number": 3965,
    "owner": {
      "name": "John Doe"
    }
  }

Get Change Detail

GET /changes/{change-id}/detail

Retrieves a change with labels, detailed labels and detailed accounts.

Request
  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/detail HTTP/1.0

As response a ChangeInfo entity is returned that describes the change.

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

  )]}'
  {
    "kind": "gerritcodereview#change",
    "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940",
    "project": "myProject",
    "branch": "master",
    "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940",
    "subject": "Implementing Feature X",
    "status": "NEW",
    "created": "2013-02-01 09:59:32.126000000",
    "updated": "2013-02-21 11:16:36.775000000",
    "reviewed": true,
    "mergeable": true,
    "_sortkey": "0023412400000f7d",
    "_number": 3965,
    "owner": {
      "_account_id": 1000096,
      "name": "John Doe",
      "email": "john.doe@example.com"
    },
    "labels": {
      "Verified": {
        "all": [
          {
            "value": 0,
            "_account_id": 1000096,
            "name": "John Doe",
            "email": "john.doe@example.com"
          },
          {
            "value": 0,
            "_account_id": 1000097,
            "name": "Jane Roe",
            "email": "jane.roe@example.com"
          }
        ],
        "values": {
          "-1": "Fails",
          " 0": "No score",
          "+1": "Verified"
        }
      },
      "Code-Review": {
        "recommended": {
          "_account_id": 1000097,
          "name": "Jane Roe",
          "email": "jane.roe@example.com"
        },
        "disliked": {
          "_account_id": 1000096,
          "name": "John Doe",
          "email": "john.doe@example.com"
        },
        "all": [
          {
            "value": -1,
            "_account_id": 1000096,
            "name": "John Doe",
            "email": "john.doe@example.com"
          },
          {
            "value": 1,
            "_account_id": 1000097,
            "name": "Jane Roe",
            "email": "jane.roe@example.com"
          }
        ]
        "values": {
          "-2": "Do not submit",
          "-1": "I would prefer that you didn\u0027t submit this",
          " 0": "No score",
          "+1": "Looks good to me, but someone else must approve",
          "+2": "Looks good to me, approved"
        }
      }
    },
    "permitted_labels": {
      "Verified": [
        "-1",
        " 0",
        "+1"
      ],
      "Code-Review": [
        "-2",
        "-1",
        " 0",
        "+1",
        "+2"
      ]
    },
    "removable_reviewers": [
      {
        "_account_id": 1000096,
        "name": "John Doe",
        "email": "john.doe@example.com"
      },
      {
        "_account_id": 1000097,
        "name": "Jane Roe",
        "email": "jane.roe@example.com"
      }
    ]
  }

Get Topic

GET /changes/{change-id}/topic

Retrieves the topic of a change.

Request
  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/topic HTTP/1.0
Response
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json;charset=UTF-8

  )]}'
  "Documentation"

If the change does not have a topic an empty string is returned.

Set Topic

PUT /changes/{change-id}/topic

Sets the topic of a change.

The new topic must be provided in the request body inside a TopicInput entity.

Request
  PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/topic HTTP/1.0
  Content-Type: application/json;charset=UTF-8

  {
    "topic": "Documentation"
  }

As response the new topic is returned.

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

  )]}'
  "Documentation"

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

Delete Topic

DELETE /changes/{change-id}/topic

Deletes the topic of a change.

The request body does not need to include a TopicInput entity if no review comment is added.

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

Request
  DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/topic HTTP/1.0
Response
  HTTP/1.1 204 No Content

Abandon Change

POST /changes/{change-id}/abandon

Abandons a change.

The request body does not need to include a AbandonInput entity if no review comment is added.

Request
  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/abandon HTTP/1.0

As response a ChangeInfo entity is returned that describes the abandoned change.

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

  )]}'
  {
    "kind": "gerritcodereview#change",
    "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940",
    "project": "myProject",
    "branch": "master",
    "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940",
    "subject": "Implementing Feature X",
    "status": "ABANDONED",
    "created": "2013-02-01 09:59:32.126000000",
    "updated": "2013-02-21 11:16:36.775000000",
    "reviewed": true,
    "mergeable": true,
    "_sortkey": "0023412400000f7d",
    "_number": 3965,
    "owner": {
      "name": "John Doe"
    }
  }

If the change cannot be abandoned because the change state doesn’t allow abandoning of the change, the response is "409 Conflict" and the error message is contained in the response body.

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

  change is merged

Restore Change

POST /changes/{change-id}/restore

Restores a change.

The request body does not need to include a RestoreInput entity if no review comment is added.

Request
  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/restore HTTP/1.0

As response a ChangeInfo entity is returned that describes the restored change.

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

  )]}'
  {
    "kind": "gerritcodereview#change",
    "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940",
    "project": "myProject",
    "branch": "master",
    "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940",
    "subject": "Implementing Feature X",
    "status": "NEW",
    "created": "2013-02-01 09:59:32.126000000",
    "updated": "2013-02-21 11:16:36.775000000",
    "reviewed": true,
    "mergeable": true,
    "_sortkey": "0023412400000f7d",
    "_number": 3965,
    "owner": {
      "name": "John Doe"
    }
  }

If the change cannot be restored because the change state doesn’t allow restoring the change, the response is "409 Conflict" and the error message is contained in the response body.

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

  change is new

Revert Change

POST /changes/{change-id}/revert

Reverts a change.

The request body does not need to include a RevertInput entity if no review comment is added.

Request
  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revert HTTP/1.0

As response a ChangeInfo entity is returned that describes the reverting change.

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

  )]}'
  {
    "kind": "gerritcodereview#change",
    "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940",
    "project": "myProject",
    "branch": "master",
    "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940",
    "subject": "Revert \"Implementing Feature X\"",
    "status": "NEW",
    "created": "2013-02-01 09:59:32.126000000",
    "updated": "2013-02-21 11:16:36.775000000",
    "reviewed": true,
    "mergeable": true,
    "_sortkey": "0023412400000f7d",
    "_number": 3965,
    "owner": {
      "name": "John Doe"
    }
  }

If the change cannot be reverted because the change state doesn’t allow reverting the change, the response is "409 Conflict" and the error message is contained in the response body.

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

  change is new

Submit Change

POST /changes/{change-id}/submit

Submits a change.

The request body only needs to include a SubmitInput entity if the request should wait for the merge to complete.

Request
  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/submit HTTP/1.0
  Content-Type: application/json;charset=UTF-8

  {
    "wait_for_merge": true
  }

As response a ChangeInfo entity is returned that describes the submitted/merged change.

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

  )]}'
  {
    "kind": "gerritcodereview#change",
    "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940",
    "project": "myProject",
    "branch": "master",
    "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940",
    "subject": "Implementing Feature X",
    "status": "MERGED",
    "created": "2013-02-01 09:59:32.126000000",
    "updated": "2013-02-21 11:16:36.775000000",
    "reviewed": true,
    "_sortkey": "0023412400000f7d",
    "_number": 3965,
    "owner": {
      "name": "John Doe"
    }
  }

If the change cannot be submitted because the submit rule doesn’t allow submitting the change, the response is "409 Conflict" and the error message is contained in the response body.

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

  blocked by Verified

Reviewer Endpoints

List Reviewers

GET /changes/{change-id}/reviewers/

Lists the reviewers of a change.

As result a list of ReviewerInfo entries is returned.

Request
  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/ HTTP/1.0
Response
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json;charset=UTF-8

  )]}'
  [
    {
      "kind": "gerritcodereview#reviewer",
      "approvals": {
        "Verified": "+1",
        "Code-Review": "+2"
      },
      "_account_id": 1000096,
      "name": "John Doe",
      "email": "john.doe@example.com"
    },
    {
      "kind": "gerritcodereview#reviewer",
      "approvals": {
        "Verified": " 0",
        "Code-Review": "-1"
      },
      "_account_id": 1000097,
      "name": "Jane Roe",
      "email": "jane.roe@example.com"
    }
  ]

Get Reviewer

GET /changes/{change-id}/reviewers/{account-id}

Retrieves a reviewer of a change.

As response a ReviewerInfo entity is returned that describes the reviewer.

Request
  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/john.doe@example.com HTTP/1.0
Response
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json;charset=UTF-8

  )]}'
  {
    "kind": "gerritcodereview#reviewer",
    "approvals": {
      "Verified": "+1",
      "Code-Review": "+2"
    },
    "_account_id": 1000096,
    "name": "John Doe",
    "email": "john.doe@example.com"
  }

Add Reviewer

POST /changes/{change-id}/reviewers

Adds one user or all members of one group as reviewer to the change.

The reviewer to be added to the change must be provided in the request body as a ReviewerInput entity.

Request
  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers HTTP/1.0
  Content-Type: application/json;charset=UTF-8

  {
    "reviewer": "john.doe@example.com"
  }

As response an AddReviewerResult entity is returned that describes the newly added reviewers.

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

  )]}'
  {
    "reviewers": [
      {
        "kind": "gerritcodereview#reviewer",
        "approvals": {
          "Verified": " 0",
          "Code-Review": " 0"
        },
        "_account_id": 1000096,
        "name": "John Doe",
        "email": "john.doe@example.com"
      }
    ]
  }

If a group is specified, adding the group members as reviewers is an atomic operation. This means if an error is returned, none of the members are added as reviewer.

If a group with many members is added as reviewer a confirmation may be required.

Request
  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers HTTP/1.0
  Content-Type: application/json;charset=UTF-8

  {
    "reviewer": "MyProjectVerifiers"
  }
Response
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json;charset=UTF-8

  )]}'
  {
    "error": "The group My Group has 15 members. Do you want to add them all as reviewers?",
    "confirm": true
  }

To confirm the addition of the reviewers, resend the request with the confirmed flag being set.

Request
  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers HTTP/1.0
  Content-Type: application/json;charset=UTF-8

  {
    "reviewer": "MyProjectVerifiers",
    "confirmed": true
  }

Delete Reviewer

DELETE /changes/{change-id}/reviewers/{account-id}

Deletes a reviewer from a change.

Request
  DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe HTTP/1.0
Response
  HTTP/1.1 204 No Content

Revision Endpoints

Get Review

GET /changes/{change-id}/revisions/{revision-id}/review

Retrieves a review of a revision.

Request
  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/review HTTP/1.0

As response a ChangeInfo entity with detailed labels and detailed accounts is returned that describes the review of the revision. The revision for which the review is retrieved is contained in the revisions field. In addition the current_revision field is set if the revision for which the review is retrieved is the current revision of the change. Please note that the returned labels are always for the current patch set.

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

  )]}'
  {
    "kind": "gerritcodereview#change",
    "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940",
    "project": "myProject",
    "branch": "master",
    "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940",
    "subject": "Implementing Feature X",
    "status": "NEW",
    "created": "2013-02-01 09:59:32.126000000",
    "updated": "2013-02-21 11:16:36.775000000",
    "reviewed": true,
    "mergeable": true,
    "_sortkey": "0023412400000f7d",
    "_number": 3965,
    "owner": {
      "_account_id": 1000096,
      "name": "John Doe",
      "email": "john.doe@example.com"
    },
    "labels": {
      "Verified": {
        "all": [
          {
            "value": 0,
            "_account_id": 1000096,
            "name": "John Doe",
            "email": "john.doe@example.com"
          },
          {
            "value": 0,
            "_account_id": 1000097,
            "name": "Jane Roe",
            "email": "jane.roe@example.com"
          }
        ],
        "values": {
          "-1": "Fails",
          " 0": "No score",
          "+1": "Verified"
        }
      },
      "Code-Review": {
        "all": [
          {
            "value": -1,
            "_account_id": 1000096,
            "name": "John Doe",
            "email": "john.doe@example.com"
          },
          {
            "value": 1,
            "_account_id": 1000097,
            "name": "Jane Roe",
            "email": "jane.roe@example.com"
          }
        ]
        "values": {
          "-2": "Do not submit",
          "-1": "I would prefer that you didn\u0027t submit this",
          " 0": "No score",
          "+1": "Looks good to me, but someone else must approve",
          "+2": "Looks good to me, approved"
        }
      }
    },
    "permitted_labels": {
      "Verified": [
        "-1",
        " 0",
        "+1"
      ],
      "Code-Review": [
        "-2",
        "-1",
        " 0",
        "+1",
        "+2"
      ]
    },
    "removable_reviewers": [
      {
        "_account_id": 1000096,
        "name": "John Doe",
        "email": "john.doe@example.com"
      },
      {
        "_account_id": 1000097,
        "name": "Jane Roe",
        "email": "jane.roe@example.com"
      }
    ],
    "current_revision": "674ac754f91e64a0efb8087e59a176484bd534d1",
    "revisions": {
      "674ac754f91e64a0efb8087e59a176484bd534d1": {
      "_number": 2,
      "fetch": {
        "http": {
          "url": "http://gerrit/myProject",
          "ref": "refs/changes/65/3965/2"
        }
      }
    }
  }

Set Review

POST /changes/{change-id}/revisions/{revision-id}/review

Sets a review on a revision.

The review must be provided in the request body as a ReviewInput entity.

Request
  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/review HTTP/1.0
  Content-Type: application/json;charset=UTF-8

  {
    "message": "Some nits need to be fixed.",
    "labels": {
      "Code-Review": -1
    },
    "comments": {
      "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": [
        {
          "line": 23,
          "message": "[nit] trailing whitespace"
        },
        {
          "line": 49,
          "message": "[nit] s/conrtol/control"
        }
      ]
    }
  }

As response a ReviewInfo entity is returned that describes the applied labels.

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

  )]}'
  {
    "labels": {
      "Code-Review": -1
    }
  }

Submit Revision

POST /changes/{change-id}/revisions/{revision-id}/submit

Submits a revision.

The request body only needs to include a SubmitInput entity if the request should wait for the merge to complete.

Request
  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/submit HTTP/1.0
  Content-Type: application/json;charset=UTF-8

  {
    "wait_for_merge": true
  }

As response a SubmitInfo entity is returned that describes the status of the submitted change.

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

  )]}'
  {
    "status": "MERGED"
  }

If the revision cannot be submitted, e.g. because the submit rule doesn’t allow submitting the revision or the revision is not the current revision, the response is "409 Conflict" and the error message is contained in the response body.

Response
  HTTP/1.1 409 Conflict
  Content-Type: text/plain;charset=UTF-8

  "revision 674ac754f91e64a0efb8087e59a176484bd534d1 is not current revision"

Get Submit Type

GET /changes/{change-id}/revisions/{revision-id}/submit_type

Gets the method the server will use to submit (merge) the change.

Request
  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/submit_type HTTP/1.0
Response
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json;charset=UTF-8

  )]}'
  "MERGE_IF_NECESSARY"

Test Submit Type

POST /changes/{change-id}/revisions/{revision-id}/test.submit_type

Tests the submit_type Prolog rule in the project, or the one given.

Request body may be either the Prolog code as text/plain or a RuleInput object. The query parameter filters may be set to SKIP to bypass parent project filters while testing a project-specific rule.

Request
  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/test.submit_type HTTP/1.0
  Content-Type: text/plain;charset-UTF-8

  submit_type(cherry_pick).
Response
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json;charset=UTF-8

  )]}'
  "cherry_pick"

Test Submit Rule

POST /changes/{change-id}/revisions/{revision-id}/test.submit_rule

Tests the submit_rule Prolog rule in the project, or the one given.

Request body may be either the Prolog code as text/plain or a RuleInput object. The query parameter filters may be set to SKIP to bypass parent project filters while testing a project-specific rule.

Request
  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/test.submit_type?filters=SKIP HTTP/1.0
  Content-Type: text/plain;charset-UTF-8

  submit_rule(submit(R)) :-
    R = label('Any-Label-Name', reject(_)).

The response is a list of SubmitRecord entries describing the permutations that satisfy the tested submit rule.

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

  )]}'
  [
    {
      "status": "NOT_READY",
      "reject": {
        "Any-Label-Name": {}
      }
    }
  ]

List Drafts

GET /changes/{change-id}/revisions/{revision-id}/drafts/

Lists the draft comments of a revision that belong to the calling user.

As result a map is returned that maps the file path to a list of CommentInfo entries. The entries in the map are sorted by file path.

Request
  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/drafts/ HTTP/1.0
Response
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json;charset=UTF-8

  )]}'
  {
    "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": [
      {
        "kind": "gerritcodereview#comment",
        "id": "TvcXrmjM",
        "line": 23,
        "message": "[nit] trailing whitespace",
        "updated": "2013-02-26 15:40:43.986000000"
      },
      {
        "kind": "gerritcodereview#comment",
        "id": "TveXwFiA",
        "line": 49,
        "in_reply_to": "TfYX-Iuo",
        "message": "Done",
        "updated": "2013-02-26 15:40:45.328000000"
      }
    ]
  }

Create Draft

PUT /changes/{change-id}/revisions/{revision-id}/drafts

Creates a draft comment on a revision.

The new draft comment must be provided in the request body inside a CommentInput entity.

Request
  PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/drafts HTTP/1.0
  Content-Type: application/json;charset=UTF-8

  {
    "path": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
    "line": 23,
    "message": "[nit] trailing whitespace"
  }

As response a CommentInfo entity is returned that describes the draft comment.

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

  )]}'
  {
    "kind": "gerritcodereview#comment",
    "id": "TvcXrmjM",
    "path": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
    "line": 23,
    "message": "[nit] trailing whitespace",
    "updated": "2013-02-26 15:40:43.986000000"
  }

Get Draft

GET /changes/{change-id}/revisions/{revision-id}/drafts/{draft-id}

Retrieves a draft comment of a revision that belongs to the calling user.

Request
  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/drafts/TvcXrmjM HTTP/1.0

As response a CommentInfo entity is returned that describes the draft comment.

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

  )]}'
  {
    "kind": "gerritcodereview#comment",
    "id": "TvcXrmjM",
    "path": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
    "line": 23,
    "message": "[nit] trailing whitespace",
    "updated": "2013-02-26 15:40:43.986000000"
  }

Update Draft

PUT /changes/{change-id}/revisions/{revision-id}/drafts/{draft-id}

Updates a draft comment on a revision.

The new draft comment must be provided in the request body inside a CommentInput entity.

Request
  PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/drafts/TvcXrmjM HTTP/1.0
  Content-Type: application/json;charset=UTF-8

  {
    "path": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
    "line": 23,
    "message": "[nit] trailing whitespace"
  }

As response a CommentInfo entity is returned that describes the draft comment.

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

  )]}'
  {
    "kind": "gerritcodereview#comment",
    "id": "TvcXrmjM",
    "path": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
    "line": 23,
    "message": "[nit] trailing whitespace",
    "updated": "2013-02-26 15:40:43.986000000"
  }

Delete Draft

DELETE /changes/{change-id}/revisions/{revision-id}/drafts/{draft-id}

Deletes a draft comment from a revision.

Request
  DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/drafts/TvcXrmjM HTTP/1.0
Response
  HTTP/1.1 204 No Content

Set Reviewed

PUT /changes/{change-id}/revisions/{revision-id}/files/{patch-id}/reviewed

Marks a patch of a revision as reviewed by the calling user.

Request
  PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/reviewed HTTP/1.0
Response
  HTTP/1.1 201 Created

If the patch was already marked as reviewed by the calling user the response is "200 OK".

Delete Reviewed

DELETE /changes/{change-id}/revisions/{revision-id}/files/{patch-id}/reviewed

Deletes the reviewed flag of the calling user from a patch of a revision.

Request
  DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/reviewed HTTP/1.0
Response
  HTTP/1.1 204 No Content

IDs

{account-id}

{change-id}

Identifier that uniquely identifies one change.

This can be:

  • an ID of the change in the format "<project>~<branch>~<Change-Id>", where for the branch the refs/heads/ prefix can be omitted ("myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940")

  • a Change-Id if it uniquely identifies one change ("I8473b95934b5732ac55d26311a706c9c2bde9940")

  • a legacy numeric change ID ("4247")

{draft-id}

UUID of a draft comment.

{patch-id}

The file path of the patch.

{revision-id}

Identifier that uniquely identifies one revision of a change.

This can be:

  • the literal current to name the current patch set/revision

  • a commit ID ("674ac754f91e64a0efb8087e59a176484bd534d1")

  • an abbreviated commit ID that uniquely identifies one revision of the change ("674ac754"), at least 4 digits are required

  • a legacy numeric patch number ("1" for first patch set of the change)

JSON Entities

AbandonInput

The AbandonInput entity contains information for abandoning a change.

Field Name Description

message

optional

Message to be added as review comment to the change when abandoning the change.

AddReviewerResult

The AddReviewerResult entity describes the result of adding a reviewer to a change.

Field Name Description

reviewers

optional

The newly added reviewers as a list of ReviewerInfo entities.

error

optional

Error message explaining why the reviewer could not be added.
If a group was specified in the input and an error is returned, it means that none of the members were added as reviewer.

confirm

false if not set

Whether adding the reviewer requires confirmation.

ApprovalInfo

The ApprovalInfo entity contains information about an approval from a user for a label on a change.

ApprovalInfo has the same fields as AccountInfo. In addition ApprovalInfo has the following fields:

Field Name Description

value

optional

The vote that the user has given for the label. If present and zero, the user is permitted to vote on the label. If absent, the user is not permitted to vote on that label.

ChangeInfo

The ChangeInfo entity contains information about a change.

Field Name Description

kind

gerritcodereview#change

id

The ID of the change in the format "<project>~<branch>~<Change-Id>", where project, branch and Change-Id are URL encoded. For branch the refs/heads/ prefix is omitted.

project

The name of the project.

branch

The name of the target branch.
The refs/heads/ prefix is omitted.

topic

optional

The topic to which this change belongs.

change_id

The Change-Id of the change.

subject

The subject of the change (header line of the commit message).

status

The status of the change (NEW, SUBMITTED, MERGED, ABANDONED, DRAFT).

created

The timestamp of when the change was created.

updated

The timestamp of when the change was last updated.

starred

not set if false

Whether the calling user has starred this change.

reviewed

not set if false

Whether the change was reviewed by the calling user.

mergeable

optional

Whether the change is mergeable.
Not set for merged changes.

_sortkey

The sortkey of the change.

_number

The legacy numeric ID of the change.

owner

The owner of the change as an AccountInfo entity.

labels

optional

The labels of the change as a map that maps the label names to LabelInfo entries.
Only set if labels or detailed labels are requested.

permitted_labels

optional

A map of the permitted labels that maps a label name to the list of values that are allowed for that label.
Only set if detailed labels are requested.

removable_reviewers

optional

The reviewers that can be removed by the calling user as a list of AccountInfo entities.
Only set if detailed labels are requested.

current_revision

optional

The commit ID of the current patch set of this change.
Only set if the current revision is requested or if all revisions are requested.

revisions

optional

All patch sets of this change as a map that maps the commit ID of the patch set to a RevisionInfo entity.
Only set if all revisions are requested.

_more_changes

optional, not set if false

Whether the query would deliver more results if not limited.
Only set on either the last or the first change that is returned.

CommentInfo

The CommentInfo entity contains information about an inline comment.

Field Name Description

kind

gerritcodereview#comment

id

The URL encoded UUID of the draft comment.

path

optional

The path of the file for which the inline comment was done.
Not set if returned in a map where the key is the file path.

side

optional

The side on which the comment was added.
Allowed values are REVISION and PARENT.
If not set, the default is REVISION.

line

optional

The number of the line for which the comment was done.
If not set, it’s a file comment.

in_reply_to

optional

The URL encoded UUID of the comment to which this comment is a reply.

message

optional

The comment message.

updated

The timestamp of when this comment was written.

CommentInput

The CommitInput entity contains information for creating an inline comment.

Field Name Description

kind

optional

Must be gerritcodereview#comment if provided.

id

optional

The URL encoded UUID of the comment if an existing draft comment should be updated.

path

optional

The path of the file for which the inline comment should be added.
Doesn’t need to be set if contained in a map where the key is the file path.

side

optional

The side on which the comment should be added.
Allowed values are REVISION and PARENT.
If not set, the default is REVISION.

line

optional

The number of the line for which the comment should be added.
0 if it is a file comment.
If not set, a file comment is added.

in_reply_to

optional

The URL encoded UUID of the comment to which this comment is a reply.

updated

optional

The timestamp of this comment.
Accepted but ignored.

message

optional

The comment message.
If not set and an existing draft comment is updated, the existing draft comment is deleted.

CommitInfo

The CommitInfo entity contains information about a commit.

Field Name Description

commit

The commit ID.

parent

The parent commits of this commit as a list of CommitInfo entities.

author

The author of the commit as a GitPersonInfo entity.

committer

The committer of the commit as a GitPersonInfo entity.

subject

The subject of the commit (header line of the commit message).

message

The commit message.

FetchInfo

The FetchInfo entity contains information about how to fetch a patch set via a certain protocol.

Field Name Description

url

The URL of the project.

ref

The ref of the patch set.

FileInfo

The FileInfo entity contains information about a file in a patch set.

Field Name Description

status

optional

The status of the file ("A"=Added, "D"=Deleted, "R"=Renamed, "C"=Copied, "W"=Rewritten).
Not set if the file was Modified ("M").

binary

not set if false

Whether the file is binary.

old_path

optional

The old file path.
Only set if the file was renamed or copied.

lines_inserted

optional

Number of inserted lines.
Not set for binary files or if no lines were inserted.

lines_deleted

optional

Number of deleted lines.
Not set for binary files or if no lines were deleted.

GitPersonInfo

The GitPersonInfo entity contains information about the author/committer of a commit.

Field Name Description

name

The name of the author/committer.

email

The email address of the author/committer.

date

The timestamp of when this identity was constructed.

tz

The timezone offset from UTC of when this identity was constructed.

LabelInfo

The LabelInfo entity contains information about a label on a change.

Field Name Description

approved

optional

The user who approved this label on the change as a AccountInfo entity.
Only set if labels are requested.

rejected

optional

The user who rejected this label on the change as a AccountInfo entity.
Only set if labels are requested.

recommended

optional

The user who recommended this label on the change as a AccountInfo entity.
Only set if labels are requested.

disliked

optional

The user who disliked this label on the change as a AccountInfo entity.
Only set if labels are requested.

value

optional

The voting value of the user who recommended/disliked this label on the change if it is not "+1"/"-1".
Only set if labels are requested.

optional

not set if false

Whether the label is optional. Optional means the label may be set, but it’s neither necessary for submission nor does it block submission if set.

all

optional

List of all approvals for this label as a list of ApprovalInfo entities.
Only set if detailed labels are requested.

values

optional

A map of all values that are allowed for this label. The map maps the values ("-2", "-1", " 0", "+1", "+2") to the value descriptions.
Only set if detailed labels are requested.

RestoreInput

The RestoreInput entity contains information for restoring a change.

Field Name Description

message

optional

Message to be added as review comment to the change when restoring the change.

RevertInput

The RevertInput entity contains information for reverting a change.

Field Name Description

message

optional

Message to be added as review comment to the change when reverting the change.

ReviewInfo

The ReviewInfo entity contains information about a review.

Field Name Description

labels

The labels of the review as a map that maps the label names to the voting values.

ReviewInput

The ReviewInput entity contains information for adding a review to a revision.

Field Name Description

message

optional

The message to be added as review comment.

labels

optional

The votes that should be added to the revision as a map that maps the label names to the voting values.

comments

optional

The comments that should be added as a map that maps a file path to a list of CommentInput entities.

strict_labels

true if not set

Whether all labels are required to be within the user’s permitted ranges based on access controls.
If true, attempting to use a label not granted to the user will fail the entire modify operation early.
If false, the operation will execute anyway, but the proposed labels will be modified to be the "best" value allowed by the access controls.

drafts

optional

Draft handling that defines how draft comments are handled that are already in the database but that were not also described in this input.
Allowed values are DELETE, PUBLISH and KEEP.
If not set, the default is DELETE.

notify

optional

Notify handling that defines to whom email notifications should be sent after the review is stored.
Allowed values are NONE, OWNER, OWNER_REVIEWERS and ALL.
If not set, the default is ALL.

ReviewerInfo

The ReviewerInfo entity contains information about a reviewer and its votes on a change.

ReviewerInfo has the same fields as AccountInfo and includes detailed account information. In addition ReviewerInfo has the following fields:

Field Name Description

kind

gerritcodereview#reviewer

approvals

The approvals of the reviewer as a map that maps the label names to the approval values ("-2", "-1", " 0", "+1", "+2").

ReviewerInput

The ReviewerInput entity contains information for adding a reviewer to a change.

Field Name Description

reviewer

The ID of one account that should be added as reviewer or the ID of one group for which all members should be added as reviewers.
If an ID identifies both an account and a group, only the account is added as reviewer to the change.

confirmed

optional

Whether adding the reviewer is confirmed.
The Gerrit server may be configured to require a confirmation when adding a group as reviewer that has many members.

RevisionInfo

The RevisionInfo entity contains information about a patch set.

Field Name Description

draft

not set if false

Whether the patch set is a draft.

_number

The patch set number.

fetch

Information about how to fetch this patch set. The fetch information is provided as a map that maps the protocol name ("git", "http", "ssh") to FetchInfo entities.

commit

The commit of the patch set as CommitInfo entity.

files

The files of the patch set as a map that maps the file names to FileInfo entities.

RuleInput

The RuleInput entity contains information to test a Prolog rule.

Field Name Description

rule

Prolog code to execute instead of the code in refs/meta/config.

filters

RUN if not set

When RUN filter rules in the parent projects are called to post-process the results of the project specific rule. This behavior matches how the rule will execute if installed.
If SKIP the parent filters are not called, allowing the test to return results from the input rule.

SubmitInfo

The SubmitInfo entity contains information about the change status after submitting.

Field Name Description

status

The status of the change after submitting, can be MERGED or SUBMITTED.
If wait_for_merge in the SubmitInput was set to false the returned status is SUBMITTED and the caller can’t know whether the change could be merged successfully.

SubmitInput

The SubmitInput entity contains information for submitting a change.

Field Name Description

wait_for_merge

false if not set

Whether the request should wait for the merge to complete.
If false the request returns immediately after the change has been added to the merge queue and the caller can’t know whether the change could be merged successfully.

SubmitRecord

The SubmitRecord entity describes results from a submit_rule.

Field Name Description

status

OK, the change can be submitted.
NOT_READY, additional labels are required before submit.
CLOSED, closed changes cannot be submitted.
RULE_ERROR, rule code failed with an error.

ok

optional

Map of labels that are approved; an AccountInfo identifies the voter chosen by the rule.

reject

optional

Map of labels that are preventing submit; AccountInfo identifies voter.

need

optional

Map of labels that need to be given to submit. The value is currently an empty object.

may

optional

Map of labels that can be used, but do not affect submit. AccountInfo identifies voter, if the label has been applied.

impossible

optional

Map of labels that should have been in need but cannot be used by any user because of access restrictions. The value is currently an empty object.

error_message

optional

When status is RULE_ERROR this message provides some text describing the failure of the rule predicate.

TopicInput

The TopicInput entity contains information for setting a topic.

Field Name Description

topic

optional

The topic.
The topic will be deleted if not set.

message

optional

Message to be added as review comment to the change when setting the topic.

Part of Gerrit Code Review