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

Change Endpoints

Create Change

'POST /changes'

The change info ChangeInfo entity must be provided in the request body. Only the following attributes are honored: project, branch, subject, status and topic. The first three attributes are mandatory. Valid values for status are: DRAFT and NEW.

Request
  POST /changes HTTP/1.0
  Content-Type: application/json; charset=UTF-8

  {
    "project" : "myProject",
    "subject" : "Let's support 100% Gerrit workflow direct in browser",
    "branch" : "master",
    "topic" : "create-change-in-browser",
    "status" : "DRAFT"
  }

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

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

  )]}'
  {
    "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9941",
    "project": "myProject",
    "branch": "master",
    "topic": "create-change-in-browser",
    "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9941",
    "subject": "Let's support 100% Gerrit workflow direct in browser",
    "status": "DRAFT",
    "created": "2014-05-05 07:15:44.639000000",
    "updated": "2014-05-05 07:15:44.639000000",
    "mergeable": true,
    "insertions": 0,
    "deletions": 0,
    "_number": 4711,
    "owner": {
      "name": "John Doe"
    }
  }

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

  )]}'
  [
    {
      "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",
      "mergeable": true,
      "insertions": 26,
      "deletions": 10,
      "_number": 1756,
      "owner": {
        "name": "John Doe"
      },
    },
    {
      "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,
      "insertions": 12,
      "deletions": 18,
      "_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.

The S or start query parameter can be supplied to skip a number of changes from the list.

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

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

  )]}'
  [
    [
      {
        "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",
        "mergeable": true,
        "insertions": 4,
        "deletions": 7,
        "_number": 1756,
        "owner": {
          "name": "John Doe"
        },
        "labels": {
          "Verified": {},
          "Code-Review": {}
        }
      }
    ],
    [],
    []
  ]

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.

  • DOWNLOAD_COMMANDS: include the commands field in the FetchInfo for revisions. Only valid when the CURRENT_REVISION or ALL_REVISIONS option is selected.

  • CURRENT_COMMIT: parse and output all header fields from the commit object, including message. Only valid when the CURRENT_REVISION or ALL_REVISIONS option is 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 option is selected.

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

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

  • MESSAGES: include messages associated with the change.

  • CURRENT_ACTIONS: include information on available actions for the change and its current revision. Ignored if the caller is not authenticated.

  • CHANGE_ACTIONS: include information on available change actions for the change. Ignored if the caller is not authenticated.

  • REVIEWED: include the reviewed field if all of the following are true:

  • the change is open

  • the caller is authenticated

  • the caller has commented on the change more recently than the last update from the change owner, i.e. this change would show up in the results of reviewedby:self.

  • CHECK: include potential problems with the change.

  • COMMIT_FOOTERS: include the full commit message with Gerrit-specific commit footers in the RevisionInfo.

  • PUSH_CERTIFICATES: include push certificate information in the RevisionInfo. Ignored if signed push is not enabled on the server.

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

  )]}'
  [
    {
      "id": "gerrit~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,
      "insertions": 16,
      "deletions": 7,
      "_number": 97,
      "owner": {
        "name": "Shawn Pearce"
      },
      "current_revision": "184ebe53805e102605d11f6b143486d15c23a09c",
      "revisions": {
        "184ebe53805e102605d11f6b143486d15c23a09c": {
          "_number": 1,
          "ref": "refs/changes/97/97/1",
          "fetch": {
            "git": {
              "url": "git://localhost/gerrit",
              "ref": "refs/changes/97/97/1",
              "commands": {
                "Checkout": "git fetch git://localhost/gerrit refs/changes/97/97/1 \u0026\u0026 git checkout FETCH_HEAD",
                "Cherry-Pick": "git fetch git://localhost/gerrit refs/changes/97/97/1 \u0026\u0026 git cherry-pick FETCH_HEAD",
                "Format-Patch": "git fetch git://localhost/gerrit refs/changes/97/97/1 \u0026\u0026 git format-patch -1 --stdout FETCH_HEAD",
                "Pull": "git pull git://localhost/gerrit refs/changes/97/97/1"
              }
            },
            "http": {
              "url": "http://myuser@127.0.0.1:8080/gerrit",
              "ref": "refs/changes/97/97/1",
              "commands": {
                "Checkout": "git fetch http://myuser@127.0.0.1:8080/gerrit refs/changes/97/97/1 \u0026\u0026 git checkout FETCH_HEAD",
                "Cherry-Pick": "git fetch http://myuser@127.0.0.1:8080/gerrit refs/changes/97/97/1 \u0026\u0026 git cherry-pick FETCH_HEAD",
                "Format-Patch": "git fetch http://myuser@127.0.0.1:8080/gerrit refs/changes/97/97/1 \u0026\u0026 git format-patch -1 --stdout FETCH_HEAD",
                "Pull": "git pull http://myuser@127.0.0.1:8080/gerrit refs/changes/97/97/1"
              }
            },
            "ssh": {
              "url": "ssh://myuser@*:29418/gerrit",
              "ref": "refs/changes/97/97/1",
              "commands": {
                "Checkout": "git fetch ssh://myuser@*:29418/gerrit refs/changes/97/97/1 \u0026\u0026 git checkout FETCH_HEAD",
                "Cherry-Pick": "git fetch ssh://myuser@*:29418/gerrit refs/changes/97/97/1 \u0026\u0026 git cherry-pick FETCH_HEAD",
                "Format-Patch": "git fetch ssh://myuser@*:29418/gerrit refs/changes/97/97/1 \u0026\u0026 git format-patch -1 --stdout FETCH_HEAD",
                "Pull": "git pull ssh://myuser@*:29418/gerrit 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,
              "size_delta": -412
            },
            "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeDetailCache.java": {
              "lines_inserted": 1,
              "size_delta": 23
            },
            "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeScreen.java": {
              "lines_inserted": 11,
              "lines_deleted": 19,
              "size_delta": -298
            },
            "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeTable.java": {
              "lines_inserted": 23,
              "lines_deleted": 20,
              "size_delta": 132
            },
            "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/StarCache.java": {
              "status": "D",
              "lines_deleted": 139,
              "size_delta": -5512
            },
            "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/StarredChanges.java": {
              "status": "A",
              "lines_inserted": 204,
              "size_delta": 8345
            },
            "gerrit-gwtui/src/main/java/com/google/gerrit/client/ui/Screen.java": {
              "lines_deleted": 9,
              "size_delta": -343
            }
          }
        }
      }
    }
  ]

Get Change

'GET /changes/{change-id}'

Retrieves a change.

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. Fields are described in Query Changes.

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

  )]}'
  {
    "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",
    "mergeable": true,
    "insertions": 34,
    "deletions": 101,
    "_number": 3965,
    "owner": {
      "name": "John Doe"
    }
  }

Get Change Detail

'GET /changes/{change-id}/detail'

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

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. Fields are described in Query Changes.

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

