Gerrit Code Review - /changes/ REST API

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 input ChangeInput entity must be provided in the request body. It is not allowed to create changes under refs/tags/ or Gerrit internal ref namespaces such as refs/changes/, refs/meta/external-ids/, and refs/users/. The request would fail with 400 Bad Request in this case.

To create a change the calling user must be allowed to upload to code review.

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" : "NEW"
  }

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

Response

  HTTP/1.1 201 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": "NEW",
    "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. The no-limit parameter can be used remove the default limit on queries and return all results (does not apply to anonymous requests). This might not be supported by all index backends.

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",
      "attention_set": [
        {
          "account": {
            "name": "John Doe"
          },
         "last_update": "2012-07-17 07:19:27.766000000",
         "reason": "reviewer or cc replied"
        }
      ]
      "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 number of changes matching the query exceeds either the internal limit or a supplied n query parameter, 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.

Administrators can use the skip-visibility query parameter to skip visibility filtering. This can be used to ensure that no changes are missed e.g. when querying for changes which need to be reindexed. Without this parameter query results the user has no permission to read are filtered out. REST requests with the skip-visibility option are rejected when the current user doesn’t have the ADMINISTRATE_SERVER capability.

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

Query for the 25 most recent open changes of the projects that you watch

GET /changes/?q=status:open+is:watched&n=25 HTTP/1.0

Query that retrieves changes for a user’s dashboard:

Request

  GET /changes/?q=is:open+owner:self&q=is:open+reviewer:self+-owner:self&q=is:closed+owner:self+limit:5&o=LABELS HTTP/1.0

Response

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

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

Query the changes for your user dashboard

GET /changes/?q=is:open+owner:self&q=is:open+reviewer:self+-owner:self&q=is:closed+owner:self+limit:5&o=LABELS HTTP/1.0

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

LABELS: Includes the labels field which contains all information about labels and approvers that have granted (or rejected) that label. Does not include the permitted_voting_range attribute with the list of ApprovalInfo of the all attribute.

DETAILED_LABELS: Includes the labels field which contains all information about labels and approvers that have granted (or rejected) that label, including the permitted_voting_range attribute with the list of ApprovalInfo of the all attribute.

SUBMIT_REQUIREMENTS: detailed result of the evaluated submit requirements for this change.

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 and magic files, 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 and magic files, 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.

REVIEWER_UPDATES: include updates to reviewers set as ReviewerUpdateInfo entities.

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.

SKIP_DIFFSTAT: skip the 'insertions' and 'deletions' field in ChangeInfo. For large trees, their computation may be expensive.

SUBMITTABLE: include the submittable field in ChangeInfo, which can be used to tell if the change is reviewed and ready for submit.

WEB_LINKS: include the web_links field in CommitInfo, therefore only valid in combination with CURRENT_COMMIT or ALL_COMMITS.

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.

TRACKING_IDS: include references to external tracking systems as TrackingIdInfo.

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": {
          "kind": "REWORK",
          "_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,
              "size": 7782
            },
            "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeDetailCache.java": {
              "lines_inserted": 1,
              "size_delta": 23,
              "size": 6762
            },
            "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeScreen.java": {
              "lines_inserted": 11,
              "lines_deleted": 19,
              "size_delta": -298,
              "size": 47023
            },
            "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeTable.java": {
              "lines_inserted": 23,
              "lines_deleted": 20,
              "size_delta": 132,
              "size": 17727
            },
            "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/StarCache.java": {
              "status": "D",
              "lines_deleted": 139,
              "size_delta": -5512,
              "size": 13098
            },
            "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/StarredChanges.java": {
              "status": "A",
              "lines_inserted": 204,
              "size_delta": 8345,
              "size": 8345
            },
            "gerrit-gwtui/src/main/java/com/google/gerrit/client/ui/Screen.java": {
              "lines_deleted": 9,
              "size_delta": -343,
              "size": 5385
            }
          }
        }
      }
    }
  ]

Get Change

'GET /changes/{change-id}'

Retrieves a change.

Request

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

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

Response

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

  )]}'
  {
    "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940",
    "project": "myProject",
    "branch": "master",
    "attention_set": [
      {
        "account": {
          "name": "John Doe"
        },
       "last_update": "2013-02-21 11:16:36.775000000",
       "reason": "reviewer or cc replied"
      }
    ]
    "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"
    }
  }

Historical state of the change can be retrieved by specifying the meta=SHA-1 parameter. This will use a historical NoteDb snapshot to populate ChangeInfo. If the SHA-1 is not reachable as a NoteDb state, status code 412 is returned.

Get Meta Diff

'GET /changes/{change-id}/meta_diff?old=SHA-1&meta=SHA-1'

Retrieves the difference between two historical states of a change by specifying the old=SHA-1 and the meta=SHA-1 parameters.

If the old parameter is not provided, the parent of the meta SHA-1 is used. If the meta parameter is not provided, the current state of the change is used. If neither are provided, the difference between the current state of the change and its previous state is returned.

Additional fields can be obtained by adding o parameters, analogous to Get Change, and the same concerns for Get Change hold for this endpoint too. Fields are described in Query Changes.

Request

  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/meta_diff?old=b083abc34eb6dbdb9e154ba092fc198000e997b4&meta=63b81f2bde703ae07787a940e8fdf9a1828605b1 HTTP/1.0

As a response, two ChangeInfo entities are returned that describe information added and removed from the old change state, and the two ChangeInfo entities that generated the diff are returned. Only fields that differ between the change’s two states are returned.

Response

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

  )]}'
  {
    "added": {
      "attention_set": [
        {
          "account": {
            "name": "John Doe"
          },
         "last_update": "2013-02-21 11:16:36.775000000",
         "reason": "reviewer or cc replied"
        }
      ]
      "updated": "2013-02-21 11:16:36.775000000",
      "topic": "new-topic"
    },
    "removed": {
      "updated": "2013-02-01 09:59:32.126000000",
      "topic": "old-topic"
    },
    "old_change_info": {
      "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940",
      "project": "myProject",
      "branch": "master",
      "attention_set": [],
      "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940",
      "subject": "Implementing Feature X",
      "status": "NEW",
      "topic": "old-topic",
      "created": "2013-02-01 09:59:32.126000000",
      "updated": "2013-02-01 09:59:32.126000000",
      "mergeable": true,
      "insertions": 34,
      "deletions": 101,
      "_number": 3965,
      "owner": {
        "name": "John Doe"
      }
    },
    "new_change_info": {
      "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940",
      "project": "myProject",
      "branch": "master",
      "attention_set": [
        {
          "account": {
            "name": "John Doe"
          },
         "last_update": "2013-02-21 11:16:36.775000000",
         "reason": "reviewer or cc replied"
        }
      ],
      "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940",
      "subject": "Implementing Feature X",
      "status": "NEW",
      "topic": "new-topic",
      "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"
      }
    },
  }

If the provided SHA-1 for meta is not reachable as a NoteDb state, the status code 412 is returned. If the SHA-1 for old is not reachable, the difference between the change at state meta and an empty change is returned.

Get Change Detail

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

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

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",
    "attention_set": [
      {
        "account": {
          "_account_id": 1000096,
          "name": "John Doe",
          "email": "john.doe@example.com",
          "username": "jdoe"
        },
       "last_update": "2013-02-21 11:16:36.775000000",
       "reason": "reviewer or cc replied"
      }
    ]
    "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 submitted",
          "-1": "I would prefer this is not submitted 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"
      }
    ],
    "reviewers": {
      "REVIEWER": [
        {
          "_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"
        }
      ]
    },
    "reviewer_updates": [
      {
        "state": "REVIEWER",
        "reviewer": {
          "_account_id": 1000096,
          "name": "John Doe",
          "email": "john.doe@example.com",
          "username": "jdoe"
        },
        "updated_by": {
          "_account_id": 1000096,
          "name": "John Doe",
          "email": "john.doe@example.com",
          "username": "jdoe"
        },
        "updated": "2016-07-21 20:12:39.000000000"
      },
      {
        "state": "REMOVED",
        "reviewer": {
          "_account_id": 1000096,
          "name": "John Doe",
          "email": "john.doe@example.com",
          "username": "jdoe"
        },
        "updated_by": {
          "_account_id": 1000096,
          "name": "John Doe",
          "email": "john.doe@example.com",
          "username": "jdoe"
        },
        "updated": "2016-07-21 20:12:33.000000000"
      },
      {
        "state": "CC",
        "reviewer": {
          "_account_id": 1000096,
          "name": "John Doe",
          "email": "john.doe@example.com",
          "username": "jdoe"
        },
        "updated_by": {
          "_account_id": 1000096,
          "name": "John Doe",
          "email": "john.doe@example.com",
          "username": "jdoe"
        },
        "updated": "2016-03-23 21:34:02.419000000",
      },
    ],
    "messages": [
      {
        "id": "YH-egE",
        "author": {
          "_account_id": 1000096,
          "name": "John Doe",
          "email": "john.doe@example.com",
          "username": "jdoe"
        },
        "date": "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"
        },
        "date": "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
      }
    ]
  }

Create Merge Patch Set For Change

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

Update an existing change by using a MergePatchSetInput entity.

Gerrit will create a merge commit based on the information of MergePatchSetInput and add a new patch set to the change corresponding to the new merge commit.

Request

  POST /changes/test~master~Ic5466d107c5294414710935a8ef3b0180fb848dc/merge  HTTP/1.0
  Content-Type: application/json; charset=UTF-8

  {
    "subject": "Merge dev_branch into master",
    "merge": {
      "source": "refs/changes/34/1234/1"
    }
  }

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

Response

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

  )]}'
  {
    "id": "test~master~Ic5466d107c5294414710935a8ef3b0180fb848dc",
    "project": "test",
    "branch": "master",
    "hashtags": [],
    "change_id": "Ic5466d107c5294414710935a8ef3b0180fb848dc",
    "subject": "Merge dev_branch into master",
    "status": "NEW",
    "created": "2016-09-23 18:08:53.238000000",
    "updated": "2016-09-23 18:09:25.934000000",
    "submit_type": "MERGE_IF_NECESSARY",
    "mergeable": true,
    "insertions": 5,
    "deletions": 0,
    "_number": 72,
    "owner": {
      "_account_id": 1000000
    },
    "current_revision": "27cc4558b5a3d3387dd11ee2df7a117e7e581822"
  }

Set Commit Message

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

Creates a new patch set with a new commit message.

The new commit message must be provided in the request body inside a CommitMessageInput entity. If a Change-Id footer is specified, it must match the current Change-Id footer. If the Change-Id footer is absent, the current Change-Id is added to the message.

Request

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

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

Notifications

An email will be sent using the "newpatchset" template.

WIP State	Default
Ready for review	owner, reviewers, CCs, stars, NEW_PATCHSETS watchers
Work in progress	owner

WIP State

Default

Ready for review

owner, reviewers, CCs, stars, NEW_PATCHSETS watchers

Work in progress

owner

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. Any leading or trailing whitespace in the topic name will be removed.

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.

Request

  DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/topic HTTP/1.0

Response

  HTTP/1.1 204 No Content

Get Assignee

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

Retrieves the account of the user assigned to a change.

Request

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

As a response an AccountInfo entity describing the assigned account is returned.

Response

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

  )]}'
  {
    "_account_id": 1000096,
    "name": "John Doe",
    "email": "john.doe@example.com",
    "username": "jdoe"
  }

If the change has no assignee the response is “204 No Content”.

Get Past Assignees

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

Returns a list of every user ever assigned to a change, in the order in which they were first assigned.

Request

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

As a response a list of AccountInfo entities is returned.

Response

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

  )]}'
  [
    {
      "_account_id": 1000051,
      "name": "Jane Doe",
      "email": "jane.doe@example.com",
      "username": "janed"
    },
    {
      "_account_id": 1000096,
      "name": "John Doe",
      "email": "john.doe@example.com",
      "username": "jdoe"
    }
  ]

Set Assignee

'PUT /changes/{change-id}/assignee'

Sets the assignee of a change.

The new assignee must be provided in the request body inside a AssigneeInput entity.

Request

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

  {
    "assignee": "jdoe"
  }

As a response an AccountInfo entity describing the assigned account is returned.

Response

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

  )]}'
  {
    "_account_id": 1000096,
    "name": "John Doe",
    "email": "john.doe@example.com",
    "username": "jdoe"
  }

Delete Assignee

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

Deletes the assignee of a change.

Request

  DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/assignee HTTP/1.0

As a response an AccountInfo entity describing the account of the deleted assignee is returned.

Response

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

  )]}'
  {
    "_account_id": 1000096,
    "name": "John Doe",
    "email": "john.doe@example.com",
    "username": "jdoe"
  }

If the change had no assignee the response is “204 No Content”.

Get Pure Revert

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

Check if the given change is a pure revert of the change it references in revertOf. Optionally, the query parameter o can be passed in to specify a commit (SHA-1 in 40 digit hex representation) to check against. It takes precedence over revertOf. If the change has no reference in revertOf, the parameter is mandatory.

As response a PureRevertInfo entity is returned.

Request

  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/pure_revert?o=247bccf56ae47634650bcc08b8aa784c3580ccas HTTP/1.0

Response

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

  )]}'
  {
    "is_pure_revert" : false
  }

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.

Abandoning a change also removes all users from the attention set.

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

Notifications

An email will be sent using the "abandon" template. The notify handling is ALL. Notifications are suppressed on WIP changes that have never started review.

WIP State	notify=ALL
Ready for review	owner, reviewers, CCs, stars, ABANDONED_CHANGES watchers
Work in progress	not sent
Reviewable WIP	owner, reviewers, CCs, stars, ABANDONED_CHANGES watchers

WIP State

notify=ALL

Ready for review

owner, reviewers, CCs, stars, ABANDONED_CHANGES watchers

Work in progress

not sent

Reviewable WIP

owner, reviewers, CCs, stars, ABANDONED_CHANGES watchers

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": {
        "kind": "REWORK",
        "_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.

Move Change

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

Move a change.

The destination branch must be provided in the request body inside a MoveInput entity. Only veto votes that are blocking the change from submission are moved to the destination branch by default.

