Documentation/rest-api-changes.txt

Gerrit Code Review - '/changes/' REST API
=========================================

This page describes the change related REST endpoints.
Please also take note of the general information on the
link:rest-api.html[REST API].

[[change-endpoints]]
Change Endpoints
----------------

[[list-changes]]
GET /changes/ (Query 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 link:#change-info[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
****

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
****

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]]
--
* `LABELS`: a summary of each label required for submit, and
  approvers that have granted (or rejected) with that label.
--

[[detailed-labels]]
--
* `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]]
--
* `CURRENT_REVISION`: describe the current revision (patch set)
  of the change, including the commit SHA-1 and URLs to fetch from.
--

[[all-revisions]]
--
* `ALL_REVISIONS`: describe all revisions, not just current.
--

[[current-commit]]
--
* `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]]
--
* `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]]
--
* `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]]
--
* `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]]
--
* `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\} (Get Change)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Retrieves a change.

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

As response a link:#change-info[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 (Get Change Detail)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Retrieves a change with link:#labels[labels], link:#detailed-labels[
detailed labels] and link:#detailed-accounts[detailed accounts].

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

As response a link:#change-info[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 (Get 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 (Set Topic)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the topic of a change.

The new topic must be provided in the request body inside a
link:#topic-input[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 (Delete Topic)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Deletes the topic of a change.

The request body does not need to include a link:#topic-input[
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
link:#set-topic[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 (Abandon Change)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Abandons a change.

The request body does not need to include a link:#abandon-input[
AbandonInput] entity if no review comment is added.

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

As response a link:#change-info[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 (Restore Change)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Restores a change.

The request body does not need to include a link:#restore-input[
RestoreInput] entity if no review comment is added.

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

As response a link:#change-info[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 (Revert Change)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Reverts a change.

The request body does not need to include a link:#revert-input[
RevertInput] entity if no review comment is added.

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

As response a link:#change-info[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 (Submit Change)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Submits a change.

The request body only needs to include a link:#submit-input[
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 link:#change-info[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,
    "mergeable": 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]]
Reviewer Endpoints
------------------

[[list-reviewers]]
GET /changes/\{change-id\}/reviewers/ (List Reviewers)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Lists the reviewers of a change.

As result a list of link:#reviewer-info[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\} (Get Reviewer)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Retrieves a reviewer of a change.

As response a link:#reviewer-info[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 (Add Reviewer)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 link:#reviewer-input[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 link:#add-reviewer-result[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
`confirm` flag being set.

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

  {
    "reviewer": "MyProjectVerifiers",
    "confirm": true
  }
----

[[delete-reviewer]]
DELETE /changes/\{change-id\}/reviewers/\{account-id\} (Delete Reviewer)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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]]
Revision Endpoints
------------------

[[get-review]]
GET /changes/\{change-id\}/revisions/\{revision-id\}/review (Get Review)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Retrieves a review of a revision.

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

As response a link:#change-info[ChangeInfo] entity with
link:#detailed-labels[detailed labels] and link:#detailed-accounts[
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 (Set Review)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets a review on a revision.

The review must be provided in the request body as a
link:#review-input[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 link:#review-info[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 (Submit Revision)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Submits a revision.

The request body only needs to include a link:#submit-input[
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 link:#submit-info[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"
----

[[list-drafts]]
GET /changes/\{change-id\}/revisions/\{revision-id\}/drafts/ (List 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
link:#comment-info[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 (Create Draft)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Creates a draft comment on a revision.

The new draft comment must be provided in the request body inside a
link:#comment-input[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 link:#comment-info[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\} (Get Draft)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 link:#comment-info[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\} (Update Draft)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Updates a draft comment on a revision.

The new draft comment must be provided in the request body inside a
link:#comment-input[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 link:#comment-info[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\} (Delete Draft)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 (Set 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 (Delete 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]]
IDs
---

[[account-id]]
link:rest-api-accounts.html#account-id[\{account-id\}]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--
--

[[change-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]]
\{draft-id\}
~~~~~~~~~~~~
UUID of a draft comment.

[[patch-id]]
\{patch-id\}
~~~~~~~~~~~~
The file path of the patch.

[[revision-id]]
\{revision-id\}
~~~~~~~~~~~~~~~
Identifier that uniquely identifies one revision of a change.

This can be:

* 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]]
JSON Entities
-------------

[[abandon-input]]
AbandonInput
~~~~~~~~~~~~
The `AbandonInput` entity contains information for abandoning a change.

[options="header",width="50%",cols="1,^1,5"]
|===========================
|Field Name    ||Description
|`message`     |optional|
Message to be added as review comment to the change when abandoning the
change.
|===========================

[[account-info]]
AccountInfo
~~~~~~~~~~~
The `AccountInfo` entity contains information about an account.