As response a ChangeInfo entity is returned that describes the change. This response will contain all votes for each label and include one combined vote. The combined label vote is calculated in the following order (from highest to lowest): REJECTED > APPROVED > DISLIKED > RECOMMENDED.

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

  )]}'
  {
    "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",
    "mergeable": true,
    "insertions": 126,
    "deletions": 11,
    "_number": 3965,
    "owner": {
      "_account_id": 1000096,
      "name": "John Doe",
      "email": "john.doe@example.com",
      "username": "jdoe"
    },
    "labels": {
      "Verified": {
        "all": [
          {
            "value": 0,
            "_account_id": 1000096,
            "name": "John Doe",
            "email": "john.doe@example.com",
            "username": "jdoe"
          },
          {
            "value": 0,
            "_account_id": 1000097,
            "name": "Jane Roe",
            "email": "jane.roe@example.com",
            "username": "jroe"
          }
        ],
        "values": {
          "-1": "Fails",
          " 0": "No score",
          "+1": "Verified"
        }
      },
      "Code-Review": {
        "disliked": {
          "_account_id": 1000096,
          "name": "John Doe",
          "email": "john.doe@example.com",
          "username": "jdoe"
        },
        "all": [
          {
            "value": -1,
            "_account_id": 1000096,
            "name": "John Doe",
            "email": "john.doe@example.com",
            "username": "jdoe"
          },
          {
            "value": 1,
            "_account_id": 1000097,
            "name": "Jane Roe",
            "email": "jane.roe@example.com",
            "username": "jroe"
          }
        ]
        "values": {
          "-2": "This shall not be merged",
          "-1": "I would prefer this is not merged as is",
          " 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",
        "username": "jdoe"
      },
      {
        "_account_id": 1000097,
        "name": "Jane Roe",
        "email": "jane.roe@example.com",
        "username": "jroe"
      }
    ],
    "messages": [
      {
        "id": "YH-egE",
        "author": {
          "_account_id": 1000096,
          "name": "John Doe",
          "email": "john.doe@example.com",
          "username": "jdoe"
        },
        "updated": "2013-03-23 21:34:02.419000000",
        "message": "Patch Set 1:\n\nThis is the first message.",
        "revision_number": 1
      },
      {
        "id": "WEEdhU",
        "author": {
          "_account_id": 1000097,
          "name": "Jane Roe",
          "email": "jane.roe@example.com",
          "username": "jroe"
        },
        "updated": "2013-03-23 21:36:52.332000000",
        "message": "Patch Set 1:\n\nThis is the second message.\n\nWith a line break.",
        "revision_number": 1
      }
    ]
  }

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.

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

  )]}'
  {
    "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",
    "mergeable": true,
    "insertions": 3,
    "deletions": 310,
    "_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

  )]}'
  {
    "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",
    "mergeable": true,
    "insertions": 2,
    "deletions": 13,
    "_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

Rebase Change

'POST /changes/{change-id}/rebase'

Rebases a change.

Optionally, the parent revision can be changed to another patch set through the RebaseInput entity.

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

  {
    "base" : "1234",
  }

As response a ChangeInfo entity is returned that describes the rebased change. Information about the current patch set is included.

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

  )]}'
  {
    "id": "myProject~master~I3ea943139cb62e86071996f2480e58bf3eeb9dd2",
    "project": "myProject",
    "branch": "master",
    "change_id": "I3ea943139cb62e86071996f2480e58bf3eeb9dd2",
    "subject": "Implement Feature X",
    "status": "NEW",
    "created": "2013-02-01 09:59:32.126000000",
    "updated": "2013-02-21 11:16:36.775000000",
    "mergeable": false,
    "insertions": 33,
    "deletions": 9,
    "_number": 4799,
    "owner": {
      "name": "John Doe"
    },
    "current_revision": "27cc4558b5a3d3387dd11ee2df7a117e7e581822",
    "revisions": {
      "27cc4558b5a3d3387dd11ee2df7a117e7e581822": {
        "_number": 2,
        "ref": "refs/changes/99/4799/2",
        "fetch": {
          "http": {
            "url": "http://gerrit:8080/myProject",
            "ref": "refs/changes/99/4799/2"
          }
        },
        "commit": {
          "parents": [
            {
              "commit": "b4003890dadd406d80222bf1ad8aca09a4876b70",
              "subject": "Implement Feature A"
            }
        ],
        "author": {
          "name": "John Doe",
          "email": "john.doe@example.com",
          "date": "2013-05-07 15:21:27.000000000",
          "tz": 120
        },
        "committer": {
          "name": "Gerrit Code Review",
          "email": "gerrit-server@example.com",
          "date": "2013-05-07 15:35:43.000000000",
          "tz": 120
        },
        "subject": "Implement Feature X",
        "message": "Implement Feature X\n\nAdded feature X."
      }
    }
  }

If the change cannot be rebased, e.g. due to conflicts, 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

  The change could not be rebased due to a path conflict during merge.

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

  )]}'
  {
    "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",
    "mergeable": true,
    "insertions": 6,
    "deletions": 4,
    "_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

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

Changes submitted together

'GET /changes/{change-id}/submitted_together'

Returns a list of all changes which are submitted when {submit} is called for this change, including the current change itself.

An empty list is returned if this change will be submitted by itself (no other changes).

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

The return value is a list of changes in the same format as in \{listing changes\} with the options {LABELS}, {DETAILED_LABELS}, {CURRENT_REVISION}, {CURRENT_COMMIT} set. The list consists of:

  • The given change.

  • If change.submitWholeTopic is enabled, include all open changes with the same topic.

  • For each change whose submit type is not CHERRY_PICK, include unmerged ancestors targeting the same branch.

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

)]}'
[
  {
    "id": "gerrit~master~I1ffe09a505e25f15ce1521bcfb222e51e62c2a14",
    "project": "gerrit",
    "branch": "master",
    "hashtags": [],
    "change_id": "I1ffe09a505e25f15ce1521bcfb222e51e62c2a14",
    "subject": "ChangeMergeQueue: Rewrite such that it works on set of changes",
    "status": "NEW",
    "created": "2015-05-01 15:39:57.979000000",
    "updated": "2015-05-20 19:25:21.592000000",
    "mergeable": true,
    "insertions": 303,
    "deletions": 210,
    "_number": 1779,
    "owner": {
      "_account_id": 1000000
    },
    "labels": {
      "Code-Review": {
        "approved": {
          "_account_id": 1000000
        },
        "all": [
          {
            "value": 2,
            "date": "2015-05-20 19:25:21.592000000",
            "_account_id": 1000000
          }
        ],
        "values": {
          "-2": "This shall not be merged",
          "-1": "I would prefer this is not merged as is",
          " 0": "No score",
          "+1": "Looks good to me, but someone else must approve",
          "+2": "Looks good to me, approved"
        },
        "default_value": 0
      },
      "Verified": {
        "approved": {
          "_account_id": 1000000
        },
        "all": [
          {
            "value": 1,
            "date": "2015-05-20 19:25:21.592000000",
            "_account_id": 1000000
          }
        ],
        "values": {
          "-1": "Fails",
          " 0": "No score",
          "+1": "Verified"
        },
        "default_value": 0
      }
    },
    "permitted_labels": {
      "Code-Review": [
        "-2",
        "-1",
        " 0",
        "+1",
        "+2"
      ],
      "Verified": [
        "-1",
        " 0",
        "+1"
      ]
    },
    "removable_reviewers": [
      {
        "_account_id": 1000000
      }
    ],
    "current_revision": "9adb9f4c7b40eeee0646e235de818d09164d7379",
    "revisions": {
      "9adb9f4c7b40eeee0646e235de818d09164d7379": {
        "_number": 1,
        "created": "2015-05-01 15:39:57.979000000",
        "uploader": {
          "_account_id": 1000000
        },
        "ref": "refs/changes/79/1779/1",
        "fetch": {},
        "commit": {
          "parents": [
            {
              "commit": "2d3176497a2747faed075f163707e57d9f961a1c",
              "subject": "Merge changes from topic \u0027submodule-subscription-tests-and-fixes-3\u0027"
            }
          ],
          "author": {
            "name": "Stefan Beller",
            "email": "sbeller@google.com",
            "date": "2015-04-29 21:36:52.000000000",
            "tz": -420
          },
          "committer": {
            "name": "Stefan Beller",
            "email": "sbeller@google.com",
            "date": "2015-05-01 00:11:16.000000000",
            "tz": -420
          },
          "subject": "ChangeMergeQueue: Rewrite such that it works on set of changes",
          "message": "ChangeMergeQueue: Rewrite such that it works on set of changes\n\nChangeMergeQueue used to work on branches rather than sets of changes.\nThis change is a first step to merge sets of changes (e.g. grouped by a\ntopic and `changes.submitWholeTopic` enabled) in an atomic fashion.\nThis change doesn\u0027t aim to implement these changes, but only as a step\ntowards it.\n\nMergeOp keeps its functionality and behavior as is. A new class\nMergeOpMapper is introduced which will map the set of changes to\nthe set of branches. Additionally the MergeOpMapper is also\nresponsible for the threading done right now, which was part of\nthe ChangeMergeQueue before.\n\nChange-Id: I1ffe09a505e25f15ce1521bcfb222e51e62c2a14\n"
        }
      }
    }
  },
  {
    "id": "gerrit~master~I7fe807e63792b3d26776fd1422e5e790a5697e22",
    "project": "gerrit",
    "branch": "master",
    "hashtags": [],
    "change_id": "I7fe807e63792b3d26776fd1422e5e790a5697e22",
    "subject": "AbstractSubmoduleSubscription: Split up createSubscription",
    "status": "NEW",
    "created": "2015-05-01 15:39:57.979000000",
    "updated": "2015-05-20 19:25:21.546000000",
    "mergeable": true,
    "insertions": 15,
    "deletions": 6,
    "_number": 1780,
    "owner": {
      "_account_id": 1000000
    },
    "labels": {
      "Code-Review": {
        "approved": {
          "_account_id": 1000000
        },
        "all": [
          {
            "value": 2,
            "date": "2015-05-20 19:25:21.546000000",
            "_account_id": 1000000
          }
        ],
        "values": {
          "-2": "This shall not be merged",
          "-1": "I would prefer this is not merged as is",
          " 0": "No score",
          "+1": "Looks good to me, but someone else must approve",
          "+2": "Looks good to me, approved"
        },
        "default_value": 0
      },
      "Verified": {
        "approved": {
          "_account_id": 1000000
        },
        "all": [
          {
            "value": 1,
            "date": "2015-05-20 19:25:21.546000000",
            "_account_id": 1000000
          }
        ],
        "values": {
          "-1": "Fails",
          " 0": "No score",
          "+1": "Verified"
        },
        "default_value": 0
      }
    },
    "permitted_labels": {
      "Code-Review": [
        "-2",
        "-1",
        " 0",
        "+1",
        "+2"
      ],
      "Verified": [
        "-1",
        " 0",
        "+1"
      ]
    },
    "removable_reviewers": [
      {
        "_account_id": 1000000
      }
    ],
    "current_revision": "1bd7c12a38854a2c6de426feec28800623f492c4",
    "revisions": {
      "1bd7c12a38854a2c6de426feec28800623f492c4": {
        "_number": 1,
        "created": "2015-05-01 15:39:57.979000000",
        "uploader": {
          "_account_id": 1000000
        },
        "ref": "refs/changes/80/1780/1",
        "fetch": {},
        "commit": {
          "parents": [
            {
              "commit": "9adb9f4c7b40eeee0646e235de818d09164d7379",
              "subject": "ChangeMergeQueue: Rewrite such that it works on set of changes"
            }
          ],
          "author": {
            "name": "Stefan Beller",
            "email": "sbeller@google.com",
            "date": "2015-04-25 00:11:59.000000000",
            "tz": -420
          },
          "committer": {
            "name": "Stefan Beller",
            "email": "sbeller@google.com",
            "date": "2015-05-01 00:11:16.000000000",
            "tz": -420
          },
          "subject": "AbstractSubmoduleSubscription: Split up createSubscription",
          "message": "AbstractSubmoduleSubscription: Split up createSubscription\n\nLater we want to have subscriptions to more submodules, so we need to\nfind a way to add more submodule entries into the file. By splitting up\nthe createSubscription() method, that is very easy by using the\naddSubmoduleSubscription method multiple times.\n\nChange-Id: I7fe807e63792b3d26776fd1422e5e790a5697e22\n"
        }
      }
    }
  }
]