Request

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

  {
    "destination_branch" : "release-branch"
  }

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

Response

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

  )]}'
  {
    "id": "myProject~release-branch~I8473b95934b5732ac55d26311a706c9c2bde9940",
    "project": "myProject",
    "branch": "release-branch",
    "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"
    }
  }

Note that this endpoint will not update the change’s parents, which is different from the cherry-pick endpoint.

If the change cannot be moved because the change state doesn’t allow moving 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

If the change cannot be moved because the user doesn’t have abandon permission on the change or upload permission on the destination, 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

  move not permitted

Revert Change

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

Reverts a change.

The subject of the newly created change will be 'Revert "<subject-of-reverted-change>"'. If the subject of the change reverted is above 63 characters, it will be cut down to 59 characters with "…" in the end.

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

Request

  POST /changes/myProject~master~I1ffe09a505e25f15ce1521bcfb222e51e62c2a14/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 user doesn’t have revert permission on the change or upload permission on the destination branch, the response is “403 Forbidden”, and the error message is contained in the response body.

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

Revert Submission

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

Creates open revert changes for all of the changes of a certain submission.

The subject of each revert change will be 'Revert "<subject-of-reverted-change"'. If the subject is above 60 characters, the subject will be cut to 56 characters with "…" in the end. However, whenever reverting the submission of a revert submission, the subject will be shortened from 'Revert "Revert "<subject-of-reverted-change""' to 'Revert^2 "<subject-of-reverted-change"'. Also, for every future revert submission, the only difference in the subject will be the number of the revert (instead of Revert^2 the subject will change to Revert^3 and so on). There are no guarantees about the subjects if the users change the default subjects.

Details for the revert can be specified in the request body inside a RevertInput The topic of all created revert changes will be revert-{submission_id}-{random_string_of_size_10}.

The changes will not be rebased on onto the destination branch so the users may still have to manually rebase them to resolve conflicts and make them submittable.

However, the changes that have the same project and branch will be rebased on top of each other. E.g, the first revert change will have the original change as a parent, and the second revert change will have the first revert change as a parent.

There is one special case that involves merge commits; if a user has multiple changes in the same project and branch, but not in the same change series, those changes can still get submitted together if they have the same topic and change.submitWholeTopic in gerrit.config is set to true. In the case, Gerrit may create merge commits on submit (depending on the submit types of the project). The first parent for the reverts will be the most recent merge commit that was created by Gerrit to merge the different change series into the target branch.

Request

  POST /changes/myProject~master~I1ffe09a505e25f15ce1521bcfb222e51e62c2a14/revert_submission HTTP/1.0

As response RevertSubmissionInfo entity is returned. That entity describes the revert changes.

Response

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

  )]}'
  "revert_changes":
    [
      {
        "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940",
        "project": "myProject",
        "branch": "master",
        "topic": "revert--1571043962462-3640749-ABCEEZGHIJ",
        "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"
        }
      },
      {
        "id": "anyProject~master~1eee2c9d8f352483781e772f35dc586a69ff5646",
        "project": "anyProject",
        "branch": "master",
        "topic": "revert--1571043962462-3640749-ABCEEZGHIJ",
        "change_id": "I1eee2c9d8f352483781e772f35dc586a69ff5646",
        "subject": "Revert \"Implementing Feature Y\"",
        "status": "NEW",
        "created": "2013-02-04 09:59:33.126000000",
        "updated": "2013-02-21 11:16:37.775000000",
        "mergeable": true,
        "insertions": 62,
        "deletions": 11,
        "_number": 3966,
        "owner": {
          "name": "Jane Doe"
        }
      }
    ]

If the user doesn’t have revert permission on the change or upload permission on the destination, the response is “403 Forbidden”, and the error message is contained in the response body.

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 submitting on behalf of another user.

Submitting a change also removes all users from the attention set.

Request

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

  {
    "on_behalf_of": 1001439
  }

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

Submission may submit multiple changes, but we still only return one ChangeInfo object. To query for all submitted changes, please use the submission_id that is part of the response.

Changes that will also be submitted: 1. All changes of the same topic if change.submitWholeTopic configuration is set to true. 2. All dependent changes. 3. The closure of the above (e.g if a dependent change has a topic, all changes of that topic will also be submitted).

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",
    "submitted": "2013-02-21 11:16:36.615000000",
    "_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?o=NON_VISIBLE_CHANGES'

Computes list of all changes which are submitted when Submit is called for this change, including the current change itself.

The list consists of:

The given change.
If change.submitWholeTopic is enabled OR if the o=TOPIC_CLOSURE query parameter is passed, 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.

As a special case, the list is empty if this change would be submitted by itself (without other changes).

Request

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

As a response a SubmittedTogetherInfo entity is returned that describes what would happen if the change were submitted. This response contains a list of changes and a count of changes that are not visible to the caller that are part of the set of changes to be merged.

The listed changes use the same format as in Query Changes with the LABELS, DETAILED_LABELS, CURRENT_REVISION,and SUBMITTABLE options set.

Standard formatting options can be specified with the o parameter, as well as the submitted_together specific options NON_VISIBLE_CHANGES and TOPIC_CLOSURE.

Response

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

)]}'
{
  "changes": [
    {
      "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 submitted",
            "-1": "I would prefer this is not submitted 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
        }
      ],
      "reviewers": {
        "REVIEWER": [
          {
            "_account_id": 1000000
          }
        ]
      },
      "current_revision": "9adb9f4c7b40eeee0646e235de818d09164d7379",
      "revisions": {
        "9adb9f4c7b40eeee0646e235de818d09164d7379": {
          "kind": "REWORK",
          "_number": 1,
          "created": "2015-05-01 15:39:57.979000000",
          "uploader": {
            "_account_id": 1000000
          },
          "ref": "refs/changes/79/1779/1",
          "fetch": {},
        }
      }
    },
    {
      "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 submitted",
            "-1": "I would prefer this is not submitted 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
        }
      ],
      "reviewers": {
        "REVIEWER": [
          {
            "_account_id": 1000000
          }
        ]
      },
      "current_revision": "1bd7c12a38854a2c6de426feec28800623f492c4",
      "revisions": {
        "1bd7c12a38854a2c6de426feec28800623f492c4": {
          "kind": "REWORK",
          "_number": 1,
          "created": "2015-05-01 15:39:57.979000000",
          "uploader": {
            "_account_id": 1000000
          },
          "ref": "refs/changes/80/1780/1",
          "fetch": {},
        }
      }
    }
  ],
  "non_visible_changes": 0
}

If the o=NON_VISIBLE_CHANGES query parameter is not passed, then instead of a SubmittedTogetherInfo entity, the response is a list of changes, or a 403 response with a message if the set of changes to be submitted with this change includes changes the caller cannot read.

Delete Change

'DELETE /changes/{change-id}'

Deletes a change.

New or abandoned changes can be deleted by their owner if the user is granted the Delete Own Changes permission, otherwise only by administrators.

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.

If the enable-context request parameter is set to true, the comment entries will contain a list of ContextLine containing the lines of the source file where the comment was written.

The context-padding request parameter can be used to specify an extra number of context lines to be added before and after the comment range. This parameter only works if enable-context is set to true.

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 Robot Comments

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

Lists the robot comments of all revisions of the change.

Return a map that maps the file path to a list of RobotCommentInfo entries. The entries in the map are sorted by file path.

Request

  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/robotcomments/ 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": "unused import",
        "updated": "2016-02-26 15:40:43.986000000",
        "author": {
          "_account_id": 1000110,
          "name": "Code Analyzer",
          "email": "code.analyzer@example.com"
        },
        "robot_id": "importChecker",
        "robot_run_id": "76b1375aa8626ea7149792831fe2ed85e80d9e04"
      },
      {
        "id": "TveXwFiA",
        "line": 49,
        "message": "wrong indention",
        "updated": "2016-02-26 15:40:45.328000000",
        "author": {
          "_account_id": 1000110,
          "name": "Code Analyzer",
          "email": "code.analyzer@example.com"
        },
        "robot_id": "styleChecker",
        "robot_run_id": "5c606c425dd45184484f9d0a2ffd725a7607839b"
      }
    ]
  }

List Change Drafts

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

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

The enable-context and context-padding request parameters can be used to request comment context. See List Change Comments for more details.

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",
    "submitted": "2013-02-21 11:16:36.615000000",
    "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"
      }
    ]
  }

Set Work-In-Progress

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

Marks the change as not ready for review yet. Changes may only be marked not ready by the owner, project owners or site administrators.

The request body does not need to include a WorkInProgressInput entity if no review comment is added. Actions that create a new patch set in a WIP change default to notifying OWNER instead of ALL.

Marking a change work in progress also removes all users from the attention set.

Request

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

  {
    "message": "Refactoring needs to be done before we can proceed here."
  }

Response

  HTTP/1.1 200 OK

Set Ready-For-Review

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

Marks the change as ready for review (set WIP property to false). Changes may only be marked ready by the owner, project owners or site administrators.

Activates notifications of reviewer. The request body does not need to include a WorkInProgressInput entity if no review comment is added.

Marking a change ready for review also adds all of the reviewers of the change to the attention set.

Request

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

  {
    "message": "Refactoring is done."
  }

Response

  HTTP/1.1 200 OK

Mark Private

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

Marks the change to be private. Only open changes can be marked private. Changes may only be marked private by the owner or site administrators.

A message can be specified in the request body inside a PrivateInput entity.

Request

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

  {
    "message": "After this security fix has been released we can make it public now."
  }

Response

  HTTP/1.1 201 Created

If the change was already private the response is “200 OK”.

Unmark Private

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

Marks the change to be non-private. Note users can only unmark own private changes.

Request

  DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/private HTTP/1.0

Response

  HTTP/1.1 204 No Content

If the change was already not private, the response is “409 Conflict”.

A message can be specified in the request body inside a PrivateInput entity. Historically, this method allowed a body in the DELETE, but that behavior is deprecated. In this case, use a POST request instead:

Request

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

  {
    "message": "This is a security fix that must not be public."
  }

Ignore

'PUT /changes/{change-id}/ignore'

Marks a change as ignored. The change will not be shown in the incoming reviews dashboard, and email notifications will be suppressed. Ignoring a change does not cause the change’s "updated" timestamp to be modified, and the owner is not notified.

Request

  PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/ignore HTTP/1.0

Unignore

'PUT /changes/{change-id}/unignore'

Un-marks a change as ignored.

Request

  PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/unignore HTTP/1.0

Get Hashtags

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

Gets the hashtags associated with a change.

Request

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

As response the change’s hashtags are returned as a list of strings.

Response

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

  )]}'
  [
    "hashtag1",
    "hashtag2"
  ]

Set Hashtags

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

Adds and/or removes hashtags from a change.

The hashtags to add or remove must be provided in the request body inside a HashtagsInput entity.

Request

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

  {
    "add" : [
      "hashtag3"
    ],
    "remove" : [
      "hashtag2"
    ]
  }

As response the change’s hashtags are returned as a list of strings.

Response

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

  )]}'
  [
    "hashtag1",
    "hashtag3"
  ]

List Change Messages

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

Lists all the messages of a change including detailed account information.

Request

  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/messages

As response a list of ChangeMessageInfo entities is returned.

Response

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

  )]}'
  [
    {
      "id": "YH-egE",
      "author": {
      "_account_id": 1000096,
      "name": "John Doe",
      "email": "john.doe@example.com",
      "username": "jdoe"
      },
      "date": "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"
      },
      "date": "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 Change Message

Retrieves a change message including detailed account information.

'GET /changes/{change-id}/messages/{change-message-id}'

As response a ChangeMessageInfo entity is returned.

Response

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

  )]}'
  {
    "id": "aaee04dcb46bafc8be24d8aa70b3b1beb7df5780",
    "author": {
      "_account_id": 1000096,
      "name": "John Doe",
      "email": "john.doe@example.com",
      "username": "jdoe"
     },
     "date": "2013-03-23 21:34:02.419000000",
     "message": "a change message",
     "_revision_number": 1
  }

Delete Change Message

'DELETE /changes/{change-id}/messages/{change-message-id}'
'POST /changes/{change-id}/messages/{change-message-id}/delete'

Deletes a change message by replacing the change message with a new message, which contains the name of the user who deleted the change message and the reason why it was deleted. The reason can be provided in the request body as a DeleteChangeMessageInput entity.

Note that only users with the Administrate Server global capability are permitted to delete a change message.

To delete a change message, send a DELETE request:

Request

  DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/messages/aaee04dcb46bafc8be24d8aa70b3b1beb7df5780 HTTP/1.0

To provide a reason for the deletion, use a POST request:

Request

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

  {
    "reason": "spam"
  }

As response a ChangeMessageInfo entity is returned that describes the updated change message.

Response

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

  )]}'
  {
    "id": "aaee04dcb46bafc8be24d8aa70b3b1beb7df5780",
    "author": {
      "_account_id": 1000096,
      "name": "John Doe",
      "email": "john.doe@example.com",
      "username": "jdoe"
     },
     "date": "2013-03-23 21:34:02.419000000",
     "message": "Change message removed by: Administrator\nReason: spam",
     "_revision_number": 1
  }

Check Submit Requirement

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

Tests a submit requirement and returns the result as a SubmitRequirementResultInfo. The request body must contain a SubmitRequirementInput.

Note that this endpoint does not modify the change resource.

Request

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

    {
      "name": "Code-Review",
      "submittability_expression": "label:Code-Review=+2"
    }

As response a SubmitRequirementResultInfo entity is returned that describes the submit requirement result.

Response

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

  )]}'
  {
    "name": "Code-Review",
    "status": "SATISFIED",
    "submittability_expression_result": {
      "expression": "label:Code-Review=+2",
      "fulfilled": true,
      "passingAtoms": [
        "label:Code-Review=+2"
      ]
    },
    "is_legacy": false
  }

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 ..."
    },
    "base_patch_set_number": 1,
    "base_revision": "c35558e0925e6985c91f3a16921537d5e572b7a3",
    "ref": "refs/users/01/1000001/edit-76482/1"
  }

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

To upload a file as binary data in the request body:

Request

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

  {
    "binary_content": "data:text/plain;base64,SGVsbG8sIFdvcmxkIQ=="
  }

