Gerrit Code Review - /accounts/ REST API

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

Endpoints

Get Account

GET /accounts/{account-id}

Returns an account as an AccountInfo entity.

Request

  GET /accounts/self HTTP/1.0

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

List Account Capabilities

GET /accounts/{account-id}/capabilities

Returns the global capabilities that are enabled for the specified user.

If the global capabilities for the calling user should be listed, self can be used as account-id. This can be used by UI tools to discover if administrative features are available to the caller, so they can hide (or show) relevant UI actions.

Request

  GET /accounts/self/capabilities HTTP/1.0

As response the global capabilities of the user are returned as a CapabilityInfo entity.

Response

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

  )]}'
  {
    "queryLimit": {
      "min": 0,
      "max": 500
    },
    "emailReviewers": true
  }

Administrator that has authenticated with digest authentication:

Request

  GET /a/accounts/self/capabilities HTTP/1.0
  Authorization: Digest username="admin", realm="Gerrit Code Review", nonce="...

Response

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

  )]}'
  {
    "administrateServer": true,
    "queryLimit": {
      "min": 0,
      "max": 500
    },
    "createAccount": true,
    "createGroup": true,
    "createProject": true,
    "emailReviewers": true,
    "killTask": true,
    "viewCaches": true,
    "flushCaches": true,
    "viewConnections": true,
    "viewQueue": true,
    "runGC": true,
    "startReplication": true
  }

Get your own capabilities

GET /accounts/self/capabilities HTTP/1.0

To filter the set of global capabilities the q parameter can be used. Filtering may decrease the response time by avoiding looking at every possible alternative for the caller.

Request

  GET /a/accounts/self/capabilities?q=createAccount&q=createGroup HTTP/1.0
  Authorization: Digest username="admin", realm="Gerrit Code Review", nonce="...

Response

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

  )]}'
  {
    "createAccount": true,
    "createGroup": true
  }

Check if you can create groups

GET /accounts/self/capabilities?q=createGroup HTTP/1.0

Check Account Capability

GET /accounts/{account-id}/capabilities/{capability-id}

Checks if a user has a certain global capability.

Request

  GET /a/accounts/self/capabilities/createGroup HTTP/1.0

If the user has the global capability the string ok is returned.

Response

  HTTP/1.1 200 OK

  ok

If the user doesn’t have the global capability the response is 404 Not Found.

Check if you can create groups

GET /accounts/self/capabilities/createGroup HTTP/1.0

List Groups

GET /accounts/{account-id}/groups/

Lists all groups that contain the specified user as a member.

Request

  GET /a/accounts/self/groups/ HTTP/1.0

As result a list of GroupInfo entries is returned.

Response

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

  )]}'
  [
    {
      "kind": "gerritcodereview#group",
      "id": "global%3AAnonymous-Users",
      "url": "#/admin/groups/uuid-global%3AAnonymous-Users",
      "options": {
      },
      "description": "Any user, signed-in or not",
      "group_id": 2,
      "owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389"
    },
    {
      "kind": "gerritcodereview#group",
      "id": "834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7",
      "url": "#/admin/groups/uuid-834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7",
      "options": {
        "visible_to_all": true,
      },
      "group_id": 6,
      "owner_id": "834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7"
    },
    {
      "kind": "gerritcodereview#group",
      "id": "global%3ARegistered-Users",
      "url": "#/admin/groups/uuid-global%3ARegistered-Users",
      "options": {
      },
      "description": "Any signed-in user",
      "group_id": 3,
      "owner_id": "6a1e70e1a88782771a91808c8af9bbb7a9871389"
    }
  ]

List all groups that contain you as a member

GET /accounts/self/groups/ HTTP/1.0

Get Avatar

GET /accounts/{account-id}/avatar

Retrieves the avatar image of the user.

With the size option (alias s) you can specify the preferred size in pixels (height and width).

Request

  GET /a/accounts/john.doe@example.com/avatar?s=20 HTTP/1.0

The response redirects to the URL of the avatar image.

Response

  HTTP/1.1 302 Found
  Location: https://profiles/avatar/john_doe.jpeg?s=20x20

Get Avatar Change URL

GET /accounts/{account-id}/avatar.change.url

Retrieves the URL where the user can change the avatar image.

Request

  GET /a/accounts/self/avatar.change.url HTTP/1.0

Response

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

  https://profiles/pictures/john.doe

Get Diff Preferences

GET /accounts/{account-id}/preferences.diff

Retrieves the diff preferences of a user.

Request

  GET /a/accounts/self/preferences.diff HTTP/1.0

As result the diff preferences of the user are returned as a DiffPreferencesInfo entity.

Response

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

  )]}'
  {
    "context": 10,
    "ignore_whitespace": "IGNORE_ALL_SPACE",
    "intraline_difference": true,
    "line_length": 100,
    "show_tabs": true,
    "show_whitespace_errors": true,
    "syntax_highlighting": true,
    "tab_size": 8
  }

Set Diff Preferences

PUT /accounts/{account-id}/preferences.diff

Sets the diff preferences of a user.

The new diff preferences must be provided in the request body as a DiffPreferencesInput entity.

Request

  GET /a/accounts/self/preferences.diff HTTP/1.0
  Content-Type: application/json;charset=UTF-8

  {
    "context": 10,
    "ignore_whitespace": "IGNORE_ALL_SPACE",
    "intraline_difference": true,
    "line_length": 100,
    "show_line_endings": true,
    "show_tabs": true,
    "show_whitespace_errors": true,
    "syntax_highlighting": true,
    "tab_size": 8
  }