Publish Draft Change

'POST /changes/{change-id}/publish'

Publishes a draft change.

Request
  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/publish HTTP/1.0
  Content-Type: application/json; charset=UTF-8
Response
  HTTP/1.1 204 No Content

Delete Draft Change

'DELETE /changes/{change-id}'

Deletes a draft change.

Request
  DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940 HTTP/1.0
  Content-Type: application/json; charset=UTF-8
Response
  HTTP/1.1 204 No Content

Get Included In

'GET /changes/{change-id}/in'

Retrieves the branches and tags in which a change is included. As result an IncludedInInfo entity is returned.

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

  )]}'
  {
    "branches": [
      "master"
    ],
    "tags": []
  }

Index Change

'POST /changes/{change-id}/index'

Adds or updates the change in the secondary index.

Request
  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/index HTTP/1.0
Response
  HTTP/1.1 204 No Content

List Change Comments

'GET /changes/{change-id}/comments'

Lists the published comments of all revisions of the change.

Returns a map of file paths to lists of CommentInfo entries. The entries in the map are sorted by file path, and the comments for each path are sorted by patch set number. Each comment has the patch_set and author fields set.

Request
  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/comments 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": [
      {
        "patch_set": 1,
        "id": "TvcXrmjM",
        "line": 23,
        "message": "[nit] trailing whitespace",
        "updated": "2013-02-26 15:40:43.986000000"
        "author": {
          "_account_id": 1000096,
          "name": "John Doe",
          "email": "john.doe@example.com"
        }
      },
      {
        "patch_set": 2,
        "id": "TveXwFiA",
        "line": 49,
        "in_reply_to": "TfYX-Iuo",
        "message": "Done",
        "updated": "2013-02-26 15:40:45.328000000"
        "author": {
          "_account_id": 1000097,
          "name": "Jane Roe",
          "email": "jane.roe@example.com"
        }
      }
    ]
  }

List Change Drafts

'GET /changes/{change-id}/drafts'

Lists the draft comments of all revisions of the change that belong to the calling user.

Returns a map of file paths to lists of CommentInfo entries. The entries in the map are sorted by file path, and the comments for each path are sorted by patch set number. Each comment has the patch_set field set, and no author.

Request
  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/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": [
      {
        "patch_set": 1,
        "id": "TvcXrmjM",
        "line": 23,
        "message": "[nit] trailing whitespace",
        "updated": "2013-02-26 15:40:43.986000000"
      },
      {
        "patch_set": 2,
        "id": "TveXwFiA",
        "line": 49,
        "in_reply_to": "TfYX-Iuo",
        "message": "Done",
        "updated": "2013-02-26 15:40:45.328000000"
      }
    ]
  }

Check change

'GET /changes/{change-id}/check'

Performs consistency checks on the change, and returns a ChangeInfo entity with the problems field set to a list of ProblemInfo entities.

Depending on the type of problem, some fields not marked optional may be missing from the result. At least id, project, branch, and _number will be present.

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

  )]}'
  {
    "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",
    "mergeable": true,
    "insertions": 34,
    "deletions": 101,
    "_number": 3965,
    "owner": {
      "name": "John Doe"
    },
    "problems": [
      {
        "message": "Current patch set 1 not found"
      }
    ]
  }

Fix change

'POST /changes/{change-id}/check'

Performs consistency checks on the change as with GET /check, and additionally fixes any problems that can be fixed automatically. The returned field values reflect any fixes.

Some fixes have options controlling their behavior, which can be set in the FixInput entity body.