Note that it must be base-64 encoded data uri.

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

When the change edit is a no-op, for example when providing the same file content that the file already has, '409 no changes were made' is returned.

Response

  HTTP/1.1 409 no changes were made

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.

If the base parameter is set to true, the returned content is from the revision that the edit is based on.

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.

If the base parameter is set to true, the returned message is from the revision that the edit is based on.

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.

Options can be provided in the request body as a PublishChangeEditInput entity.

Request

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

  {
    "notify": "NONE"
  }

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.

This REST endpoint only suggests accounts that

are active
can see the change
are visible to the calling user
are not already reviewer on the change
don’t own the change
are not service users (unless skipServiceUsers is set to false)

Groups can be excluded from the results by specifying the 'exclude-groups' request parameter:

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

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"
      },
      "count": 1
    },
    {
      "group": {
        "id": "4fd581c0657268f2bdcc26699fbf9ddb76e3a279",
        "name": "Joiner"
      },
      "count": 5
    }
  ]

To suggest CCs reviewer-state=CC can be specified as additional URL parameter. This includes existing reviewers in the result, but excludes existing CCs.

'GET /changes/{change-id}/suggest_reviewers?q=J&reviewer-state=CC'

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.

Users can be moved from reviewer to CC and vice versa. This means if a user is added as CC that is already a reviewer on the change, the reviewer state of that user is updated to CC. If a user that is already a CC on the change is added as reviewer, the reviewer state of that user is updated to reviewer.

Adding a new reviewer also adds that reviewer to the attention set, unless the change is work in progress. Also, moving a reviewer to CC removes that user from the attention set.

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

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

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.

If a group is added as CC and members of this group are already reviewers on the change, these members stay reviewers on the change (they are not downgraded to CC). However if a group is added as reviewer, all group members become reviewer of the change, even if they have been added as CC before.

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

  )]}'
  {
    "input": "MyProjectVerifiers",
    "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

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

If reviewer.enableByEmail is set for the project, reviewers and CCs are not required to have a Gerrit account. If you POST an email address of a reviewer or CC then, they will be added to the change even if they don’t have a Gerrit account.

If this option is disabled, the request would fail with 400 Bad Request if the email address can’t be resolved to an active Gerrit account.

Note that the name is optional so both "un.registered@reviewer.com" and "John Doe <un.registered@reviewer.com>" are valid inputs.

Reviewers without Gerrit accounts can only be added on changes visible to anonymous users.

Request

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

  {
    "reviewer": "John Doe <un.registered@reviewer.com>"
  }

Response

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

  )]}'
  {
    "input": "John Doe <un.registered@reviewer.com>"
  }

Notifications

An email will be sent using the "newchange" template.

WIP State	Default	notify=ALL
Ready for review	owner, reviewers, CCs	owner, reviewers, CCs
Work in progress	not sent	owner, reviewers, CCs

WIP State

Default

notify=ALL

Ready for review

owner, reviewers, CCs

Work in progress

not sent

owner, reviewers, CCs

Delete Reviewer

'DELETE /changes/{change-id}/reviewers/{account-id}'
'POST /changes/{change-id}/reviewers/{account-id}/delete'

Deletes a reviewer from a change. Deleting a reviewer also removes that user from the attention set.

Request

  DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe HTTP/1.0
  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe/delete HTTP/1.0

Options can be provided in the request body as a DeleteReviewerInput entity. Historically, this method allowed a body in the DELETE, but that behavior is deprecated. In this case, use a POST request instead:

Request

  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe/delete HTTP/1.0
  Content-Type: application/json; charset=UTF-8

  {
    "notify": "NONE"
  }

Response

  HTTP/1.1 204 No Content

Notifications

An email will be sent using the "deleteReviewer" template. If deleting the reviewer resulted in one or more approvals being removed, then the deleted reviewer will also receive a notification (unless notify=NONE).

WIP State	Default Recipients
Ready for review	notify=ALL: deleted reviewer (if voted), owner, reviewers, CCs, stars, ALL_COMMENTS watchers
Work in progress	notify=NONE: deleted reviewer (if voted)

WIP State

Default Recipients

Ready for review

notify=ALL: deleted reviewer (if voted), owner, reviewers, CCs, stars, ALL_COMMENTS watchers

Work in progress

notify=NONE: deleted reviewer (if voted)

List Votes

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

Lists the votes for a specific reviewer of the change.

Request

  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe/votes/ HTTP/1.0

As result a map is returned that maps the label name to the label value. The entries in the map are sorted by label name.

Response

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

  )]}'
  {
    "Code-Review": -1,
    "Verified": 1
    "Work-In-Progress": 1,
  }

Delete Vote

'DELETE /changes/{change-id}/reviewers/{account-id}/votes/{label-id}'
'POST /changes/{change-id}/reviewers/{account-id}/votes/{label-id}/delete'

Deletes a single vote from a change. Note, that even when the last vote of a reviewer is removed the reviewer itself is still listed on the change.

If another user removed a user’s vote, the user with the deleted vote will be added to the attention set.

Request

  DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe/votes/Code-Review HTTP/1.0
  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe/votes/Code-Review/delete HTTP/1.0

Options can be provided in the request body as a DeleteVoteInput entity. Historically, this method allowed a body in the DELETE, but that behavior is deprecated. In this case, use a POST request instead:

Request

  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe/votes/Code-Review/delete HTTP/1.0
  Content-Type: application/json; charset=UTF-8

  {
    "notify": "NONE"
  }

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 Description

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

Retrieves the description of a patch set.

Request

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

Response

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

  )]}'
  "Added Documentation"

If the patch set does not have a description an empty string is returned.

Set Description

'PUT /changes/{change-id}/revisions/{revision-id}/description'

Sets the description of a patch set.

The new description must be provided in the request body inside a DescriptionInput entity.

Request

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

  {
    "description": "Added Documentation"
  }

As response the new description is returned.

Response

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

  )]}'
  "Added Documentation"

Get Merge List

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

Returns the list of commits that are being integrated into a target branch by a merge commit. By default the first parent is assumed to be uninteresting. By using the parent option another parent can be set as uninteresting (parents are 1-based).

The list of commits is returned as a list of CommitInfo entities. Web links are only included if the links option was set.

Request

  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/7e30d802b890ec8d0be45b1cc2a8ef092bcfc858/mergelist HTTP/1.0

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 ..."
    }
  ]

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 REST endpoint names 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 submitted",
          "-1": "I would prefer this is not submitted 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"
      }
    ],
    "reviewers": {
      "REVIEWER": [
        {
          "_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": {
        "kind": "REWORK",
        "_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": [
      {
        "project": "gerrit",
        "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"
      },
      {
        "project": "gerrit",
        "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, optionally also publishing draft comments, setting labels, adding reviewers or CCs, and modifying the work in progress property.

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

If the labels are set, the user sending the request will automatically be added as a reviewer, otherwise (if they only commented) they are added to the CC list.

Some updates to the attention set occur here. If more than one update should occur, only the first update in the order of the below documentation occurs:

If a user is part of remove_from_attention_set, the user will be explicitly removed from the attention set.

If a user is part of add_to_attention_set, the user will be explicitly added to the attention set.

If the boolean ignore_default_attention_set_rules is set to true, all other rules below will be ignored:

The user who created the review is removed from the attention set.

If the change is ready for review, the following also apply:

When the uploader replies, the owner is added to the attention set.

When the owner or uploader replies, all the reviewers are added to the attention set.

When neither the owner nor the uploader replies, add the owner and the uploader to the attention set.

Then, new reviewers are added to the attention set, and removed reviewers (by becoming CC) are removed from the attention set.

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

Here is an example of using this method to set labels:

Request

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

  {
    "tag": "jenkins",
    "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 ReviewResult entity is returned that describes the applied labels and any added reviewers (e.g. yourself, if you set a label but weren’t previously a reviewer on this CL).

Response

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

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

It is also possible to add one or more reviewers or CCs to a change simultaneously with a review:

Request

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

  {
    "message": "I don't have context here. Jane and maybe John and the project leads should take a look.",
    "reviewers": [
      {
        "reviewer": "jane.roe@example.com"
      },
      {
        "reviewer": "john.doe@example.com",
        "state": "CC"
      }
      {
        "reviewer": "MyProjectVerifiers",
      }
    ]
  }

Each element of the reviewers list is an instance of ReviewerInput. The corresponding result of adding each reviewer will be returned in a map of inputs to ReviewerResults.

Response

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

  )]}'
  {
    "reviewers": {
      "jane.roe@example.com": {
        "input": "jane.roe@example.com",
        "reviewers": [
          {
            "_account_id": 1000097,
            "name": "Jane Roe",
            "email": "jane.roe@example.com"
            "approvals": {
              "Verified": " 0",
              "Code-Review": " 0"
            },
          },
        ]
      },
      "john.doe@example.com": {
        "input": "john.doe@example.com",
        "ccs": [
          {
            "_account_id": 1000096,
            "name": "John Doe",
            "email": "john.doe@example.com"
            "approvals": {
              "Verified": " 0",
              "Code-Review": " 0"
            },
          }
        ]
      },
      "MyProjectVerifiers": {
        "input": "MyProjectVerifiers",
        "reviewers": [
          {
            "_account_id": 1000098,
            "name": "Alice Ansel",
            "email": "alice.ansel@example.com"
            "approvals": {
              "Verified": " 0",
              "Code-Review": " 0"
            },
          },
          {
            "_account_id": 1000099,
            "name": "Bob Bollard",
            "email": "bob.bollard@example.com"
            "approvals": {
              "Verified": " 0",
              "Code-Review": " 0"
            },
          },
        ]
      }
    }
  }

If there are any errors returned for reviewers, the entire review request will be rejected with 400 Bad Request. None of the entries will have the reviewers or ccs field set, and those which specifically failed will have the errors field set containing details of why they failed.

Error Response

  HTTP/1.1 400 Bad Request
  Content-Disposition: attachment
  Content-Type: application/json; charset=UTF-8

  )]}'
  {
    "reviewers": {
      "jane.roe@example.com": {
        "input": "jane.roe@example.com",
        "error": "Account of jane.roe@example.com is inactive."
      },
      "john.doe@example.com": {
        "input": "john.doe@example.com"
      },
      "MyProjectVerifiers": {
        "input": "MyProjectVerifiers",
        "error": "The group My Group has 15 members. Do you want to add them all as reviewers?",
        "confirm": true
      }
    }
  }

Notifications

An email will be sent using the "comment" template.

If the top-level notify property is null or not set, then notification behavior depends on whether the change is WIP, whether it has started review, and whether the tag property is null.

Note	If adding reviewers, the notify property of each ReviewerInput is ignored. Use the notify property of the top-level ReviewInput instead.

For the purposes of this table, everyone means owner, reviewers, CCs, stars, and ALL_COMMENTS watchers.

WIP State	Review Started	Tag Given	Default	notify=ALL
Ready for review	N/A	N/A	everyone	everyone
Work in progress	no	no	not sent	everyone
Work in progress	no	yes	owner	everyone
Work in progress	yes	no	everyone	everyone
Work in progress	yes	yes	owner	everyone

WIP State

Review Started

Tag Given

Default

notify=ALL

Ready for review

N/A

everyone

Work in progress

not sent

everyone

Work in progress

yes

owner

everyone

Work in progress

yes

everyone

Work in progress

yes

owner

everyone

If reviewers are added, then a second email will be sent using the "newchange" template. The notification logic for this email is the same as for Add Reviewer.

WIP State	Default	notify=ALL
Ready for review	owner, reviewers, CCs	owner, reviewers, CCs
Work in progress	not sent	owner, reviewers, CCs

WIP State

Default

notify=ALL

Ready for review

owner, reviewers, CCs

Work in progress

not sent

owner, reviewers, CCs

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": {
        "kind": "REWORK",
        "_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. Submitting a change also removes all users from the attention set.

Request

  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/submit HTTP/1.0

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

Submission may submit multiple changes, but we still only return one ChangeInfo object. To query for all submitted changes, please use the submission_id that is part of the response.

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",
    "submitted": "2013-02-21 11:16:36.615000000",
    "_number": 3965,
    "owner": {
      "name": "John Doe"
    }
  }

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

Response

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

  "revision 674ac754f91e64a0efb8087e59a176484bd534d1 is not current revision"

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

If the path parameter is set, the returned content is a diff of the single file that the path refers to.

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",
    strategy: "recursive",
    mergeable: true
  }

If the other-branches parameter is specified, the mergeability will also be checked for all other branches which are listed in the branchOrder section in the project.config file.

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

  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 SubmitRecord describing the permutations that satisfy the tested submit rule.

If the submit rule was a no-op, the response is “204 No Content”.

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

Delete Comment

'DELETE /changes/{change-id}/revisions/{revision-id}/comments/{comment-id}'
'POST /changes/{change-id}/revisions/{revision-id}/comments/{comment-id}/delete'

Deletes a published comment of a revision. Instead of deleting the whole comment, this endpoint just replaces the comment’s message with a new message, which contains the name of the user who deletes the comment and the reason why it’s deleted.

This endpoint also marks the comment as resolved since deleted comments are not actionable.

Note that only users with the Administrate Server global capability are permitted to delete a comment.

Deletion reason can be provided in the request body as a DeleteCommentInput entity. Historically, this method allowed a body in the DELETE, but that behavior is deprecated. In this case, use a POST request instead:

Request

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

  {
    "reason": "contains confidential information"
  }

As response a CommentInfo entity is returned that describes the updated 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": "Comment removed by: Administrator; Reason: contains confidential information",
    "updated": "2013-02-26 15:40:43.986000000",
    "author": {
      "_account_id": 1000096,
      "name": "John Doe",
      "email": "john.doe@example.com"
    }
  }

List Robot Comments

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

Lists the robot comments of a revision.

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