As result the new diff preferences of the user are returned as a DiffPreferencesInfo entity.

Response

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

  )]}'
  {
    "context": 10,
    "ignore_whitespace": "IGNORE_ALL_SPACE",
    "intraline_difference": true,
    "line_length": 100,
    "show_line_endings": true,
    "show_tabs": true,
    "show_whitespace_errors": true,
    "syntax_highlighting": true,
    "tab_size": 8
  }

IDs

{account-id}

Identifier that uniquely identifies one account.

This can be:

a string of the format "Full Name <email@example.com>"
just the email address ("email@example")
a full name if it is unique ("Full Name")
an account ID ("18419")
a user name ("username")
self for the calling user

{capability-id}

Identifier of a global capability. Valid values are all field names of the CapabilityInfo entity.

JSON Entities

AccountInfo

The AccountInfo entity contains information about an account.

Field Name		Description
`_account_id`		The numeric ID of the account.
`name`	optional	The full name of the user. Only set if detailed account information is requested.
`email`	optional	The email address the user prefers to be contacted through. Only set if detailed account information is requested.

CapabilityInfo

The CapabilityInfo entity contains information about the global capabilities of a user.

Field Name		Description
`administrateServer`	not set if `false`	Whether the user has the Administrate Server capability.
`queryLimit`		The Query Limit of the user as QueryLimitInfo.
`createAccount`	not set if `false`	Whether the user has the Create Account capability.
`createGroup`	not set if `false`	Whether the user has the Create Group capability.
`createProject`	not set if `false`	Whether the user has the Create Project capability.
`emailReviewers`	not set if `false`	Whether the user has the Email Reviewers capability.
`killTask`	not set if `false`	Whether the user has the Kill Task capability.
`viewCaches`	not set if `false`	Whether the user has the View Caches capability.
`flushCaches`	not set if `false`	Whether the user has the Flush Caches capability.
`viewConnections`	not set if `false`	Whether the user has the View Connections capability.
`viewQueue`	not set if `false`	Whether the user has the View Queue capability.
`runGC`	not set if `false`	Whether the user has the Run Garbage Collection capability.
`startReplication`	not set if `false`	Whether the user has the Start Replication capability.

DiffPreferencesInfo

The DiffPreferencesInfo entity contains information about the diff preferences of a user.

Field Name		Description
`context`		The number of lines of context when viewing a patch.
`expand_all_comments`	not set if `false`	Whether all inline comments should be automatically expanded.
`ignore_whitespace`		Whether whitespace changes should be ignored and if yes, which whitespace changes should be ignored. Allowed values are `IGNORE_NONE`, `IGNORE_SPACE_AT_EOL`, `IGNORE_SPACE_CHANGE`, `IGNORE_ALL_SPACE`.
`intraline_difference`	not set if `false`	Whether intraline differences should be highlighted.
`line_length`		Number of characters that should be displayed in one line.
`manual_review`	not set if `false`	Whether the Reviewed flag should not be set automatically on a patch when it is viewed.
`retain_header`	not set if `false`	Whether the header that is displayed above the patch (that either shows the commit message, the diff preferences, the patch sets or the files) should be retained on file switch.
`show_line_endings`	not set if `false`	Whether Windows EOL/Cr-Lf should be displayed as \r in a dotted-line box.
`show_tabs`	not set if `false`	Whether tabs should be shown.
`show_whitespace_errors`	not set if `false`	Whether whitespace errors should be shown.
`skip_deleted`	not set if `false`	Whether deleted files should be skipped on file switch.
`skip_uncommented`	not set if `false`	Whether uncommented files should be skipped on file switch.
`syntax_highlighting`	not set if `false`	Whether syntax highlighting should be enabled.
`tab_size`		Number of spaces that should be used to display one tab.

DiffPreferencesInput

The DiffPreferencesInput entity contains information for setting the diff preferences of a user. Fields which are not set will not be updated.

Field Name		Description
`context`	optional	The number of lines of context when viewing a patch.
`expand_all_comments`	optional	Whether all inline comments should be automatically expanded.
`ignore_whitespace`	optional	Whether whitespace changes should be ignored and if yes, which whitespace changes should be ignored. Allowed values are `IGNORE_NONE`, `IGNORE_SPACE_AT_EOL`, `IGNORE_SPACE_CHANGE`, `IGNORE_ALL_SPACE`.
`intraline_difference`	optional	Whether intraline differences should be highlighted.
`line_length`	optional	Number of characters that should be displayed in one line.
`manual_review`	optional	Whether the Reviewed flag should not be set automatically on a patch when it is viewed.
`retain_header`	optional	Whether the header that is displayed above the patch (that either shows the commit message, the diff preferences, the patch sets or the files) should be retained on file switch.
`show_line_endings`	optional	Whether Windows EOL/Cr-Lf should be displayed as \r in a dotted-line box.
`show_tabs`	optional	Whether tabs should be shown.
`show_whitespace_errors`	optional	Whether whitespace errors should be shown.
`skip_deleted`	optional	Whether deleted files should be skipped on file switch.
`skip_uncommented`	optional	Whether uncommented files should be skipped on file switch.
`syntax_highlighting`	optional	Whether syntax highlighting should be enabled.
`tab_size`	optional	Number of spaces that should be used to display one tab.

QueryLimitInfo

The QueryLimitInfo entity contains information about the Query Limit of a user.

Field Name	Description
`min`	Lower limit.
`max`	Upper limit.

Part of Gerrit Code Review