Only the change owner, a project owner, or an administrator may fix changes.

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

  )]}'
  {
    "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",
    "mergeable": true,
    "insertions": 34,
    "deletions": 101,
    "_number": 3965,
    "owner": {
      "name": "John Doe"
    },
    "problems": [
      {
        "message": "Current patch set 2 not found"
      },
      {
        "message": "Patch set 1 (1eee2c9d8f352483781e772f35dc586a69ff5646) is merged into destination ref master (1eee2c9d8f352483781e772f35dc586a69ff5646), but change status is NEW",
        "status": FIXED,
        "outcome": "Marked change as merged"
      }
    ]
  }

Change Edit Endpoints

Get Change Edit Details

'GET /changes/{change-id}/edit

Retrieves a change edit details.

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

As response an EditInfo entity is returned that describes the change edit, or “204 No Content” when change edit doesn’t exist for this change. Change edits are stored on special branches and there can be max one edit per user per change. Edits aren’t tracked in the database. When request parameter list is provided the response also includes the file list. When base request parameter is provided the file list is computed against this base revision. When request parameter download-commands is provided fetch info map is also included.

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

  )]}'
  {
    "commit":{
      "parents":[
        {
          "commit":"1eee2c9d8f352483781e772f35dc586a69ff5646",
        }
      ],
      "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 ..."
    },
  }

Change file content in Change Edit

'PUT /changes/{change-id}/edit/path%2fto%2ffile

Put content of a file to a change edit.

Request
  PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit/foo HTTP/1.0

When change edit doesn’t exist for this change yet it is created. When file content isn’t provided, it is wiped out for that file. As response “204 No Content” is returned.

Response
  HTTP/1.1 204 No Content

Restore file content or rename files in Change Edit

'POST /changes/{change-id}/edit

Creates empty change edit, restores file content or renames files in change edit. The request body needs to include a ChangeEditInput entity when a file within change edit should be restored or old and new file names to rename a file.

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

  {
    "restore_path": "foo"
  }

or for rename:

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

  {
    "old_path": "foo",
    "new_path": "bar"
  }

When change edit doesn’t exist for this change yet it is created. When path and restore flag are provided in request body, this file is restored. When old and new file names are provided, the file is renamed. As response “204 No Content” is returned.

Response
  HTTP/1.1 204 No Content

Change commit message in Change Edit

'PUT /changes/{change-id}/edit:message

Modify commit message. The request body needs to include a ChangeEditMessageInput entity.

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

  {
    "message": "New commit message\n\nChange-Id: I10394472cbd17dd12454f229e4f6de00b143a444"
  }

If a change edit doesn’t exist for this change yet, it is created. As response “204 No Content” is returned.

Response
  HTTP/1.1 204 No Content

Delete file in Change Edit

'DELETE /changes/{change-id}/edit/path%2fto%2ffile'

Deletes a file from a change edit. This deletes the file from the repository completely. This is not the same as reverting or restoring a file to its previous contents.

Request
  DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit/foo HTTP/1.0

When change edit doesn’t exist for this change yet it is created.

Response
  HTTP/1.1 204 No Content

Retrieve file content from Change Edit

'GET /changes/{change-id}/edit/path%2fto%2ffile

Retrieves content of a file from a change edit.

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

The content of the file is returned as text encoded inside base64. The Content-Type header will always be text/plain reflecting the outer base64 encoding. A Gerrit-specific X-FYI-Content-Type header can be examined to find the server detected content type of the file.

When the specified file was deleted in the change edit “204 No Content” is returned.

If only the content type is required, callers should use HEAD to avoid downloading the encoded file contents.

Response
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: text/plain; charset=ISO-8859-1
  X-FYI-Content-Encoding: base64
  X-FYI-Content-Type: text/xml

  RnJvbSA3ZGFkY2MxNTNmZGVhMTdhYTg0ZmYzMmE2ZTI0NWRiYjY...

Alternatively, if the only value of the Accept request header is application/json the content is returned as JSON string and X-FYI-Content-Encoding is set to json.

Retrieve meta data of a file from Change Edit

'GET /changes/{change-id}/edit/path%2fto%2ffile/meta

Retrieves meta data of a file from a change edit. Currently only web links are returned.

Request
  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit/foo/meta HTTP/1.0

This REST endpoint retrieves additional information for a file in a change edit. As result an EditFileInfo entity is returned.

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

  )]}'
  {
  "web_links":[
    {
      "show_on_side_by_side_diff_view": true,
      "name": "side-by-side preview diff",
      "image_url": "plugins/xdocs/static/sideBySideDiffPreview.png",
      "url": "#/x/xdocs/c/42/1..0/README.md",
      "target": "_self"
    },
    {
      "show_on_unified_diff_view": true,
      "name": "unified preview diff",
      "image_url": "plugins/xdocs/static/unifiedDiffPreview.png",
      "url": "#/x/xdocs/c/42/1..0/README.md,unified",
      "target": "_self"
    }
  ]}

Retrieve commit message from Change Edit or current patch set of the change

'GET /changes/{change-id}/edit:message

Retrieves commit message from change edit.

Request
  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit:message HTTP/1.0

The commit message is returned as base64 encoded string.

Response
  HTTP/1.1 200 OK

  VGhpcyBpcyBhIGNvbW1pdCBtZXNzYWdlCgpDaGFuZ2UtSWQ6IElhYzhmZGM1MGRlZjFiYWUzYjAz
M2JhNjcxZTk0OTBmNzUxNDU5ZGUzCg==

Alternatively, if the only value of the Accept request header is application/json the commit message is returned as JSON string:

Response
  HTTP/1.1 200 OK

)]}'
"Subject of the commit message\n\nThis is the body of the commit message.\n\nChange-Id: Iaf1ba916bf843c175673d675bf7f52862f452db9\n"

Publish Change Edit

'POST /changes/{change-id}/edit:publish

Promotes change edit to a regular patch set.

Request
  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit:publish HTTP/1.0

As response “204 No Content” is returned.

Response
  HTTP/1.1 204 No Content

Rebase Change Edit

'POST /changes/{change-id}/edit:rebase

Rebases change edit on top of latest patch set.

Request
  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit:rebase HTTP/1.0

When change was rebased on top of latest patch set, response “204 No Content” is returned. When change edit is already based on top of the latest patch set, the response “409 Conflict” is returned.

Response
  HTTP/1.1 204 No Content

Delete Change Edit

'DELETE /changes/{change-id}/edit'

Deletes change edit.

Request
  DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit HTTP/1.0

As response “204 No Content” is returned.

Response
  HTTP/1.1 204 No Content

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

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

Suggest Reviewers

'GET /changes/{change-id}/suggest_reviewers?q=J&n=5'

Suggest the reviewers for a given query q and result limit n. If result limit is not passed, then the default 10 is used.

As result a list of SuggestedReviewerInfo entries is returned.

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

  )]}'
  [
    {
      "account": {
        "_account_id": 1000097,
        "name": "Jane Roe",
        "email": "jane.roe@example.com"
      }
    },
    {
      "group": {
        "id": "4fd581c0657268f2bdcc26699fbf9ddb76e3a279",
        "name": "Joiner"
      }
    }
  ]

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

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

'GET /changes/{change-id}/revisions/{revision-id}/commit'

Retrieves a parsed commit of a revision.

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

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

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

  )]}'
  {
    "commit": "674ac754f91e64a0efb8087e59a176484bd534d1",
    "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 ..."
  }

Adding query parameter links (for example /changes/…​/commit?links) returns a CommitInfo with the additional field web_links.

Get Revision Actions

'GET /changes/{change-id}/revisions/{revision-id}/actions'

Retrieves revision actions of the revision of a change.

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

  )]}'