Request

  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/robotcomments/ 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": "unused import",
        "updated": "2016-02-26 15:40:43.986000000",
        "author": {
          "_account_id": 1000110,
          "name": "Code Analyzer",
          "email": "code.analyzer@example.com"
        },
        "robot_id": "importChecker",
        "robot_run_id": "76b1375aa8626ea7149792831fe2ed85e80d9e04"
      },
      {
        "id": "TveXwFiA",
        "line": 49,
        "message": "wrong indention",
        "updated": "2016-02-26 15:40:45.328000000",
        "author": {
          "_account_id": 1000110,
          "name": "Code Analyzer",
          "email": "code.analyzer@example.com"
        },
        "robot_id": "styleChecker",
        "robot_run_id": "5c606c425dd45184484f9d0a2ffd725a7607839b"
      }
    ]
  }

Get Robot Comment

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

Retrieves a robot comment of a revision.

Request

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

As response a RobotCommentInfo entity is returned that describes the robot comment.

Response

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

  )]}'
  {
    "id": "TvcXrmjM",
    "line": 23,
    "message": "unused import",
    "updated": "2016-02-26 15:40:43.986000000",
    "author": {
      "_account_id": 1000110,
      "name": "Code Analyzer",
      "email": "code.analyzer@example.com"
    },
    "robot_id": "importChecker",
    "robot_run_id": "76b1375aa8626ea7149792831fe2ed85e80d9e04"
  }

List Ported Comments

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

Ports comments of other revisions to the requested revision.

Only comments added on earlier patchsets are ported. That set of comments is filtered even further due to some additional rules. Callers of this endpoint shouldn’t rely on the exact logic of which comments are ported as that logic might change in the future. Instead, callers must be able to handle any smaller/larger set of comments returned by this endpoint.

Typically, a comment thread is returned fully or excluded fully. However, draft comments and robot comments are ignored and not returned via this endpoint. Hence, it’s possible to get ported comments from this endpoint which are a reply to a non-ported robot comment. Callers must be able to deal with this situation.

The returned comments are organized in a map of file path to CommentInfo entries in the same fashion as for the List Revision Comments endpoint. The map is filled with the original comment attributes except for these attributes: path, line, and range point to the computed position in the target revision. If the exactly correct position can’t be determined, those fields will be filled with the next best position. That can also mean not filling the line or range attribute anymore and thus converting the comment to a file comment (or even moving the comment to a different file or the patchset level). Callers of this endpoint must be able to deal with this and not rely on the original comment position.

It’s possible that this endpoint returns different CommentInfo entries with the same comment UUID. This is not a bug but a feature. If a comment appears on a file which Gerrit recognizes as copied between patchsets, the ported version of this comment consists of two ported instances having the same UUID but different file/line/range positions. Callers must be able to handle this situation.

Repeated calls of this endpoint might produce different results. Internal errors during the position computation are mapped to fallback locations for affected comments. Those errors might have vanished on later calls, upon which this endpoint returns the actually mapped position. In addition, comments can be deleted and draft comments can be published, upon which the set of ported comments may change.

Request

  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/4/ported_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",
        "patch_set": 2,
        "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"
        },
        "unresolved": true
      },
      {
        "id": "TveXwFiA",
        "patch_set": 2,
        "line": 23,
        "in_reply_to": "TvcXrmjM",
        "message": "Done",
        "updated": "2013-02-26 15:40:45.328000000",
        "author": {
          "_account_id": 1000097,
          "name": "Jane Roe",
          "email": "jane.roe@example.com"
        },
        "unresolved": true
      }
    ]
  }

List Ported Drafts

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

Ports draft comments of other revisions to the requested revision.

This endpoint behaves similarly to the List Ported Comments endpoint. With this endpoint, only draft comments of the calling user are ported, though. If a draft comment is a reply to a published comment, only the ported draft comment is returned.

Depending on the filtering rules, it’s possible that this endpoint returns a draft comment which is a reply to a comment thread which is not returned by the List Ported Comments endpoint. That’s intended behavior. Callers must be able to handle this situation. The same holds for drafts which are a reply to a robot comment.

Different than the List Ported Comments endpoint, the author of the returned comments is not filled for this endpoint as only comments of the calling user are returned.

This endpoint requires authentication.

Request

  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/ported_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": "TveXwFiA",
        "patch_set": 2,
        "line": 23,
        "in_reply_to": "TvcXrmjM",
        "message": "Done",
        "updated": "2013-02-26 15:40:45.328000000",
        "unresolved": true
      }
    ]
  }

Apply Fix

'POST /changes/{change-id}/revisions/{revision-id}/fixes/{fix-id}/apply'

Applies a suggested fix by creating a change edit which includes the modifications indicated by the fix suggestion. If a change edit already exists, it will be updated accordingly. A fix can only be applied if no change edit exists and the fix refers to the current patch set, or the fix refers to the patch set on which the change edit is based.

Request

  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/fixes/8f605a55_f6aa4ecc/apply HTTP/1.0

If the fix was successfully applied, an EditInfo describing the resulting change edit is returned.

Response

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

    )]}'
    {
      "commit": {
        "parents": [
          {
            "commit": "1eee2c9d8f352483781e772f35dc586a69ff5646",
          }
        ],
        "author": {
          "name": "John Doe",
          "email": "john.doe@example.com",
          "date": "2013-05-07 15:21:27.000000000",
          "tz": 120
         },
         "committer": {
           "name": "Jane Doe",
           "email": "jane.doe@example.com",
           "date": "2013-05-07 15:35:43.000000000",
           "tz": 120
         },
         "subject": "Implement feature X",
         "message": "Implement feature X\n\nWith this feature ..."
      },
      "base_patch_set_number": 1,
      "base_revision": "674ac754f91e64a0efb8087e59a176484bd534d1"
      "ref": "refs/users/01/1000001/edit-42622/1"
    }

If the application failed e.g. due to conflicts with an existing change edit, the response “409 Conflict” including an error message in the response body is returned.

Response

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

  The existing change edit could not be merged with another tree.

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 FileInfo entry. 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,
      "size": 551
    },
    "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": {
      "lines_inserted": 5,
      "lines_deleted": 3,
      "size_delta": 98,
      "size": 23348
    }
  }

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. Clients that also need the FileInfo should make two requests.

For merge commits only, the integer-valued request parameter parent changes the response to return a map of the files which are different in this commit compared to the given parent commit. The value is the 1-based index of the parent’s position in the commit object, with the first parent always belonging to the target branch. If not specified, the response contains a map of the files different in the auto merge result.

The request parameter base changes the response to return a map of the files which are different in this commit compared to the given revision. The revision must correspond to a patch set in the change.

The reviewed, q, parent, and base options are mutually exclusive. That is, only one of them may be used at a time.

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.

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 is non-positive, the patch set is referenced.

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.

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/download 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/download?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.

The integer-valued request parameter parent can be specified to control the parent commit number against which the diff should be generated. This is useful for supporting review of merge commits. The value is the 1-based index of the parent’s position in the commit object.

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 whitespace parameter can be specified to control how whitespace differences are reported in the result. Valid values are IGNORE_NONE, IGNORE_TRAILING, IGNORE_LEADING_AND_TRAILING or IGNORE_ALL.

Preview fix

'GET /changes/{change-id}/revisions/{revision-id}/fixes/{fix-id}/preview'

Gets the diffs of all files for a certain {fix-id}. As response, a map of DiffInfo entities is returned that describes the diffs.

Each DiffInfo is the differences between the patch set indicated by revision-id and a virtual patch set with the applied fix.

Get Blame

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

Gets the blame 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/blame HTTP/1.0

As response a BlameInfo entity is returned that describes the blame.

Response

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

  )]
  {
    [
      {
        "author": "Joe Daw",
        "id": "64e140b4de5883a4dd74d06c2b62ccd7ffd224a7",
        "time": 1421441349,
        "commit_msg": "RST test\n\nChange-Id: I11e9e24bd122253f4bb10c36dce825ac2410d646\n",
        "ranges": [
          {
            "start": 1,
            "end": 10
          },
          {
            "start": 16,
            "end": 296
          }
        ]
      },
      {
        "author": "Jane Daw",
        "id": "8d52621a0e2ac6adec73bd3a49f2371cd53137a7",
        "time": 1421825421,
        "commit_msg": "add banner\n\nChange-Id: I2eced9b2691015ae3c5138f4d0c4ca2b8fb15be9\n",
        "ranges": [
          {
            "start": 13,
            "end": 13
          }
        ]
      }
    ]
  }

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

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.

To cherry pick a commit with no change-id associated with it, see CherryPickCommit.

The commit message and destination branch must be provided in the request body inside a CherryPickInput entity. If the commit message does not specify a Change-Id, a new one is picked for the destination change.

When cherry-picking a change into a branch that already contains the Change-Id that we want to cherry-pick, the cherry-pick will create a new patch-set on the destination’s branch’s appropriate Change-Id. If the change is closed on the destination branch, the cherry-pick will fail.

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

Revision Reviewer Endpoints

List Revision Reviewers

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

Lists the reviewers of a revision.

Please note that only the current revision is supported.

As result a list of ReviewerInfo entries is returned.

Request

  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/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"
    }
  ]

List Revision Votes

'GET /changes/{change-id}/revisions/{revision-id}/reviewers/{account-id}/votes/'

Lists the votes for a specific reviewer of the revision.

Please note that only the current revision is supported.

Request

  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/reviewers/John%20Doe/votes/ HTTP/1.0

As result a map is returned that maps the label name to the label value. The entries in the map are sorted by label name.

Response

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

  )]}'
  {
    "Code-Review": -1,
    "Verified": 1,
    "Work-In-Progress": 1
  }

Delete Revision Vote

'DELETE /changes/{change-id}/revisions/{revision-id} /reviewers/{account-id}/votes/{label-id}'
'POST /changes/{change-id}/revisions/{revision-id} /reviewers/{account-id}/votes/{label-id}/delete'

Deletes a single vote from a revision. The deletion will be possible only if the revision is the current revision. By using this endpoint you can prevent deleting the vote (with same label) from a newer patch set by mistake.

Note, that even when the last vote of a reviewer is removed the reviewer itself is still listed on the change.

If another user removed a user’s vote, the user with the deleted vote will be added to the attention set.

Request

  DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/reviewers/John%20Doe/votes/Code-Review HTTP/1.0
  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/reviewers/John%20Doe/votes/Code-Review/delete HTTP/1.0

Request

  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/reviewers/John%20Doe/votes/Code-Review/delete HTTP/1.0
  Content-Type: application/json; charset=UTF-8

  {
    "notify": "NONE"
  }

Response

  HTTP/1.1 204 No Content

Attention Set Endpoints

Get Attention Set

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

Returns all users that are currently in the attention set. As response a list of AttentionSetInfo entity is returned.

Request

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

Response

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

  )]}'
  [
    {
      "account": {
        "_account_id": 1000096,
        "name": "John Doe",
        "email": "john.doe@example.com",
        "username": "jdoe"
      },
      "last_update": "2013-02-01 09:59:32.126000000",
      "reason": "reviewer or cc replied"
    },
    {
      "account": {
        "_account_id": 1000097,
        "name": "Jane Doe",
        "email": "jane.doe@example.com",
        "username": "janedoe"
      },
      "last_update": "2013-02-01 09:59:32.126000000",
      "reason": "Reviewer was added"
    }
  ]

Add To Attention Set

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

Adds a single user to the attention set of a change.

A user can only be added if they are not in the attention set. If a user is added while already in the attention set, the request is silently ignored.

The user must be a reviewer, cc, uploader, or owner on the change.

Request

  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/attention HTTP/1.0

Details should be provided in the request body as an AttentionSetInput entity.

Request

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

  {
    "user": "John Doe",
    "reason": "reason"
  }

Response

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

  )]}'
  {
    "_account_id": 1000096,
    "name": "John Doe",
    "email": "john.doe@example.com",
    "username": "jdoe"
  }

Remove from Attention Set

'DELETE /changes/{change-id}/attention/{account-id}'
'POST /changes/{change-id}/attention/{account-id}/delete'

Deletes a single user from the attention set of a change.

A user can only be removed from the attention set if they are currently in the attention set. Otherwise, the request is silently ignored.

Request

  DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/attention/John%20Doe HTTP/1.0
  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/attention/John%20Doe/delete HTTP/1.0

Reason can be provided in the request body as an AttentionSetInput entity.

User must be left empty, or the user must be exactly the same user as in the request header.

Request

  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/attention/John%20Doe/delete HTTP/1.0
  Content-Type: application/json; charset=UTF-8

  {
    "reason": "reason"
  }

Response

  HTTP/1.1 204 No Content

Attention Set

Attention Set is the set of users that should perform some action on the change. E.g, reviewers should review the change, owner/uploader should add a new patchset or respond to comments.

Users are added to the attention set if one the following apply:

They are manually added in ReviewInput in add_to_attention_set.
They are added as reviewers.
The change is marked ready for review.
As an owner/uploader, when someone replies on your change.
As a reviewer, when the owner/uploader replies.
When the user’s vote is deleted by another user.
The rules above (except manually adding to the attention set) don’t apply for changes that are work in progress.

Users are removed from the attention set if one the following apply:

They are manually removed in ReviewInput in remove_from_attention_set.
They are removed from reviewers.
The change is marked work in progress, abandoned, or submitted.
When the user replies on a change.

If the ignore_default_attention_set_rules in ReviewInput is set to true, no other changes to the attention set will occur during the set-review. Also, users specified in the list will occur instead of any of the implicit changes to the attention set. E.g, if a user is added by add_to_attention_set in ReviewInput, but also the change is marked work in progress, the user will still be added.

IDs

{account-id}

{change-id}

Identifier that uniquely identifies one change. It contains the URL-encoded project name as well as the change number: "'<project>~<changeNumber>'"

Alternative identifiers

Gerrit also supports an array of other change identifiers.

Note

Even though these identifiers will work in the majority of cases it is highly recommended to use "'<project>~<changeNumber>'" whenever possible. Since these identifiers require additional lookups from index and caches, to be translated to the "'<project>~<changeNumber>'" identifier, they may result in both false-positives and false-negatives. Furthermore the additional lookup mean that they come with a performance penalty.

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 change number if it uniquely identifies one change ("4247")

{change-message-id}

ID of a change message returned in a ChangeMessageInfo.

{comment-id}

UUID of a published comment.

{draft-id}

UUID of a draft comment.

{label-id}

