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

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.

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