{
  "submit": {
    "method": "POST",
    "label": "Submit",
    "title": "Submit patch set 1 into master",
    "enabled": true
  },
  "cherrypick": {
    "method": "POST",
    "label": "Cherry Pick",
    "title": "Cherry pick change to a different branch",
    "enabled": true
  }
}

The response is a flat map of possible revision actions mapped to their ActionInfo.

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

  )]}'
  {
    "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",
    "mergeable": true,
    "insertions": 34,
    "deletions": 45,
    "_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": "This shall not be merged",
          "-1": "I would prefer this is not merged as is",
          " 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,
      "ref": "refs/changes/65/3965/2",
      "fetch": {
        "http": {
          "url": "http://gerrit/myProject",
          "ref": "refs/changes/65/3965/2"
        }
      }
    }
  }

'GET /changes/{change-id}/revisions/{revision-id}/related'

Retrieves related changes of a revision. Related changes are changes that either depend on, or are dependencies of the revision.

Request
  GET /changes/gerrit~master~I5e4fc08ce34d33c090c9e0bf320de1b17309f774/revisions/b1cb4caa6be46d12b94c25aa68aebabcbb3f53fe/related HTTP/1.0

As result a RelatedChangesInfo entity is returned describing the related changes.

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

  )]}'
  {
    "changes": [
      {
        "change_id": "Ic62ae3103fca2214904dbf2faf4c861b5f0ae9b5",
        "commit": {
          "commit": "78847477532e386f5a2185a4e8c90b2509e354e3",
          "parents": [
            {
              "commit": "bb499510bbcdbc9164d96b0dbabb4aa45f59a87e"
            }
          ],
          "author": {
            "name": "David Ostrovsky",
            "email": "david@ostrovsky.org",
            "date": "2014-07-12 15:04:24.000000000",
            "tz": 120
          },
          "subject": "Remove Solr"
        },
        "_change_number": 58478,
        "_revision_number": 2,
        "_current_revision_number": 2
        "status": "NEW"
      },
      {
        "change_id": "I5e4fc08ce34d33c090c9e0bf320de1b17309f774",
        "commit": {
          "commit": "b1cb4caa6be46d12b94c25aa68aebabcbb3f53fe",
          "parents": [
            {
              "commit": "d898f12a9b7a92eb37e7a80636195a1b06417aad"
            }
          ],
          "author": {
            "name": "David Pursehouse",
            "email": "david.pursehouse@sonymobile.com",
            "date": "2014-06-24 02:01:28.000000000",
            "tz": 540
          },
          "subject": "Add support for secondary index with Elasticsearch"
        },
        "_change_number": 58081,
        "_revision_number": 10,
        "_current_revision_number": 10
        "status": "NEW"
      }
    ]
  }

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"
        },
        {
          "range": {
            "start_line": 50,
            "start_character": 0,
            "end_line": 55,
            "end_character": 20
          },
          "message": "Incorrect indentation"
        }
      ]
    }
  }

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

A review cannot be set on a change edit. Trying to post a review for a change edit fails with 409 Conflict.

Rebase Revision

'POST /changes/{change-id}/revisions/{revision-id}/rebase'

Rebases a revision.

Optionally, the parent revision can be changed to another patch set through the RebaseInput entity.

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

  {
    "base" : "1234",
  }

As response a ChangeInfo entity is returned that describes the rebased change. Information about the current patch set is included.

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

  )]}'
  {
    "id": "myProject~master~I3ea943139cb62e86071996f2480e58bf3eeb9dd2",
    "project": "myProject",
    "branch": "master",
    "change_id": "I3ea943139cb62e86071996f2480e58bf3eeb9dd2",
    "subject": "Implement Feature X",
    "status": "NEW",
    "created": "2013-02-01 09:59:32.126000000",
    "updated": "2013-02-21 11:16:36.775000000",
    "mergeable": false,
    "insertions": 21,
    "deletions": 21,
    "_number": 4799,
    "owner": {
      "name": "John Doe"
    },
    "current_revision": "27cc4558b5a3d3387dd11ee2df7a117e7e581822",
    "revisions": {
      "27cc4558b5a3d3387dd11ee2df7a117e7e581822": {
        "_number": 2,
        "ref": "refs/changes/99/4799/2",
        "fetch": {
          "http": {
            "url": "http://gerrit:8080/myProject",
            "ref": "refs/changes/99/4799/2"
          }
        },
        "commit": {
          "parents": [
            {
              "commit": "b4003890dadd406d80222bf1ad8aca09a4876b70",
              "subject": "Implement Feature A"
            }
        ],
        "author": {
          "name": "John Doe",
          "email": "john.doe@example.com",
          "date": "2013-05-07 15:21:27.000000000",
          "tz": 120
        },
        "committer": {
          "name": "Gerrit Code Review",
          "email": "gerrit-server@example.com",
          "date": "2013-05-07 15:35:43.000000000",
          "tz": 120
        },
        "subject": "Implement Feature X",
        "message": "Implement Feature X\n\nAdded feature X."
      }
    }
  }

If the revision cannot be rebased, e.g. due to conflicts, 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

  The change could not be rebased due to a path conflict during merge.

Submit Revision

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

Submits a revision.

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

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"

Publish Draft Revision

'POST /changes/{change-id}/revisions/{revision-id}/publish'

Publishes a draft revision.

Request
  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/publish HTTP/1.0
  Content-Type: application/json; charset=UTF-8
Response
  HTTP/1.1 204 No Content

Delete Draft Revision

'DELETE /changes/{change-id}/revisions/{revision-id}'

Deletes a draft revision.

Request
  DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1 HTTP/1.0
  Content-Type: application/json; charset=UTF-8
Response
  HTTP/1.1 204 No Content

Get Patch

'GET /changes/{change-id}/revisions/{revision-id}/patch'

Gets the formatted patch for one revision.

Request
  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/patch HTTP/1.0

The formatted patch is returned as text encoded inside base64:

Response
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: text/plain; charset=ISO-8859-1
  X-FYI-Content-Encoding: base64
  X-FYI-Content-Type: application/mbox

  RnJvbSA3ZGFkY2MxNTNmZGVhMTdhYTg0ZmYzMmE2ZTI0NWRiYjY...

Adding query parameter zip (for example /changes/…​/patch?zip) returns the patch as a single file inside of a ZIP archive. Clients can expand the ZIP to obtain the plain text patch, avoiding the need for a base64 decoding step. This option implies download.

Query parameter download (e.g. /changes/…​/patch?download) will suggest the browser save the patch as commitsha1.diff.base64, for later processing by command line tools.

Get Mergeable

'GET /changes/{change-id}/revisions/{revision-id}/mergeable'

Gets the method the server will use to submit (merge) the change and an indicator if the change is currently mergeable.

Request
  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/mergeable HTTP/1.0

As response a MergeableInfo entity is returned.

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

  )]}'
  {
    submit_type: "MERGE_IF_NECESSARY",
    mergeable: true,
  }

If the other-branches parameter is specified, the mergeability will also be checked for all other branches.

Request
  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/current/mergeable?other-branches HTTP/1.0

The response will then contain a list of all other branches where this changes could merge cleanly.

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

  )]}'
  {
    submit_type: "MERGE_IF_NECESSARY",
    mergeable: true,
    mergeable_into: [
        "refs/heads/stable-2.7",
        "refs/heads/stable-2.8",
    ]
  }

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_rule?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": {}
      }
    }
  ]

When testing with the curl command line client the --data-binary @rules.pl flag should be used to ensure all LFs are included in the Prolog code:

  curl -X POST \
    -H 'Content-Type: text/plain; charset=UTF-8' \
    --data-binary @rules.pl \
    http://.../test.submit_rule

List Revision Drafts

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

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