The name of the label.

{file-id}

The path of the file.

The following magic paths are supported:

/COMMIT_MSG:

The commit message and headers with the parent commit(s), the author information and the committer information.
/MERGE_LIST (for merge commits only):

The list of commits that are being integrated into the destination branch by submitting the merge commit.
/PATCHSET_LEVEL:

This file path is used exclusively for posting and indicating patchset-level comments, thus not relevant for other use-cases.

{fix-id}

UUID of a suggested fix.

{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)
"0" or the literal edit for a change edit

JSON Entities

AbandonInput

The AbandonInput entity contains information for abandoning a change.

Field Name Description

Field Name		Description
`message`	optional	Message to be added as review comment to the change when abandoning the change.
`notify`	optional	Notify handling that defines to whom email notifications should be sent after the change is abandoned. Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. If not set, the default is `ALL`.
`notify_details`	optional	Additional information about whom to notify about the update as a map of recipient type to NotifyInfo entity.

message

optional

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

notify

optional

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

notify_details

optional

Additional information about whom to notify about the update as a map of recipient type to NotifyInfo entity.

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

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.

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.

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

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.
`permitted_voting_range`	optional	The VotingRangeInfo the user is authorized to vote on that label. If present, the user is permitted to vote on the label regarding the range values. If absent, the user is not permitted to vote on that label.
`date`	optional	The time and date describing when the approval was made.
`tag`	optional	Value of the `tag` field from ReviewInput set while posting the review. Votes/comments that contain `tag` with 'autogenerated:' prefix can be filtered out in the web UI. NOTE: To apply different tags on different votes/comments multiple invocations of the REST call are required.
`post_submit`	not set if `false`	If true, this vote was made after the change was submitted.

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.

permitted_voting_range

optional

The VotingRangeInfo the user is authorized to vote on that label. If present, the user is permitted to vote on the label regarding the range values. If absent, the user is not permitted to vote on that label.

date

optional

The time and date describing when the approval was made.

tag

optional

Value of the tag field from ReviewInput set while posting the review. Votes/comments that contain tag with 'autogenerated:' prefix can be filtered out in the web UI. NOTE: To apply different tags on different votes/comments multiple invocations of the REST call are required.

post_submit

not set if false

If true, this vote was made after the change was submitted.

AssigneeInput

The AssigneeInput entity contains the identity of the user to be set as assignee.

Field Name Description

Field Name		Description
`assignee`		The ID of one account that should be added as assignee.

assignee

The ID of one account that should be added as assignee.

AttentionSetInfo

The AttentionSetInfo entity contains details of users that are in the attention set.

Field Name Description

Field Name		Description
`account`		AccountInfo entity.
`last_update`		The timestamp of the last update.
`reason`		The reason for adding or removing the user. If the update was caused by another user, that account is represented by account ID in reason as `<GERRIT_ACCOUNT_18419>` and the corresponding AccountInfo can be found in `reason_account` field.
`reason_account`		AccountInfo of the user who caused the update.

account

AccountInfo entity.

last_update

The timestamp of the last update.

reason

The reason for adding or removing the user. If the update was caused by another user, that account is represented by account ID in reason as <GERRIT_ACCOUNT_18419> and the corresponding AccountInfo can be found in reason_account field.

reason_account

AccountInfo of the user who caused the update.

AttentionSetInput

The AttentionSetInput entity contains details for adding users to the attention set and removing them from it.

Field Name Description

Field Name		Description
`user`	optional	ID of the account that should be added to the attention set. For removals, this field should be empty or the same as the field in the request header.
`reason`		The reason of for adding or removing the user.
`notify`	optional	Notify handling that defines to whom email notifications should be sent after the change is created. Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. If not set, the default is `OWNER`.
`notify_details`	optional	Additional information about whom to notify about the change creation as a map of recipient type to NotifyInfo entity.

user

optional

ID of the account that should be added to the attention set. For removals, this field should be empty or the same as the field in the request header.

reason

The reason of for adding or removing the user.

notify

optional

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

notify_details

optional

Additional information about whom to notify about the change creation as a map of recipient type to NotifyInfo entity.

BlameInfo

The BlameInfo entity stores the commit metadata with the row coordinates where it applies.

Field Name Description

Field Name	Description
`author`	The author of the commit.
`id`	The id of the commit.
`time`	Commit time.
`commit_msg`	The commit message.
`ranges`	The blame row coordinates as RangeInfo entities.

author

The author of the commit.

id

The id of the commit.

time

Commit time.

commit_msg

The commit message.

ranges

The blame row coordinates as RangeInfo entities.

ChangeEditInput

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

Field Name Description

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.

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

Field Name		Description
`message`		New commit message.

message

New commit message.

ChangeInfo

The ChangeInfo entity contains information about a change.

Field Name Description

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.
`attention_set`	optional	The map that maps account IDs to AttentionSetInfo of that account. Those are all accounts that are currently in the attention set.
`removed_from_attention_set`	optional	The map that maps account IDs to AttentionSetInfo of that account. Those are all accounts that were in the attention set but were removed. The AttentionSetInfo is the latest and most recent removal of the account from the attention set.
`assignee`	optional	The assignee of the change as an AccountInfo entity.
`hashtags`	optional	List of hashtags that are set on the change.
`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`).
`created`		The timestamp of when the change was created.
`updated`		The timestamp of when the change was last updated.
`submitted`	only set for merged changes	The timestamp of when the change was submitted.
`submitter`	only set for merged changes	The user who submitted the change, as an AccountInfo entity.
`starred`	not set if `false`	Whether the calling user has starred this change with the default label.
`stars`	optional	A list of star labels that are applied by the calling user to this change. The labels are lexicographically sorted.
`reviewed`	not set if `false`	Whether the change was reviewed by the calling user. Only set if reviewed is requested.
`submit_type`	optional	The submit type of the change. Not set for merged changes.
`mergeable`	optional	Whether the change is mergeable. Only set for open changes if change.mergeabilityComputationBehavior is `API_REF_UPDATED_AND_CHANGE_REINDEX`.
`submittable`	optional	Whether the change has been approved by the project submit rules. Only set if requested.
`insertions`		Number of inserted lines.
`deletions`		Number of deleted lines.
`total_comment_count`	optional	Total number of inline comments across all patch sets. Not set if the current change index doesn’t have the data.
`unresolved_comment_count`	optional	Number of unresolved inline comment threads across all patch sets. Not set if the current change index doesn’t have the data.
`_number`		The change number. (The underscore is just a relict of a prior attempt to deprecate the change number.)
`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.
`submit_records`		List of the SubmitRecordInfo containing the submit records for the change at the latest patchset.
`requirements`	optional	List of the requirements to be met before this change can be submitted. This field is deprecated in favour of `submit_requirements`.
`submit_requirements`	optional	List of the SubmitRequirementResultInfo containing the evaluated submit requirements for the change. Only set if `SUBMIT_REQUIREMENTS` is requested.
`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 labels or detailed labels are requested.
`reviewers`	optional	The reviewers as a map that maps a reviewer state to a list of AccountInfo entities. Possible reviewer states are `REVIEWER`, `CC` and `REMOVED`. `REVIEWER`: Users with at least one non-zero vote on the change. `CC`: Users that were added to the change, but have not voted. `REMOVED`: Users that were previously reviewers on the change, but have been removed. Only set if labels or detailed labels are requested.
`pending_reviewers`	optional	Updates to `reviewers` that have been made while the change was in the WIP state. Only present on WIP changes and only if there are pending reviewer updates to report. These are reviewers who have not yet been notified about being added to or removed from the change. Only set if labels or detailed labels are requested.
`reviewer_updates`	optional	Updates to reviewers set for the change as ReviewerUpdateInfo entities. Only set if reviewer updates 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.
`meta_rev_id`	optional	The SHA-1 of the NoteDb meta ref.
`tracking_ids`	optional	A list of TrackingIdInfo entities describing references to external tracking systems. Only set if tracking ids 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.
`is_private`	optional, not set if `false`	When present, change is marked as private.
`work_in_progress`	optional, not set if `false`	When present, change is marked as Work In Progress.
`has_review_started`	optional, not set if `false`	When present, change has been marked Ready at some point in time.
`revert_of`	optional	The change number of the change that this change reverts.
`submission_id`	optional	ID of the submission of this change. Only set if the status is `MERGED`. This ID is equal to the change number of the change that triggered the submission. If the change that triggered the submission also has a topic, it will be "<id>-<topic>" of the change that triggered the submission. The callers must not rely on the format of the submission ID.
`cherry_pick_of_change`	optional	The change number of the change that this change was cherry-picked from. Only set if the cherry-pick has been done through the Gerrit REST API (and not if a cherry-picked commit was pushed).
`cherry_pick_of_patch_set`	optional	The patchset number of the change that this change was cherry-picked from. Only set if the cherry-pick has been done through the Gerrit REST API (and not if a cherry-picked commit was pushed).
`contains_git_conflicts`	optional, not set if `false`	Whether the change contains conflicts. If `true`, some of the file contents of the change contain git conflict markers to indicate the conflicts. Only set if this change info is returned in response to a request that creates a new change or patch set and conflicts are allowed. In particular this field is only populated if the change info is returned by one of the following REST endpoints: Create Change, Create Merge Patch Set For Change, Cherry Pick Revision, Cherry Pick Commit

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.

attention_set

optional

The map that maps account IDs to AttentionSetInfo of that account. Those are all accounts that are currently in the attention set.

removed_from_attention_set

optional

The map that maps account IDs to AttentionSetInfo of that account. Those are all accounts that were in the attention set but were removed. The AttentionSetInfo is the latest and most recent removal of the account from the attention set.

assignee

optional

The assignee of the change as an AccountInfo entity.

hashtags

optional

List of hashtags that are set on the change.

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

created

The timestamp of when the change was created.

updated

The timestamp of when the change was last updated.

submitted

only set for merged changes

The timestamp of when the change was submitted.

submitter

only set for merged changes

The user who submitted the change, as an AccountInfo entity.

starred

not set if false

Whether the calling user has starred this change with the default label.

stars

optional

A list of star labels that are applied by the calling user to this change. The labels are lexicographically sorted.

reviewed

not set if false

Whether the change was reviewed by the calling user. Only set if reviewed is requested.

submit_type

optional

The submit type of the change.
Not set for merged changes.

mergeable

optional

Whether the change is mergeable.
Only set for open changes if change.mergeabilityComputationBehavior is API_REF_UPDATED_AND_CHANGE_REINDEX.

submittable

optional

Whether the change has been approved by the project submit rules.
Only set if requested.

insertions

Number of inserted lines.

deletions

Number of deleted lines.

total_comment_count

optional

Total number of inline comments across all patch sets. Not set if the current change index doesn’t have the data.

unresolved_comment_count

optional

Number of unresolved inline comment threads across all patch sets. Not set if the current change index doesn’t have the data.

_number

The change number. (The underscore is just a relict of a prior attempt to deprecate the change number.)

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.

submit_records

List of the SubmitRecordInfo containing the submit records for the change at the latest patchset.

requirements

optional

List of the requirements to be met before this change can be submitted. This field is deprecated in favour of submit_requirements.

submit_requirements

optional

List of the SubmitRequirementResultInfo containing the evaluated submit requirements for the change. Only set if SUBMIT_REQUIREMENTS is requested.

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 labels or detailed labels are requested.

reviewers

optional

The reviewers as a map that maps a reviewer state to a list of AccountInfo entities. Possible reviewer states are REVIEWER, CC and REMOVED.
REVIEWER: Users with at least one non-zero vote on the change.
CC: Users that were added to the change, but have not voted.
REMOVED: Users that were previously reviewers on the change, but have been removed.
Only set if labels or detailed labels are requested.

pending_reviewers

optional

Updates to reviewers that have been made while the change was in the WIP state. Only present on WIP changes and only if there are pending reviewer updates to report. These are reviewers who have not yet been notified about being added to or removed from the change.
Only set if labels or detailed labels are requested.

reviewer_updates

optional

Updates to reviewers set for the change as ReviewerUpdateInfo entities. Only set if reviewer updates 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.

meta_rev_id

optional

The SHA-1 of the NoteDb meta ref.

tracking_ids

optional

A list of TrackingIdInfo entities describing references to external tracking systems. Only set if tracking ids 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.

is_private

optional, not set if false

When present, change is marked as private.

work_in_progress

optional, not set if false

When present, change is marked as Work In Progress.

has_review_started

optional, not set if false

When present, change has been marked Ready at some point in time.

revert_of

optional

The change number of the change that this change reverts.

submission_id

optional

ID of the submission of this change. Only set if the status is MERGED. This ID is equal to the change number of the change that triggered the submission. If the change that triggered the submission also has a topic, it will be "<id>-<topic>" of the change that triggered the submission. The callers must not rely on the format of the submission ID.

cherry_pick_of_change

optional

The change number of the change that this change was cherry-picked from. Only set if the cherry-pick has been done through the Gerrit REST API (and not if a cherry-picked commit was pushed).

cherry_pick_of_patch_set

optional

The patchset number of the change that this change was cherry-picked from. Only set if the cherry-pick has been done through the Gerrit REST API (and not if a cherry-picked commit was pushed).

contains_git_conflicts

optional, not set if false

Whether the change contains conflicts.
If true, some of the file contents of the change contain git conflict markers to indicate the conflicts.
Only set if this change info is returned in response to a request that creates a new change or patch set and conflicts are allowed. In particular this field is only populated if the change info is returned by one of the following REST endpoints: Create Change, Create Merge Patch Set For Change, Cherry Pick Revision, Cherry Pick Commit

ChangeInput

The ChangeInput entity contains information about creating a new change.

Field Name Description