[options="header",width="50%",cols="1,^1,5"]
|===========================
|Field Name    ||Description
|`_account_id` ||The numeric ID of the account.
|`name`        |optional|The full name of the user. +
Only set if link:#detailed-accounts[detailed account information] is
requested.
|`email`       |optional|
The email address the user prefers to be contacted through. +
Only set if link:#detailed-accounts[detailed account information] is
requested.
|===========================

[[add-reviewer-result]]
AddReviewerResult
~~~~~~~~~~~~~~~~~
The `AddReviewerResult` entity describes the result of adding a
reviewer to a change.

[options="header",width="50%",cols="1,^1,5"]
|===========================
|Field Name    ||Description
|`reviewers`   |optional|
The newly added reviewers as a list of link:#reviewer-info[
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.
|===========================

[[approval-info]]
ApprovalInfo
~~~~~~~~~~~~
The `ApprovalInfo` entity contains information about an approval from a
user for a label on a change.

`ApprovalInfo` has the same fields as link:#account-info[AccountInfo].
In addition `ApprovalInfo` has the following fields:

[options="header",width="50%",cols="1,^1,5"]
|===========================
|Field Name    ||Description
|`value`       ||The vote that the user has given for the label.
|===========================

[[change-info]]
ChangeInfo
~~~~~~~~~~
The `ChangeInfo` entity contains information about a change.

[options="header",width="50%",cols="1,^1,5"]
|==================================
|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 link:rest-api.html#timestamp[timestamp] of when the change was
created.
|`updated`            ||
The link:rest-api.html#timestamp[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`          ||Whether the change is mergeable.
|`_sortkey`           ||The sortkey of the change.
|`_number`            ||The legacy numeric ID of the change.
|`owner`              ||
The owner of the change as an link:#account-info[AccountInfo] entity.
|`labels`             |optional|
The labels of the change as a map that maps the label names to
link:#label-info[LabelInfo] entries. +
Only set if link:#labels[labels] or link:#detailed-labels[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 link:#detailed-labels[detailed labels] are requested.
|`removable_reviewers`|optional|
The reviewers that can be removed by the calling user as a list of
link:#account-info[AccountInfo] entities. +
Only set if link:#detailed-labels[detailed labels] are requested.
|`current_revision`   |optional|
The commit ID of the current patch set of this change. +
Only set if link:#current-revision[the current revision] is requested
or if link:#all-revisions[all revisions] are requested.
|`revisions`          |optional|
All patch sets of this changes as a map that maps the commit ID of the
patch set to a link:#revision-info[RevisionInfo] entity. +
Only set if link:#all-revisions[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.
|==================================

[[comment-info]]
CommentInfo
~~~~~~~~~~~
The `CommitInfo` entity contains information about an inline comment.

[options="header",width="50%",cols="1,^1,5"]
|===========================
|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 link:rest-api.html#timestamp[timestamp] of when this comment was
written.
|===========================

[[comment-input]]
CommentInput
~~~~~~~~~~~~
The `CommitInput` entity contains information for creating an inline
comment.

[options="header",width="50%",cols="1,^1,5"]
|===========================
|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 link:rest-api.html#timestamp[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.
|===========================

[[commit-info]]
CommitInfo
~~~~~~~~~~
The `CommitInfo` entity contains information about a commit.

[options="header",width="50%",cols="1,6"]
|==========================
|Field Name    |Description
|`commit`      |The commit ID.
|`parent`      |
The parent commits of this commit as a list of
link:#commit-info[CommitInfo] entities.
|`author`      |The author of the commit as a
link:#git-person-info[GitPersonInfo] entity.
|`committer`   |The committer of the commit as a
link:#git-person-info[GitPersonInfo] entity.
|`subject`     |
The subject of the commit (header line of the commit message).
|`message`     |The commit message.
|==========================

[[fetch-info]]
FetchInfo
~~~~~~~~~
The `FetchInfo` entity contains information about how to fetch a patch
set via a certain protocol.

[options="header",width="50%",cols="1,6"]
|==========================
|Field Name    |Description
|`url`         |The URL of the project.
|`ref`         |The ref of the patch set.
|==========================

[[file-info]]
FileInfo
~~~~~~~~
The `FileInfo` entity contains information about a file in a patch set.

[options="header",width="50%",cols="1,^1,5"]
|=============================
|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 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.
|=============================

[[git-person-info]]
GitPersonInfo
~~~~~~~~~~~~~
The `GitPersonInfo` entity contains information about the
author/committer of a commit.

[options="header",width="50%",cols="1,6"]
|==========================
|Field Name    |Description
|`name`        |The name of the author/committer.
|`email`       |The email address of the author/committer.
|`date`        |The link:rest-api.html#timestamp[timestamp] of when
this identity was constructed.
|`tz`          |The timezone offset from UTC of when this identity was
constructed.
|==========================