Returns a map of file paths to lists 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": [
      {
        "id": "TvcXrmjM",
        "line": 23,
        "message": "[nit] trailing whitespace",
        "updated": "2013-02-26 15:40:43.986000000"
      },
      {
        "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

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

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

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

List Revision Comments

'GET /changes/{change-id}/revisions/{revision-id}/comments/'

Lists the published comments of a revision.

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 and only include file (or inline) comments. Use the Get Change Detail endpoint to retrieve the general change message (or comment).

Request
  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/comments/ 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": [
      {
        "id": "TvcXrmjM",
        "line": 23,
        "message": "[nit] trailing whitespace",
        "updated": "2013-02-26 15:40:43.986000000",
        "author": {
          "_account_id": 1000096,
          "name": "John Doe",
          "email": "john.doe@example.com"
        }
      },
      {
        "id": "TveXwFiA",
        "line": 49,
        "in_reply_to": "TfYX-Iuo",
        "message": "Done",
        "updated": "2013-02-26 15:40:45.328000000",
        "author": {
          "_account_id": 1000097,
          "name": "Jane Roe",
          "email": "jane.roe@example.com"
        }
      }
    ]
  }

Get Comment

'GET /changes/{change-id}/revisions/{revision-id}/comments/{comment-id}'

Retrieves a published comment of a revision.

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

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

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

  )]}'
  {
    "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",
    "author": {
      "_account_id": 1000096,
      "name": "John Doe",
      "email": "john.doe@example.com"
    }
  }

List Files

'GET /changes/{change-id}/revisions/{revision-id}/files/'

Lists the files that were modified, added or deleted in a revision.

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

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

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

  )]}'
  {
    "/COMMIT_MSG": {
      "status": "A",
      "lines_inserted": 7,
      "size_delta": 551
    },
    "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": {
      "lines_inserted": 5,
      "lines_deleted": 3,
      "size_delta": 98
    }
  }

The request parameter reviewed changes the response to return a list of the paths the caller has marked as reviewed. Clients that also need the FileInfo should make two requests.

The request parameter q changes the response to return a list of all files (modified or unmodified) that contain that substring in the path name. This is useful to implement suggestion services finding a file by partial name.

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

  )]}'
  [
    "/COMMIT_MSG",
    "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
  ]

Get Content

'GET /changes/{change-id}/revisions/{revision-id}/files/{file-id}/content'

Gets the content of a file from a certain revision.

Request
  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/content HTTP/1.0

The content is returned as base64 encoded string. The HTTP response Content-Type is always text/plain, reflecting the base64 wrapping. A Gerrit-specific X-FYI-Content-Type header is returned describing the server detected content type of the file.

If only the content type is required, callers should use HEAD to avoid downloading the encoded file contents.

Response
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: text/plain; charset=ISO-8859-1
  X-FYI-Content-Encoding: base64
  X-FYI-Content-Type: text/xml

  Ly8gQ29weXJpZ2h0IChDKSAyMDEwIFRoZSBBbmRyb2lkIE9wZW4gU291cmNlIFByb2plY...

Alternatively, if the only value of the Accept request header is application/json the content is returned as JSON string and X-FYI-Content-Encoding is set to json.

Download Content

'GET /changes/{change-id}/revisions/{revision-id}/files/{file-id}/download'

Downloads the content of a file from a certain revision, in a safe format that poses no risk for inadvertent execution of untrusted code.

If the content type is defined as safe, the binary file content is returned verbatim. If the content type is not safe, the file is stored inside a ZIP file, containing a single entry with a random, unpredictable name having the same base and suffix as the true filename. The ZIP file is returned in verbatim binary form.

See Gerrit config documentation for information about safe file type configuration.

The HTTP resource Content-Type is dependent on the file type: the applicable type for safe files, or "application/zip" for unsafe files.

The optional, integer-valued parent parameter can be specified to request the named file from a parent commit of the specified revision. The value is the 1-based index of the parent’s position in the commit object. If the parameter is omitted or the value non-positive, the patch set is referenced.

Filenames are decorated with a suffix of _new for the current patch, _old for the only parent, or _oldN for the Nth parent of many.

Request
  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/website%2Freleases%2Flogo.png/safe_content HTTP/1.0
Response
  HTTP/1.1 200 OK
  Content-Disposition: attachment; filename="logo.png"
  Content-Type: image/png

  `[binary data for logo.png]`
Request
  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/safe_content?suffix=new HTTP/1.0
Response
  HTTP/1.1 200 OK
  Content-Disposition: Content-Disposition:attachment; filename="RefControl_new-931cdb73ae9d97eb500a3533455b055d90b99944.java.zip"
  Content-Type:application/zip

  `[binary ZIP archive containing a single file, "RefControl_new-cb218df1337df48a0e7ab30a49a8067ac7321881.java"]`

Get Diff

'GET /changes/{change-id}/revisions/{revision-id}/files/{file-id}/diff'

Gets the diff of a file from a certain revision.

Request
  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/diff HTTP/1.0

As response a DiffInfo entity is returned that describes the diff.

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

  )]
  {
    "meta_a": {
      "name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
      "content_type": "text/x-java-source",
      "lines": 372
    },
    "meta_b": {
      "name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
      "content_type": "text/x-java-source",
      "lines": 578
    },
    "change_type": "MODIFIED",
    "diff_header": [
      "diff --git a/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java b/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
      "index 59b7670..9faf81c 100644",
      "--- a/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
      "+++ b/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java"
    ],
    "content": [
      {
        "ab": [
          "// Copyright (C) 2010 The Android Open Source Project",
          "//",
          "// Licensed under the Apache License, Version 2.0 (the \"License\");",
          "// you may not use this file except in compliance with the License.",
          "// You may obtain a copy of the License at",
          "//",
          "// http://www.apache.org/licenses/LICENSE-2.0",
          "//",
          "// Unless required by applicable law or agreed to in writing, software",
          "// distributed under the License is distributed on an \"AS IS\" BASIS,",
          "// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.",
          "// See the License for the specific language governing permissions and",
          "// limitations under the License."
        ]
      },
      {
        "b": [
          "//",
          "// Add some more lines in the header."
        ]
      },
      {
        "ab": [
          "",
          "package com.google.gerrit.server.project;",
          "",
          "import com.google.common.collect.Maps;",
          ...
        ]
      }
      ...
    ]
  }

If the intraline parameter is specified, intraline differences are included in the diff.

Request
  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/b6b9c10649b9041884046119ab794374470a1b45/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/diff?intraline HTTP/1.0
Response
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json; charset=UTF-8

  )]
  {
    "meta_a": {
      "name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
      "content_type": "text/x-java-source",
      "lines": 372
    },
    "meta_b": {
      "name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
      "content_type": "text/x-java-source",
      "lines": 578
    },
    "change_type": "MODIFIED",
    "diff_header": [
      "diff --git a/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java b/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
      "index 59b7670..9faf81c 100644",
      "--- a/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
      "+++ b/gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java"
    ],
    "content": [
      ...
      {
        "a": [
          "/** Manages access control for Git references (aka branches, tags). */"
        ],
        "b": [
          "/** Manages access control for the Git references (aka branches, tags). */"
        ],
        "edit_a": [],
        "edit_b": [
          [
            31,
            4
          ]
        ]
      }
      ]
    }

The base parameter can be specified to control the base patch set from which the diff should be generated.

Request
  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/b6b9c10649b9041884046119ab794374470a1b45/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/diff?base=2 HTTP/1.0
Response
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json; charset=UTF-8

  )]
  {
    "meta_a": {
      "name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
      "content_type": "text/x-java-source",
      "lines": 578
    },
    "meta_b": {
      "name": "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java",
      "content_type": "text/x-java-source",
      "lines": 578
    },
    "change_type": "MODIFIED",
    "content": [
      {
        "skip": 578
      }
    ]
  }