Field Name		Description
`project`		The name of the project.
`branch`		The name of the target branch. The `refs/heads/` prefix is omitted.
`subject`		The commit message of the change. Comment lines (beginning with `#`) will be removed. If the commit message contains a Change-Id (as a "Change-Id: I…" footer) that Change-Id will be used for the newly created changed. If a change with this Change-Id already exists for same repository and branch, the request is rejected since Change-Ids must be unique per repository and branch. If the commit message doesn’t contain a Change-Id, a newly generated Change-Id is automatically inserted into the commit message.
`topic`	optional	The topic to which this change belongs. Topic can’t contain quotation marks.
`status`	optional, default to `NEW`	The status of the change (only `NEW` accepted here).
`is_private`	optional, default to `false`	Whether the new change should be marked as private.
`work_in_progress`	optional, default to `false`	Whether the new change should be set to work in progress.
`base_change`	optional	A {change-id} that identifies the base change for a create change operation. Mutually exclusive with `base_commit`.
`base_commit`	optional	A 40-digit hex SHA-1 of the commit which will be the parent commit of the newly created change. If set, it must be a merged commit on the destination branch. Mutually exclusive with `base_change`.
`new_branch`	optional, default to `false`	Allow creating a new branch when set to `true`. Using this option is only possible for non-merge commits (if the `merge` field is not set).
`validation_options`	optional	Map with key-value pairs that are forwarded as options to the commit validation listeners (e.g. can be used to skip certain validations). Which validation options are supported depends on the installed commit validation listeners. Gerrit core doesn’t support any validation options, but commit validation listeners that are implemented in plugins may. Please refer to the documentation of the installed plugins to learn whether they support validation options. Unknown validation options are silently ignored.
`merge`	optional	The detail of a merge commit as a MergeInput entity. If set, the target branch (see `branch` field) must exist (it is not possible to create it automatically by setting the `new_branch` field to `true`.
`author`	optional	An AccountInput entity that will set the author of the commit to create. The author must be specified as name/email combination. The caller needs "Forge Author" permission when using this field. This field does not affect the owner of the change, which will continue to use the identity of the caller.
`notify`	optional	Notify handling that defines to whom email notifications should be sent after the change is created. Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. If not set, the default is `ALL`.
`notify_details`	optional	Additional information about whom to notify about the change creation as a map of recipient type to NotifyInfo entity.

project

The name of the project.

branch

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

subject

The commit message of the change. Comment lines (beginning with #) will be removed. If the commit message contains a Change-Id (as a "Change-Id: I…" footer) that Change-Id will be used for the newly created changed. If a change with this Change-Id already exists for same repository and branch, the request is rejected since Change-Ids must be unique per repository and branch. If the commit message doesn’t contain a Change-Id, a newly generated Change-Id is automatically inserted into the commit message.

topic

optional

The topic to which this change belongs. Topic can’t contain quotation marks.

status

optional, default to NEW

The status of the change (only NEW accepted here).

is_private

optional, default to false

Whether the new change should be marked as private.

work_in_progress

optional, default to false

Whether the new change should be set to work in progress.

base_change

optional

A {change-id} that identifies the base change for a create change operation. Mutually exclusive with base_commit.

base_commit

optional

A 40-digit hex SHA-1 of the commit which will be the parent commit of the newly created change. If set, it must be a merged commit on the destination branch. Mutually exclusive with base_change.

new_branch

optional, default to false

Allow creating a new branch when set to true. Using this option is only possible for non-merge commits (if the merge field is not set).

validation_options

optional

Map with key-value pairs that are forwarded as options to the commit validation listeners (e.g. can be used to skip certain validations). Which validation options are supported depends on the installed commit validation listeners. Gerrit core doesn’t support any validation options, but commit validation listeners that are implemented in plugins may. Please refer to the documentation of the installed plugins to learn whether they support validation options. Unknown validation options are silently ignored.

merge

optional

The detail of a merge commit as a MergeInput entity. If set, the target branch (see branch field) must exist (it is not possible to create it automatically by setting the new_branch field to true.

author

optional

An AccountInput entity that will set the author of the commit to create. The author must be specified as name/email combination. The caller needs "Forge Author" permission when using this field. This field does not affect the owner of the change, which will continue to use the identity of the caller.

notify

optional

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

notify_details

optional

Additional information about whom to notify about the change creation as a map of recipient type to NotifyInfo entity.

ChangeMessageInfo

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

Field Name Description

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.
`real_author`	optional	Real author of the message as an AccountInfo entity. Set if the message was posted on behalf of another user.
`date`		The timestamp this message was posted.
`message`		The text left by the user or Gerrit system. Accounts are served as account IDs inlined in the text as `<GERRIT_ACCOUNT_18419>`. All accounts, used in message, can be found in `accountsInMessage` field.
`accountsInMessage`		Accounts, used in `message`.
`tag`	optional	Value of the `tag` field from ReviewInput set while posting the review. Votes/comments that contain `tag` with 'autogenerated:' prefix can be filtered out in the web UI. NOTE: To apply different tags on different votes/comments multiple invocations of the REST call are required.
`_revision_number`	optional	Which patchset (if any) generated this message.

id

The ID of the message.

author

optional

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

real_author

optional

Real author of the message as an AccountInfo entity.
Set if the message was posted on behalf of another user.

date

The timestamp this message was posted.

message

The text left by the user or Gerrit system. Accounts are served as account IDs inlined in the text as <GERRIT_ACCOUNT_18419>. All accounts, used in message, can be found in accountsInMessage field.

accountsInMessage

Accounts, used in message.

tag

optional

_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

Field Name		Description
`message`	optional	Commit message for the cherry-pick change. If not set, the commit message of the cherry-picked commit is used.
`destination`		Destination branch
`base`	optional	40-hex digit SHA-1 of the commit which will be the parent commit of the newly created change. If set, it must be a merged commit or a change revision on the destination branch.
`parent`	optional, defaults to 1	Number of the parent relative to which the cherry-pick should be considered.
`notify`	optional	Notify handling that defines to whom email notifications should be sent after the cherry-pick. Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. If not set, the default is `ALL`.
`notify_details`	optional	Additional information about whom to notify about the update as a map of recipient type to NotifyInfo entity.
`keep_reviewers`	optional, defaults to false	If `true`, carries reviewers and ccs over from original change to newly created one.
`allow_conflicts`	optional, defaults to false	If `true`, the cherry-pick uses content merge and succeeds also if there are conflicts. If there are conflicts the file contents of the created change contain git conflict markers to indicate the conflicts. Callers can find out if there were conflicts by checking the `contains_git_conflicts` field in the ChangeInfo. If there are conflicts the cherry-pick change is marked as work-in-progress.
`topic`	optional	The topic of the created cherry-picked change. If not set, the default depends on the source. If the source is a change with a topic, the resulting topic of the cherry-picked change will be {source_change_topic}-{destination_branch}. Otherwise, if the source change has no topic, or the source is a commit, the created change will have no topic. If the change already exists, the topic will not change if not set. If set, the topic will be overridden.
`allow_empty`	optional, defaults to false	If `true`, the cherry-pick succeeds also if the created commit will be empty. If `false`, a cherry-pick that would create an empty commit fails without creating the commit.
`validation_options`	optional	Map with key-value pairs that are forwarded as options to the commit validation listeners (e.g. can be used to skip certain validations). Which validation options are supported depends on the installed commit validation listeners. Gerrit core doesn’t support any validation options, but commit validation listeners that are implemented in plugins may. Please refer to the documentation of the installed plugins to learn whether they support validation options. Unknown validation options are silently ignored.

message

optional

Commit message for the cherry-pick change. If not set, the commit message of the cherry-picked commit is used.

destination

Destination branch

base

optional

40-hex digit SHA-1 of the commit which will be the parent commit of the newly created change. If set, it must be a merged commit or a change revision on the destination branch.

parent

optional, defaults to 1

Number of the parent relative to which the cherry-pick should be considered.

notify

optional

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

notify_details

optional

Additional information about whom to notify about the update as a map of recipient type to NotifyInfo entity.

keep_reviewers

optional, defaults to false

If true, carries reviewers and ccs over from original change to newly created one.

allow_conflicts

optional, defaults to false

If true, the cherry-pick uses content merge and succeeds also if there are conflicts. If there are conflicts the file contents of the created change contain git conflict markers to indicate the conflicts. Callers can find out if there were conflicts by checking the contains_git_conflicts field in the ChangeInfo. If there are conflicts the cherry-pick change is marked as work-in-progress.

topic

optional

The topic of the created cherry-picked change. If not set, the default depends on the source. If the source is a change with a topic, the resulting topic of the cherry-picked change will be {source_change_topic}-{destination_branch}. Otherwise, if the source change has no topic, or the source is a commit, the created change will have no topic. If the change already exists, the topic will not change if not set. If set, the topic will be overridden.

allow_empty

optional, defaults to false

If true, the cherry-pick succeeds also if the created commit will be empty. If false, a cherry-pick that would create an empty commit fails without creating the commit.

validation_options

optional

CommentInfo

The CommentInfo entity contains information about an inline comment.

Field Name Description

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 file path 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`.
`parent`	optional	The 1-based parent number. Used only for merge commits when `side == PARENT`. When not set the comment is for the auto-merge tree.
`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.
`tag`	optional	Value of the `tag` field from ReviewInput set while posting the review. NOTE: To apply different tags on different votes/comments multiple invocations of the REST call are required.
`unresolved`	optional	Whether or not the comment must be addressed by the user. The state of resolution of a comment thread is stored in the last comment in that thread chronologically.
`change_message_id`	optional	Available with the list change comments endpoint. Contains the id of the change message that this comment is linked to.
`commit_id`	optional	Hex commit SHA-1 (40 characters string) of the commit of the patchset to which this comment applies.
`context_lines`	optional	A list of ContextLine containing the lines of the source file where the comment was written. Available only if the "enable-context" parameter (see List Change Comments) is set.
`source_content_type`	optional	Mime type of the file where the comment is written. Available only if the "enable-context" parameter (see List Change Comments) is set.

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 file path 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.

parent

optional

The 1-based parent number. Used only for merge commits when side == PARENT. When not set the comment is for the auto-merge tree.

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.

tag

optional

Value of the tag field from ReviewInput set while posting the review. NOTE: To apply different tags on different votes/comments multiple invocations of the REST call are required.

unresolved

optional

Whether or not the comment must be addressed by the user. The state of resolution of a comment thread is stored in the last comment in that thread chronologically.

change_message_id

optional

Available with the list change comments endpoint. Contains the id of the change message that this comment is linked to.

commit_id

optional

Hex commit SHA-1 (40 characters string) of the commit of the patchset to which this comment applies.

context_lines

optional

A list of ContextLine containing the lines of the source file where the comment was written. Available only if the "enable-context" parameter (see List Change Comments) is set.

source_content_type

optional

Mime type of the file where the comment is written. Available only if the "enable-context" parameter (see List Change Comments) is set.

CommentInput

The CommentInput entity contains information for creating an inline comment.

Field Name Description

Field Name		Description
`id`	optional	The URL encoded UUID of the comment if an existing draft comment should be updated.
`path`	optional	The file path 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.
`tag`	optional, drafts only	Value of the `tag` field. Only allowed on draft comment inputs; for published comments, use the `tag` field in ReviewInput. Votes/comments that contain `tag` with 'autogenerated:' prefix can be filtered out in the web UI.
`unresolved`	optional	Whether or not the comment must be addressed by the user. This value will default to false if the comment is an orphan, or the value of the `in_reply_to` comment if it is supplied.

id

optional

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

path

optional

The file path 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.

tag

optional, drafts only

Value of the tag field. Only allowed on draft comment
inputs; for published comments, use the tag field in
ReviewInput. Votes/comments that contain tag with 'autogenerated:' prefix can be filtered out in the web UI.

unresolved

optional

Whether or not the comment must be addressed by the user. This value will default to false if the comment is an orphan, or the value of the in_reply_to comment if it is supplied.

CommentRange

The CommentRange entity describes the range of an inline comment.

The comment range is a range from the start position, specified by start_line and start_character, to the end position, specified by end_line and end_character. The start position is inclusive and the end position is exclusive.

So, a range over part of a line will have start_line equal to end_line; however a range with end_line set to 5 and end_character equal to 0 will not include any characters on line 5,

Field Name Description

Field Name		Description
`start_line`		The start line number of the range. (1-based)
`start_character`		The character position in the start line. (0-based)
`end_line`		The end line number of the range. (1-based)
`end_character`		The character position in the end line. (0-based)

start_line

The start line number of the range. (1-based)

start_character

The character position in the start line. (0-based)

end_line

The end line number of the range. (1-based)

end_character

The character position in the end line. (0-based)

ContextLine

The ContextLine entity contains the line number and line text of a single line of the source file content.

Field Name Description

Field Name	Description
`line_number`	The line number of the source line.
`context_line`	String containing the line text.

line_number

The line number of the source line.

context_line

String containing the line text.

CommitInfo

The CommitInfo entity contains information about a commit.

Field Name Description

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 patch set in external sites as a list of WebLinkInfo entities.
`resolve_conflicts_web_links`	optional	Links to the commit in external sites for resolving conflicts as a list of WebLinkInfo entities.

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 patch set in external sites as a list of WebLinkInfo entities.

resolve_conflicts_web_links

optional

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

CommitMessageInput

The CommitMessageInput entity contains information for changing the commit message of a change.

Field Name Description

Field Name		Description
`message`		New commit message.
`notify`	optional	Notify handling that defines to whom email notifications should be sent after the commit message was updated. Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. If not set, the default is `OWNER` for WIP changes and `ALL` otherwise.
`notify_details`	optional	Additional information about whom to notify about the update as a map of recipient type to NotifyInfo entity.

message

New commit message.

notify

optional

Notify handling that defines to whom email notifications should be sent after the commit message was updated.
Allowed values are NONE, OWNER, OWNER_REVIEWERS and ALL.
If not set, the default is OWNER for WIP changes and ALL otherwise.

notify_details

optional

Additional information about whom to notify about the update as a map of recipient type to NotifyInfo entity.

DeleteChangeMessageInput

The DeleteChangeMessageInput entity contains the options for deleting a change message.

Field Name Description

Field Name		Description
`reason`	optional	The reason why the change message should be deleted. If set, the change message will be replaced with "Change message removed by: `name`\nReason: reason`", or just "Change message removed by: `name." if not set.

reason

optional

The reason why the change message should be deleted.
If set, the change message will be replaced with "Change message removed by: name\nReason: reason`", or just "Change message removed by: `name." if not set.

DeleteCommentInput

The DeleteCommentInput entity contains the option for deleting a comment.

Field Name Description

Field Name		Description
`reason`	optional	The reason why the comment should be deleted. If set, the comment’s message will be replaced with "Comment removed by: `name`; Reason: reason`", or just "Comment removed by: `name." if not set.

reason

optional

The reason why the comment should be deleted.
If set, the comment’s message will be replaced with "Comment removed by: name; Reason: reason`", or just "Comment removed by: `name." if not set.

DeleteReviewerInput

The DeleteReviewerInput entity contains options for the deletion of a reviewer.

Field Name Description

Field Name		Description
`notify`	optional	Notify handling that defines to whom email notifications should be sent after the reviewer is deleted. Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. If not set, the default is `ALL`.
`notify_details`	optional	Additional information about whom to notify about the update as a map of recipient type to NotifyInfo entity.

notify

optional

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

notify_details

optional

Additional information about whom to notify about the update as a map of recipient type to NotifyInfo entity.

DeleteVoteInput

The DeleteVoteInput entity contains options for the deletion of a vote.

Field Name Description

Field Name		Description
`label`	optional	The label for which the vote should be deleted. If set, must match the label in the URL.
`notify`	optional	Notify handling that defines to whom email notifications should be sent after the vote is deleted. Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. If not set, the default is `ALL`.
`notify_details`	optional	Additional information about whom to notify about the update as a map of recipient type to NotifyInfo entity.
`ignore_automatic_attention_set_rules`	optional	If set to true, ignore all automatic attention set rules described in the attention set. When not set, the default is false.

label

optional

The label for which the vote should be deleted.
If set, must match the label in the URL.

notify

optional

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

notify_details

optional

Additional information about whom to notify about the update as a map of recipient type to NotifyInfo entity.

ignore_automatic_attention_set_rules

optional

If set to true, ignore all automatic attention set rules described in the attention set. When not set, the default is false.

DescriptionInput

The DescriptionInput entity contains information for setting a description.

Field Name Description

Field Name	Description
`description`	The description text.

description

The description text.

DiffContent

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

Field Name Description

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 when the `intraline` parameter is set and the DiffContent is a replace, i.e. both `a` and `b` are present	Text sections deleted from side A as a DiffIntralineInfo entity.
`edit_b`	only present when the `intraline` parameter is set and the DiffContent is a replace, i.e. both `a` and `b` are present	Text sections inserted in side B as a DiffIntralineInfo entity.
`due_to_rebase`	not set if `false`	Indicates whether this entry was introduced by a rebase.
`due_to_move`	not set if `false`	Indicates whether this entry was introduced by a move operation.
`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.

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 when the intraline parameter is set and the DiffContent is a replace, i.e. both a and b are present

Text sections deleted from side A as a DiffIntralineInfo entity.

edit_b

only present when the intraline parameter is set and the DiffContent is a replace, i.e. both a and b are present

Text sections inserted in side B as a DiffIntralineInfo entity.

due_to_rebase

not set if false

Indicates whether this entry was introduced by a rebase.

due_to_move

not set if false

Indicates whether this entry was introduced by a move operation.

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

Field Name		Description
`name`		The name of the file.
`content_type`		The content type of the file. For the commit message and merge list the value is `text/x-gerrit-commit-message` and `text/x-gerrit-merge-list` respectively. For git links the value is `x-git/gitlink`. For symlinks the value is `x-git/symlink`. For regular files the value is the file mime type (e.g. `text/x-java`, `text/x-c++src`, etc…).
`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.

name

The name of the file.

content_type

The content type of the file. For the commit message and merge list the value is text/x-gerrit-commit-message and text/x-gerrit-merge-list respectively. For git links the value is x-git/gitlink. For symlinks the value is x-git/symlink. For regular files the value is the file mime type (e.g. text/x-java, text/x-c++src, etc…).

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

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.
`edit_web_links`	optional	Links to edit the file in external sites as a list of WebLinkInfo entries.
`binary`	not set if `false`	Whether the file is binary.

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.

edit_web_links

optional

Links to edit the file in external sites as a list of WebLinkInfo 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, edit 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 edit 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. If the list is empty, the entire DiffContent should be considered as unedited.

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.

DiffWebLinkInfo

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

Field Name Description

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.

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

Field Name		Description
`web_links`	optional	Links to the diff info in external sites as a list of WebLinkInfo entities.

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

Field Name		Description
`commit`		The commit of change edit as CommitInfo entity.
`base_patch_set_number`		The patch set number of the patch set the change edit is based on.
`base_revision`		The revision of the patch set the change edit is based on.
`ref`		The ref of the change edit.
`fetch`	optional	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.

commit

The commit of change edit as CommitInfo entity.

base_patch_set_number

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

base_revision

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

ref

The ref of the change edit.

fetch

optional

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

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.

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

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. An empty last line is not included in the count and hence this number can differ by one from details provided in DiffInfo.
`lines_deleted`	optional	Number of deleted lines. Not set for binary files or if no lines were deleted. An empty last line is not included in the count and hence this number can differ by one from details provided in DiffInfo.
`size_delta`		Number of bytes by which the file size increased/decreased.
`size`		File size in bytes.

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.
An empty last line is not included in the count and hence this number can differ by one from details provided in DiffInfo.

lines_deleted

optional

Number of deleted lines.
Not set for binary files or if no lines were deleted.
An empty last line is not included in the count and hence this number can differ by one from details provided in DiffInfo.

size_delta

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

size

File size in bytes.

FixInput

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

Field Name Description

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.

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.

FixSuggestionInfo

The FixSuggestionInfo entity represents a suggested fix.

Field Name Description

Field Name		Description
`fix_id`	generated, don’t set	The UUID of the suggested fix. It will be generated automatically and hence will be ignored if it’s set for input objects.
`description`		A description of the suggested fix.
`replacements`		A list of FixReplacementInfo entities indicating how the content of one or several files should be modified. Within a file, they should refer to non-overlapping regions.

fix_id

generated, don’t set

The UUID of the suggested fix. It will be generated automatically and hence will be ignored if it’s set for input objects.

description

A description of the suggested fix.

replacements

A list of FixReplacementInfo entities indicating how the content of one or several files should be modified. Within a file, they should refer to non-overlapping regions.

FixReplacementInfo

The FixReplacementInfo entity describes how the content of a file should be replaced by another content.

Field Name Description

Field Name	Description
`path`	The path of the file which should be modified. Any file in the repository may be modified. The commit message can be modified via the magic file `/COMMIT_MSG` though only the part below the generated header of that magic file can be modified. References to the header lines will result in errors when the fix is applied.
`range`	A CommentRange indicating which content of the file should be replaced. Lines in the file are assumed to be separated by the line feed character.
`replacement`	The content which should be used instead of the current one.

path

The path of the file which should be modified. Any file in the repository may be modified. The commit message can be modified via the magic file /COMMIT_MSG though only the part below the generated header of that magic file can be modified. References to the header lines will result in errors when the fix is applied.

range

A CommentRange indicating which content of the file should be replaced. Lines in the file are assumed to be separated by the line feed character.

replacement

The content which should be used instead of the current one.

GitPersonInfo

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

Field Name Description

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.

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

Field Name	Description
`id`	The UUID of the group.
`name`	The name of the group.

id

The UUID of the group.

name

The name of the group.

HashtagsInput

The HashtagsInput entity contains information about hashtags to add to, and/or remove from, a change.

Field Name Description

Field Name		Description
`add`	optional	The list of hashtags to be added to the change.
`remove`	optional	The list of hashtags to be removed from the change.

add

optional

The list of hashtags to be added to the change.

remove

optional

The list of hashtags to be removed from the change.

IncludedInInfo

The IncludedInInfo entity contains information about the branches a change was merged into and tags it was tagged with. The branch or tag must have 'refs/head/' or 'refs/tags/' prefix respectively.

Field Name Description

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.

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.

Using LABELS will skip the all.permitted_voting_range attribute.
Using DETAILED_LABELS will include the all.permitted_voting_range attribute.

Field Name Description

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.
`description`	optional	The description of the label.
`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.
votes	optional	A list of integers containing the vote values applied to this label at the latest patchset.
`all`	optional	List of all approvals for this label as a list of ApprovalInfo entities. Items in this list may not represent actual votes cast by users; if a user votes on any label, a corresponding ApprovalInfo will appear in this list for all labels. The `permitted_voting_range` attribute is only set if the `DETAILED_LABELS` option is requested.
`values`	optional	A map of all values that are allowed for this label. The map maps the values (“-2”, “-1”, " `0`", “+1”, “+2”) to the value descriptions.

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.

description

optional

The description of the label.

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.

votes

optional

A list of integers containing the vote values applied to this label at the latest patchset.

all

optional

List of all approvals for this label as a list of ApprovalInfo entities. Items in this list may not represent actual votes cast by users; if a user votes on any label, a corresponding ApprovalInfo will appear in this list for all labels.
The permitted_voting_range attribute is only set if the DETAILED_LABELS option is requested.

values

optional

A map of all values that are allowed for this label. The map maps the values (“-2”, “-1”, " `0`", “+1”, “+2”) to the value descriptions.

MergeableInfo

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

Field Name Description

Field Name		Description
`submit_type`		Submit type used for this change, can be `MERGE_IF_NECESSARY`, `FAST_FORWARD_ONLY`, `REBASE_IF_NECESSARY`, `REBASE_ALWAYS`, `MERGE_ALWAYS` or `CHERRY_PICK`.
`strategy`	optional	The strategy of the merge, can be `recursive`, `resolve`, `simple-two-way-in-core`, `ours` or `theirs`.
`mergeable`		`true` if this change is cleanly mergeable, `false` otherwise
`commit_merged`	optional	`true` if this change is already merged, `false` otherwise
`content_merged`	optional	`true` if the content of this change is already merged, `false` otherwise
`conflicts`	optional	A list of paths with conflicts
`mergeable_into`	optional	A list of other branch names where this change could merge cleanly

submit_type

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

strategy

optional

The strategy of the merge, can be recursive, resolve, simple-two-way-in-core, ours or theirs.

mergeable

true if this change is cleanly mergeable, false otherwise

commit_merged

optional

true if this change is already merged, false otherwise

content_merged

optional

true if the content of this change is already merged, false otherwise

conflicts

optional

A list of paths with conflicts

mergeable_into

optional

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

MergeInput

The MergeInput entity contains information about the merge

Field Name Description

Field Name		Description
`source`		The source to merge from, e.g. a complete or abbreviated commit SHA-1, a complete reference name, a short reference name under `refs/heads`, `refs/tags`, or `refs/remotes` namespace, etc.
`source_branch`	optional	A branch from which `source` is reachable. If specified, `source` is checked for visibility and reachability against only this branch. This speeds up the operation, especially for large repos with many branches.
`strategy`	optional	The strategy of the merge, can be `recursive`, `resolve`, `simple-two-way-in-core`, `ours` or `theirs`, default will use project settings.
`allow_conflicts`	optional, defaults to false	If `true`, creating the merge succeeds also if there are conflicts. If there are conflicts the file contents of the created change contain git conflict markers to indicate the conflicts. Callers can find out whether there were conflicts by checking the `contains_git_conflicts` field in the ChangeInfo. If there are conflicts the change is marked as work-in-progress. This option is not supported for all merge strategies (e.g. it’s supported for `recursive` and `resolve`, but not for `simple-two-way-in-core`).

source

The source to merge from, e.g. a complete or abbreviated commit SHA-1, a complete reference name, a short reference name under refs/heads, refs/tags, or refs/remotes namespace, etc.

source_branch

optional

A branch from which source is reachable. If specified, source is checked for visibility and reachability against only this branch. This speeds up the operation, especially for large repos with many branches.

strategy

optional

The strategy of the merge, can be recursive, resolve, simple-two-way-in-core, ours or theirs, default will use project settings.

allow_conflicts

optional, defaults to false

If true, creating the merge succeeds also if there are conflicts.
If there are conflicts the file contents of the created change contain git conflict markers to indicate the conflicts.
Callers can find out whether there were conflicts by checking the contains_git_conflicts field in the ChangeInfo.
If there are conflicts the change is marked as work-in-progress.
This option is not supported for all merge strategies (e.g. it’s supported for recursive and resolve, but not for simple-two-way-in-core).

MergePatchSetInput

The MergePatchSetInput entity contains information about updating a new change by creating a new merge commit.

Field Name Description

subject

optional

The new subject for the change, if not specified, will reuse the current patch set’s subject

inherit_parent

optional, default to false

Use the current patch set’s first parent as the merge tip when set to true.

base_change

optional

A {change-id} that identifies a change. When inherit_parent is false, the merge tip will be the current patch set of the base_change if it’s set. Otherwise, the current branch tip of the destination branch will be used.

merge

The detail of the source commit for merge as a MergeInput entity.

author

optional

MoveInput

The MoveInput entity contains information for moving a change to a new branch.

Field Name Description

destination_branch

Destination branch

message

optional

A message to be posted in this change’s comments

keep_all_votes

optional, defaults to false

By default, only veto votes that are blocking the change from submission are moved to the destination branch. Using this option is only allowed for administrators, because it can affect the submission behaviour of the change (depending on the label access configuration and submissions rules).

NotifyInfo

The NotifyInfo entity contains detailed information about who should be notified about an update. These notifications are sent out even if a notify option in the request input disables normal notifications. NotifyInfo entities are normally contained in a notify_details map in the request input where the key is the recipient type.

Field Name Description

accounts

optional

A list of account IDs that identify the accounts that should be should be notified.

PrivateInput

The PrivateInput entity contains information for changing the private flag on a change.

Field Name Description

message

optional

Message describing why the private flag was changed.

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.

PublishChangeEditInput

The PublishChangeEditInput entity contains options for the publishing of change edit.

Field Name Description

notify

optional

Notify handling that defines to whom email notifications should be sent after the change edit is published.
Allowed values are NONE and ALL.
If not set, the default is ALL.

notify_details

optional

Additional information about whom to notify about the update as a map of recipient type to NotifyInfo entity.

PureRevertInfo

The PureRevertInfo entity describes the result of a pure revert check.

Field Name Description

is_pure_revert

Outcome of the check as boolean.

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.

RangeInfo

The RangeInfo entity stores the coordinates of a range.

Field Name Description

start

First index.

end

Last index.

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 SHA-1 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.

allow_conflicts

optional, defaults to false

If true, the rebase also succeeds if there are conflicts.
If there are conflicts the file contents of the rebased patch set contain git conflict markers to indicate the conflicts.
Callers can find out whether there were conflicts by checking the contains_git_conflicts field in the returned ChangeInfo.
If there are conflicts the change is marked as work-in-progress.

validation_options

optional

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

Field Name Description

project

The project of the change or commit.

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

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.

Requirement

The Requirement entity contains information about a requirement relative to a change.

Field Name Description

status

Status of the requirement. Can be either OK, NOT_READY or RULE_ERROR.

fallback_text

A human readable reason

type

Alphanumerical (plus hyphens or underscores) string to identify what the requirement is and why it was triggered. Can be seen as a class: requirements sharing the same type were created for a similar reason, and the data structure will follow one set of rules.

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.

notify

optional

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

notify_details

optional

Additional information about whom to notify about the revert as a map of recipient type to NotifyInfo entity.

topic

optional

Name of the topic for the revert change. If not set, the default for Revert endpoint is the topic of the change being reverted, and the default for the RevertSubmission endpoint is revert-{submission_id}-{timestamp.now}. Topic can’t contain quotation marks.

work_in_progress

optional

When present, change is marked as Work In Progress. The notify input is used if it’s present, otherwise it will be overridden to OWNER.
If not set, the default is false.

RevertSubmissionInfo

The RevertSubmissionInfo entity describes the revert changes.

Field Name Description

revert_changes

A list of ChangeInfo that describes the revert changes. Each entity in that list is a revert change that was created in that revert submission.

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.

ReviewerUpdateInfo

The ReviewerUpdateInfo entity contains information about updates to change’s reviewers set.

Field Name Description

updated

Timestamp of the update.

updated_by

The account which modified state of the reviewer in question as AccountInfo entity.

reviewer

The reviewer account added or removed from the change as an AccountInfo entity.

state

The reviewer state, one of REVIEWER, CC or REMOVED.

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.

tag

optional

Apply this tag to the review comment message, votes, and inline comments. Tags with an 'autogenerated:' prefix may be used by CI or other automated systems to distinguish them from human reviews. If another message was posted on a newer patchset, but with the same tag, then the older message will be hidden in the UI. Suffixes starting with ~ are not considered, so autogenerated:my-ci-system~trigger and autogenerated:my-ci-system~result will be considered being the same tag with regards to the hiding rule.

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.

robot_comments

optional

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

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 PUBLISH, PUBLISH_ALL_REVISIONS and KEEP. All values except PUBLISH_ALL_REVISIONS operate only on drafts for a single revision.
Only KEEP is allowed when used in conjunction with on_behalf_of.
If not set, the default is KEEP. If on_behalf_of is set, then no other value besides KEEP is allowed.

draft_ids_to_publish

optional

List of draft IDs to be published. The draft IDs should belong to the current user and be valid. If drafts is set to PUBLISH, then draft IDs should contain drafts for the same revision that is requested for review. If drafts is set to KEEP, then draft_ids_to_publish will be ignored and no draft comments will be published.
If not set, the default is to publish all drafts according to the drafts field.

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.

notify_details

optional

Additional information about whom to notify about the update as a map of recipient type to NotifyInfo entity.

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.

reviewers

optional

A list of ReviewerInput representing reviewers that should be added/removed to/from the change.

ready

optional

If true, and if the change is work in progress, then start review. It is an error for both ready and work_in_progress to be true.

work_in_progress

optional

If true, mark the change as work in progress. It is an error for both ready and work_in_progress to be true.

add_to_attention_set

optional

list of AttentionSetInput entities to add to the attention set. Users that are not reviewers, ccs, owner, or uploader are silently ignored.

remove_from_attention_set

optional

list of AttentionSetInput entities to remove from the attention set.

ignore_automatic_attention_set_rules

optional

If set to true, ignore all automatic attention set rules described in the attention set. Updates in add_to_attention_set and remove_from_attention_set are not ignored.

ReviewResult

The ReviewResult entity contains information regarding the updates that were made to a review.

Field Name Description

labels

optional

Map of labels to values after the review was posted. Null if any reviewer additions were rejected.

reviewers

optional

Map of account or group identifier to ReviewerResult representing the outcome of adding/removing a reviewer. Absent if no reviewer additions were requested.

ready

optional

If true, the change was moved from WIP to ready for review as a result of this action. Not set if false.

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

_account_id

This field is inherited from AccountInfo but is optional here if an unregistered reviewer was added by email. See add-reviewer for details.

ReviewerInput

The ReviewerInput entity contains information for adding or removing reviewers to/from the change.

Field Name Description

reviewer

The ID of one account that should be added/removed as reviewer or the ID of one internal 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. External groups, such as LDAP groups, will be silently omitted from a set-review or add-reviewer call. A group can only be specified for adding reviewers, not for removing them.

state

optional

Add reviewer in this state. Possible reviewer states are REVIEWER, CC and REMOVED. If not given, defaults to REVIEWER.

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.

notify

optional

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

notify_details

optional

Additional information about whom to notify about the update as a map of recipient type to NotifyInfo entity.

ReviewerResult

The ReviewerResult entity describes the result of modifying reviewers of a change.

Field Name Description

input

Value of the reviewer field from ReviewerInput set while adding the reviewer.

reviewers

optional

The newly added reviewers as a list of ReviewerInfo entities.

ccs

optional

The newly CCed accounts as a list of AccountInfo entities. This field will only appear if the requested state for the reviewer was CC.

removed

optional

The newly removed accounts as a list of AccountInfo entities. This field will only appear if the requested state for the reviewer was REMOVED.

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.

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

kind

The change kind. Valid values are REWORK, TRIVIAL_REBASE, MERGE_FIRST_PARENT_UPDATE, NO_CODE_CHANGE, and NO_CHANGE.

_number

The patch set number, or edit if the patch set is an edit.

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.

commit_with_footers

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.

description

optional

The description of this patchset, as displayed in the patchset selector menu. May be null if no description is set.

RobotCommentInfo

The RobotCommentInfo entity contains information about a robot inline comment.

RobotCommentInfo has the same fields as CommentInfo except for the unresolved field which doesn’t exist for robot comments. In addition RobotCommentInfo has the following fields:

Field Name Description

robot_id

The ID of the robot that generated this comment.

robot_run_id

An ID of the run of the robot.

url

optional

URL to more information.

properties

optional

Robot specific properties as map that maps arbitrary keys to values.

fix_suggestions

optional

Suggested fixes for this robot comment as a list of FixSuggestionInfo entities.

RobotCommentInput

The RobotCommentInput entity contains information for creating an inline robot comment.

Field Name Description

path

The file path for which the inline comment should be added.

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

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.

robot_id

The ID of the robot that generated this comment.

robot_run_id

An ID of the run of the robot.

url

optional

URL to more information.

properties

optional

Robot specific properties as map that maps arbitrary keys to values.

fix_suggestions

optional

Suggested fixes for this robot comment as a list of FixSuggestionInfo entities.

RuleInput

The RuleInput entity contains information to test a Prolog rule.

Field Name Description

rule

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

filters

RUN if not set

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

SubmitInput

The SubmitInput entity contains information for submitting a change.

Field Name Description

on_behalf_of

optional

If set, submit the change on behalf of the given user. The value may take any format accepted by the accounts REST API. Using this option requires Submit (On Behalf Of) permission on the branch.

notify

optional

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

notify_details

optional

Additional information about whom to notify about the update as a map of recipient type to NotifyInfo entity.

SubmitRecord

The SubmitRecord entity describes results from a submit_rule. Fields in this entity roughly correspond to the fields set by LABELS in LabelInfo.

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.

SubmitRecordInfo

The SubmitRecordInfo entity describes results from a submit_rule.

Field Name Description

rule_name

The name of the submit rule that created this submit record. The submit rule is specified in the form of "$plugin~$rule" where $plugin is the plugin name and $rule is the name of the class that implemented the submit rule.

status

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

labels

optional

A list of labels, each containing the following fields.
* label: the label name.
* status: the label status: {OK, REJECT, MAY, NEED, IMPOSSIBLE}.
* appliedBy: the AccountInfo that applied the vote to the label.

requirements

optional

List of the requirements to be met before this change can be submitted.

error_message

optional

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

SubmitRequirementExpressionInfo

The SubmitRequirementExpressionInfo describes the result of evaluating a single submit requirement expression, for example label:code-review=+2.

Field Name Description

expression

optional

The submit requirement expression as a string, for example branch:refs/heads/foo and label:verified=+1.

fulfilled

True if the submit requirement is fulfilled for the change.

passing_atoms

optional

A list of passing atoms as strings. For the above expression, passing_atoms can contain ["branch:refs/heads/foo"] if the branch predicate is fulfilled for the change.

failing_atoms

optional

A list of failing atoms. This is similar to passing_atoms except that it contains the list of predicates that are not fulfilled for the change.

error_message

optional

If the submit requirement fails during evaluation, this string will contain an error message describing why it failed.

SubmitRequirementInput

The SubmitRequirementInput entity describes a submit requirement.

Field Name Description

name

The submit requirement name.

description

optional

Description of the submit requirement.

applicability_expression

optional

Query expression that can be evaluated on any change. If evaluated to true on a change, the submit requirement is then applicable for this change. If not specified, the submit requirement is applicable for all changes.

submittability_expression

Query expression that can be evaluated on any change. If evaluated to true on a change, the submit requirement is fulfilled and not blocking change submission.

override_expression

optional

Query expression that can be evaluated on any change. If evaluated to true on a change, the submit requirement is overridden and not blocking change submission.

allow_override_in_child_projects

optional

Whether this submit requirement can be overridden in child projects. Default is true.

SubmitRequirementResultInfo

The SubmitRequirementResultInfo describes the result of evaluating a submit requirement on a change.

Field Name Description

name

The submit requirement name.

description

optional

Description of the submit requirement.

status

Status describing the result of evaluating the submit requirement. The status is one of (SATISFIED, UNSATISFIED, OVERRIDDEN, NOT_APPLICABLE, ERROR, FORCED).

is_legacy

If true, this submit requirement result was created from a legacy SubmitRecord. Otherwise, it was created by evaluating a submit requirement.

applicability_expression_result

optional

A SubmitRequirementExpressionInfo containing the result of evaluating the applicability expression. Not set if the submit requirement did not define an applicability expression. Note that fields expression, passing_atoms and failing_atoms are always omitted for the applicability_expression_result.

submittability_expression_result

optional

A SubmitRequirementExpressionInfo containing the result of evaluating the submittability expression.
If the submit requirement does not apply, the expression is not evaluated and the field is not set.

override_expression_result

optional

A SubmitRequirementExpressionInfo containing the result of evaluating the override expression.
Not set if the submit requirement did not define an override expression or if it does not apply.

SubmittedTogetherInfo

The SubmittedTogetherInfo entity contains information about a collection of changes that would be submitted together.

Field Name Description

changes

A list of ChangeInfo entities representing the changes to be submitted together.

non_visible_changes

The number of changes to be submitted together that the current user cannot see. (This count includes changes that are visible to the current user when their reason for being submitted together involves changes the user cannot see.)

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.

Field Name Description

account

optional

An AccountInfo entity, if the suggestion is an account.

group

optional

A GroupBaseInfo entity, if the suggestion is a group.

count

The total number of accounts in the suggestion. This is 1 if account is present. If group is present, the total number of accounts that are members of the group is returned (this count includes members of nested groups).

confirm

optional

True if group is present and count is above the threshold where the confirmed flag must be passed to add the group as a reviewer.

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. Topic can’t contain quotation marks.

TrackingIdInfo

The TrackingIdInfo entity describes a reference to an external tracking system.

Field Name Description

system

The name of the external tracking system.

id

The tracking id.

VotingRangeInfo

The VotingRangeInfo entity describes the continuous voting range from min to max values.

Field Name Description

min

The minimum voting value.

max

The maximum voting value.

WebLinkInfo

The WebLinkInfo entity describes a link to an external site.

Field Name Description

name

The link name.

url

The link URL.

image_url

optional

URL to the icon of the link.

target

optional

The target window in which the web link should be opened.

WorkInProgressInput

The WorkInProgressInput entity contains additional information for a change set to WorkInProgress/ReadyForReview.

Field Name Description

message

optional

Message to be added as a review comment to the change being set WorkInProgress/ReadyForReview.

Part of Gerrit Code Review

Gerrit Code Review - /changes/ REST API

Change Endpoints

Create Change

Query Changes

Get Change

Get Meta Diff

Get Change Detail

Create Merge Patch Set For Change

Set Commit Message

Get Topic

Set Topic

Delete Topic

Get Assignee

Get Past Assignees

Set Assignee

Delete Assignee

Get Pure Revert

Abandon Change

Restore Change

Rebase Change

Move Change

Revert Change

Revert Submission

Submit Change

Changes Submitted Together

Delete Change

Get Included In

Index Change

List Change Comments

List Change Robot Comments

List Change Drafts

Check Change

Fix Change

Set Work-In-Progress

Set Ready-For-Review

Mark Private

Unmark Private

Ignore

Unignore

Get Hashtags

Set Hashtags

List Change Messages

Get Change Message

Delete Change Message

Check Submit Requirement

Change Edit Endpoints

Get Change Edit Details

Change file content in Change Edit

Restore file content or rename files in Change Edit

Change commit message in Change Edit

Delete file in Change Edit

Retrieve file content from Change Edit

Retrieve meta data of a file from Change Edit

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

Publish Change Edit

Rebase Change Edit

Delete Change Edit

Reviewer Endpoints

List Reviewers

Suggest Reviewers

Get Reviewer

Add Reviewer

Delete Reviewer

List Votes

Delete Vote

Revision Endpoints

Get Commit

Get Description

Set Description

Get Merge List

Get Revision Actions

Get Review

Get Related Changes

Set Review

Rebase Revision

Submit Revision

Get Patch

Get Mergeable

Get Submit Type

Test Submit Type