[[label-info]]
LabelInfo
~~~~~~~~~
The `LabelInfo` entity contains information about a label on a change.

[options="header",width="50%",cols="1,^1,5"]
|===========================
|Field Name    ||Description
|`approved`    |optional|The user who approved this label on the change
as a link:#account-info[AccountInfo] entity. +
Only set if link:#labels[labels] are requested.
|`rejected`    |optional|The user who rejected this label on the change
as a link:#account-info[AccountInfo] entity. +
Only set if link:#labels[labels] are requested.
|`recommended` |optional|The user who recommended this label on the
change as a link:#account-info[AccountInfo] entity. +
Only set if link:#labels[labels] are requested.
|`disliked`    |optional|The user who disliked this label on the change
as a link:#account-info[AccountInfo] entity. +
Only set if link:#labels[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 link:#labels[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 link:#approval-info[ApprovalInfo] entities. +
Only set if link:#detailed-labels[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 link:#detailed-labels[detailed labels] are requested.
|===========================

[[restore-input]]
RestoreInput
~~~~~~~~~~~~
The `RestoreInput` entity contains information for restoring a change.

[options="header",width="50%",cols="1,^1,5"]
|===========================
|Field Name    ||Description
|`message`     |optional|
Message to be added as review comment to the change when restoring the
change.
|===========================

[[revert-input]]
RevertInput
~~~~~~~~~~~
The `RevertInput` entity contains information for reverting a change.

[options="header",width="50%",cols="1,^1,5"]
|===========================
|Field Name    ||Description
|`message`     |optional|
Message to be added as review comment to the change when reverting the
change.
|===========================

[[review-info]]
ReviewInfo
~~~~~~~~~~
The `ReviewInfo` entity contains information about a review.

[options="header",width="50%",cols="1,6"]
|===========================
|Field Name     |Description
|`labels`       |
The labels of the review as a map that maps the label names to the
voting values.
|===========================

[[review-input]]
ReviewInput
~~~~~~~~~~~
The `ReviewInput` entity contains information for adding a review to a
revision.

[options="header",width="50%",cols="1,^1,5"]
|============================
|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 link:#comment-input[CommentInput] entities.
|`strict_labels`|`true` if not set|
Whether all labels are rquired 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`.
|============================

[[reviewer-info]]
ReviewerInfo
~~~~~~~~~~~~
The `ReviewerInfo` entity contains information about a reviewer and its
votes on a change.

`ReviewerInfo` has the same fields as link:#account-info[AccountInfo]
and includes link:#detailed-accounts[detailed account information].
In addition `ReviewerInfo` has the following fields:

[options="header",width="50%",cols="1,6"]
|==========================
|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`").
|==========================

[[reviewer-input]]
ReviewerInput
~~~~~~~~~~~~~
The `ReviewerInput` entity contains information for adding a reviewer
to a change.

[options="header",width="50%",cols="1,^1,5"]
|===========================
|Field Name    ||Description
|`reviewer`    ||
The link:rest-api-accounts.html#account-id[ID] of one account that
should be added as reviewer or the link:rest-api-groups.html#group-id[
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
link:config-gerrit.html#addreviewer.maxWithoutConfirmation[require a
confirmation] when adding a group as reviewer that has many members.
|===========================

[[revision-info]]
RevisionInfo
~~~~~~~~~~~~
The `RevisionInfo` entity contains information about a patch set.

[options="header",width="50%",cols="1,^1,5"]
|===========================
|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 link:#fetch-info[FetchInfo] entities.
|`commit`      ||The commit of the patch set as
link:#commit-info[CommitInfo] entity.
|`files`       ||
The files of the patch set as a map that maps the file names to
link:#file-info[FileInfo] entities.
|===========================

[[submit-info]]
SubmitInfo
~~~~~~~~~~
The `SubmitInfo` entity contains information about the change status
after submitting.

[options="header",width="50%",cols="1,6"]
|==========================
|Field Name    |Description
|`status`      |
The status of the change after submitting, can be `MERGED` or
`SUBMITTED`. +
If `wait_for_merge` in the link:#submit-input[SubmitInput] was set to
`false` the returned status is `SUBMITTED` and the caller can't know
whether the change could be merged successfully.
|==========================

[[submit-input]]
SubmitInput
~~~~~~~~~~~
The `SubmitInput` entity contains information for submitting a change.

[options="header",width="50%",cols="1,^1,5"]
|===========================
|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.
|===========================

[[topic-input]]
TopicInput
~~~~~~~~~~
The `TopicInput` entity contains information for setting a topic.

[options="header",width="50%",cols="1,^1,5"]
|===========================
|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.
|===========================


GERRIT
------
Part of link:index.html[Gerrit Code Review]