The ignore-whitespace parameter can be specified to control how whitespace differences are reported in the result. Valid values are NONE, TRAILING, CHANGED or ALL.

The context parameter can be specified to control the number of lines of surrounding context in the diff. Valid values are ALL or number of lines.

Set Reviewed

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

Marks a file 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 file was already marked as reviewed by the calling user the response is “200 OK”.

Delete Reviewed

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

Deletes the reviewed flag of the calling user from a file 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

Cherry Pick Revision

'POST /changes/{change-id}/revisions/{revision-id}/cherrypick'

Cherry picks a revision to a destination branch.

The commit message and destination branch must be provided in the request body inside a CherryPickInput entity.

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

  {
    "message" : "Implementing Feature X",
    "destination" : "release-branch"
  }

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

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

  )]}'
  {
    "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9941",
    "project": "myProject",
    "branch": "release-branch",
    "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9941",
    "subject": "Implementing Feature X",
    "status": "NEW",
    "created": "2013-02-01 09:59:32.126000000",
    "updated": "2013-02-21 11:16:36.775000000",
    "mergeable": true,
    "insertions": 12,
    "deletions": 11,
    "_number": 3965,
    "owner": {
      "name": "John Doe"
    }
  }

IDs

{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")

{comment-id}

UUID of a published comment.

{draft-id}

UUID of a draft comment.

{file-id}

The path of the file.

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

ActionInfo

The ActionInfo entity describes a REST API call the client can make to manipulate a resource. These are frequently implemented by plugins and may be discovered at runtime.

Field Name Description

method

optional

HTTP method to use with the action. Most actions use POST, PUT or DELETE to cause state changes.

label

optional

Short title to display to a user describing the action. In the Gerrit web interface the label is used as the text on the button presented in the UI.

title

optional

Longer text to display describing the action. In a web UI this should be the title attribute of the element, displaying when the user hovers the mouse.

enabled

optional

If true the action is permitted at this time and the caller is likely allowed to execute it. This may change if state is updated at the server or permissions are modified. Not present if false.

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.

date

optional

The time and date describing when the approval was made.

ChangeEditInput

The ChangeEditInput entity contains information for restoring a path within change edit.

Field Name Description

restore_path

optional

Path to file to restore.

old_path

optional

Old path to file to rename.

new_path

optional

New path to file to rename.

ChangeEditMessageInput

The ChangeEditMessageInput entity contains information for changing the commit message within a change edit.

Field Name Description

message

New commit message.

ChangeInfo

The ChangeInfo entity contains information about a change.

Field Name Description

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, 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. Only set if reviewed is requested.

mergeable

optional

Whether the change is mergeable.
Not set for merged changes, or if the change has not yet been tested.

insertions

Number of inserted lines.

deletions

Number of deleted lines.

_number

The legacy numeric ID of the change.

owner

The owner of the change as an AccountInfo entity.

actions

optional

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

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.

messages

optional

Messages associated with the change as a list of ChangeMessageInfo entities.
Only set if messages 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 the current revision is requested (in which case it will only contain a key for the current revision) or 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 the last change that is returned.

problems

optional

A list of ProblemInfo entities describing potential problems with this change. Only set if CHECK is set.

base_change

optional

A {change-id} that identifies the base change for a create change operation. Only used for the CreateChange endpoint.

ChangeMessageInfo

The ChangeMessageInfo entity contains information about a message attached to a change.

Field Name Description

id

The ID of the message.

author

optional

Author of the message as an AccountInfo entity.
Unset if written by the Gerrit system.

date

The timestamp this message was posted.

message

The text left by the user.

_revision_number

optional

Which patchset (if any) generated this message.

CherryPickInput

The CherryPickInput entity contains information for cherry-picking a change to a new branch.

Field Name Description

message

Commit message for the cherry-picked change

destination

Destination branch

CommentInfo

The CommentInfo entity contains information about an inline comment.

Field Name Description

patch_set

optional

The patch set number for the comment; only set in contexts where
comments may be returned for multiple patch sets.

id

The URL encoded UUID of the 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 range is set, this equals the end line of the range.
If neither line nor range is set, it’s a file comment.

range

optional

The range of the comment as a CommentRange entity.

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.

author

optional

The author of the message as an AccountInfo entity.
Unset for draft comments, assumed to be the calling user.

CommentInput

The CommentInput entity contains information for creating an inline comment.

Field Name Description

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 neither line nor range is set, a file comment is added.
If range is set, this value is ignored in favor of the end_line of the range.

range

optional

The range of the comment as a CommentRange entity.

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.

CommentRange

The CommentRange entity describes the range of an inline comment.

Field Name Description

start_line

The start line number of the range.

start_character

The character position in the start line.

end_line

The end line number of the range.

end_character

The character position in the end line.

CommitInfo

The CommitInfo entity contains information about a commit.

Field Name Description

commit

Optional

The commit ID. Not set if included in a RevisionInfo entity that is contained in a map which has the commit ID as key.

parents

The parent commits of this commit as a list of CommitInfo entities. In each parent only the commit and subject fields are populated.

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.

web_links

optional

Links to the commit in external sites as a list of WebLinkInfo entities.

DiffContent

The DiffContent entity contains information about the content differences in a file.

Field Name Description

a

optional

Content only in the file on side A (deleted in B).

b

optional

Content only in the file on side B (added in B).

ab

optional

Content in the file on both sides (unchanged).

edit_a

only present during a replace, i.e. both a and b are present

Text sections deleted from side A as a DiffIntralineInfo entity.

edit_b

only present during a replace, i.e. both a and b are present

Text sections inserted in side B as a DiffIntralineInfo entity.

skip

optional

count of lines skipped on both sides when the file is too large to include all common lines.

common

optional

Set to true if the region is common according to the requested ignore-whitespace parameter, but a and b contain differing amounts of whitespace. When present and true a and b are used instead of ab.

DiffFileMetaInfo

The DiffFileMetaInfo entity contains meta information about a file diff.

Field Name Description

name

The name of the file.

content_type

The content type of the file.

lines

The total number of lines in the file.

web_links

optional

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

DiffInfo

The DiffInfo entity contains information about the diff of a file in a revision.

If the weblinks-only parameter is specified, only the web_links field is set.

Field Name Description

meta_a

not present when the file is added

Meta information about the file on side A as a DiffFileMetaInfo entity.

meta_b

not present when the file is deleted

Meta information about the file on side B as a DiffFileMetaInfo entity.

change_type

The type of change (ADDED, MODIFIED, DELETED, RENAMED COPIED, REWRITE).

intraline_status

only set when the intraline parameter was specified in the request

Intraline status (OK, ERROR, TIMEOUT).

diff_header

A list of strings representing the patch set diff header.

content

The content differences in the file as a list of DiffContent entities.

web_links

optional

Links to the file diff in external sites as a list of DiffWebLinkInfo entries.

binary

not set if false

Whether the file is binary.

DiffIntralineInfo

The DiffIntralineInfo entity contains information about intraline edits in a file.

The information consists of a list of <skip length, mark length> pairs, where the skip length is the number of characters between the end of the previous edit and the start of this edit, and the mark length is the number of edited characters following the skip. The start of the edits is from the beginning of the related diff content lines.

Note that the implied newline character at the end of each line is included in the length calculation, and thus it is possible for the edits to span newlines.

The DiffWebLinkInfo entity describes a link on a diff screen to an external site.

Field Name Description

name

The link name.

url

The link URL.

image_url

URL to the icon of the link.

show_on_side_by_side_diff_view

Whether the web link should be shown on the side-by-side diff screen.

show_on_unified_diff_view

Whether the web link should be shown on the unified diff screen.

EditFileInfo

The EditFileInfo entity contains additional information of a file within a change edit.

Field Name Description

web_links

optional

Links to the diff info in external sites as a list of WebLinkInfo entities.

EditInfo

The EditInfo entity contains information about a change edit.

Field Name Description

commit

The commit of change edit as CommitInfo entity.

baseRevision

The revision of the patch set change edit is based on.

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.

files

optional

The files of the change edit as a map that maps the file names to FileInfo entities.

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.

commands

optional

The download commands for this patch set as a map that maps the command names to the commands.
Only set if download commands are requested.

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.

size_delta

Number of bytes by which the file size increased/decreased.

FixInput

The FixInput entity contains options for fixing commits using the fix change endpoint.

Field Name Description

delete_patch_set_if_commit_missing

If true, delete patch sets from the database if they refer to missing commit options.

expect_merged_as

If set, check that the change is merged into the destination branch as this exact SHA-1. If not, insert a new patch set referring to this commit.

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.

GroupBaseInfo

The GroupBaseInfo entity contains base information about the group.

Field Name Description

id

The id of the group.

name

The name of the group.

IncludedInInfo

The IncludedInInfo entity contains information about the branches a change was merged into and tags it was tagged with.

Field Name Description

branches

The list of branches this change was merged into. Each branch is listed without the 'refs/head/' prefix.

tags

The list of tags this change was tagged with. Each tag is listed without the 'refs/tags/' prefix.

external

optional

A map that maps a name to a list of external systems that include this change, e.g. a list of servers on which this change is deployed.

LabelInfo

The LabelInfo entity contains information about a label on a change, always corresponding to the current patch set.

There are two options that control the contents of LabelInfo: LABELS and DETAILED_LABELS.

  • For a quick summary of the state of labels, use LABELS.

  • For detailed information about labels, including exact numeric votes for all users and the allowed range of votes for the current user, use DETAILED_LABELS.

Common fields

Field Name Description

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.

Fields set by LABELS

Field Name Description

approved

optional

One user who approved this label on the change (voted the maximum value) as an AccountInfo entity.

rejected

optional

One user who rejected this label on the change (voted the minimum value) as an AccountInfo entity.

recommended

optional

One user who recommended this label on the change (voted positively, but not the maximum value) as an AccountInfo entity.

disliked

optional

One user who disliked this label on the change (voted negatively, but not the minimum value) as an AccountInfo entity.

blocking

optional

If true, the label blocks submit operation. If not set, the default is false.

value

optional

The voting value of the user who recommended/disliked this label on the change if it is not “+1”/“-1”.

default_value

optional

The default voting value for the label. This value may be outside the range specified in permitted_labels.

Fields set by DETAILED_LABELS

Field Name Description

all

optional

List of all approvals for this label as a list of ApprovalInfo entities.

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.

MergeableInfo

The MergeableInfo entity contains information about the mergeability of a change.

Field Name Description

submit_type

Submit type used for this change, can be MERGE_IF_NECESSARY, FAST_FORWARD_ONLY, REBASE_IF_NECESSARY, MERGE_ALWAYS or CHERRY_PICK.

mergeable

true if this change is cleanly mergeable, false otherwise

mergeable_into

optional

A list of other branch names where this change could merge cleanly

ProblemInfo

The ProblemInfo entity contains a description of a potential consistency problem with a change. These are not related to the code review process, but rather indicate some inconsistency in Gerrit’s database or repository metadata related to the enclosing change.

Field Name Description

message

Plaintext message describing the problem with the change.

status

optional

The status of fixing the problem (FIXED, FIX_FAILED). Only set if a fix was attempted.

outcome

optional

If status is set, an additional plaintext message describing the outcome of the fix.

PushCertificateInfo

The PushCertificateInfo entity contains information about a push certificate provided when the user pushed for review with git push --signed HEAD:refs/for/<branch>. Only used when signed push is enabled on the server.

Field Name Description

certificate

Signed certificate payload and GPG signature block.

key

Information about the key that signed the push, along with any problems found while checking the signature or the key itself, as a GpgKeyInfo entity.

RebaseInput

The RebaseInput entity contains information for changing parent when rebasing.

Field Name Description

base

optional

The new parent revision. This can be a ref or a SHA1 to a concrete patchset.
Alternatively, a change number can be specified, in which case the current patch set is inferred.
Empty string is used for rebasing directly on top of the target branch, which effectively breaks dependency towards a parent change.

The RelatedChangeAndCommitInfo entity contains information about a related change and commit.

Field Name Description

change_id

optional

The Change-Id of the change.

commit

The commit as a CommitInfo entity.

_change_number

optional

The change number.

_revision_number

optional

The revision number.

_current_revision_number

optional

The current revision number.

status

optional

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

The RelatedChangesInfo entity contains information about related changes.

Field Name Description

changes

A list of RelatedChangeAndCommitInfo entities describing the related changes. Sorted by git commit order, newest to oldest. Empty if there are no related changes.

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, PUBLISH_ALL_REVISIONS and KEEP. All values except PUBLISH_ALL_REVISIONS operate only on drafts for a single revision.
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.

omit_duplicate_comments

optional

If true, comments with the same content at the same place will be omitted.

on_behalf_of

optional

{account-id} the review should be posted on behalf of. To use this option the caller must have been granted labelAs-NAME permission for all keys of labels.

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

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. Not all fields are returned by default. Additional fields can be obtained by adding o parameters as described in Query Changes.

Field Name Description

draft

not set if false

Whether the patch set is a draft.

_number

The patch set number.

created

The timestamp of when the patch set was created.

uploader

The uploader of the patch set as an AccountInfo entity.

ref

The Git reference for the patch set.

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. This information is only included if a plugin implementing the download commands interface is installed.

commit

optional

The commit of the patch set as CommitInfo entity.

files

optional

The files of the patch set as a map that maps the file names to FileInfo entities. Only set if CURRENT_FILES or ALL_FILES option is requested.

actions

optional

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

reviewed

optional

Indicates whether the caller is authenticated and has commented on the current revision. Only set if REVIEWED option is requested.

messageWithFooter

optional

If the COMMIT_FOOTERS option is requested and this is the current patch set, contains the full commit message with Gerrit-specific commit footers, as if this revision were submitted using the Cherry Pick submit type.

push_certificate

optional

If the PUSH_CERTIFICATES option is requested, contains the push certificate provided by the user when uploading this patch set as a PushCertificateInfo entity. This field is always set if the option is requested; if no push certificate was provided, it is set to an empty object.

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 is MERGED. + As wait_for_merge in the SubmitInput is deprecated and the request always waits for the merge to be completed, you can expect MERGED to be returned here.

on_behalf_of

optional

The {account-id} of the user on whose behalf the action should be done. To use this option the caller must have been granted both Submit and Submit (On Behalf Of) permissions. The user named by on_behalf_of does not need to be granted the Submit permission. This feature is aimed for CI solutions: the CI account can be granted both permssions, so individual users don’t need Submit permission themselves. Still the changes can be submited on behalf of real users and not with the identity of the CI account.

SubmitInput

The SubmitInput entity contains information for submitting a change.

Field Name Description

wait_for_merge

Deprecated, always true

Whether the request should wait for the merge to complete.

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.

SuggestedReviewerInfo

The SuggestedReviewerInfo entity contains information about a reviewer that can be added to a change (an account or a group).

SuggestedReviewerInfo has either the account field that contains the AccountInfo entity, or the group field that contains the GroupBaseInfo entity.

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.

The WebLinkInfo entity describes a link to an external site.

Field Name Description

name

The link name.

url

The link URL.

image_url

URL to the icon of the link.