Documentation/rest-api-accounts.txt

Gerrit Code Review - /accounts/ REST API
========================================

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

[[account-endpoints]]
Account Endpoints
-----------------

[[get-account]]
Get Account
~~~~~~~~~~~
[verse]
'GET /accounts/link:#account-id[\{account-id\}]'

Returns an account as an link:#account-info[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",
    "username": "john"
  }
----

[[create-account]]
Create Account
~~~~~~~~~~~~~~
[verse]
'PUT /accounts/link:#username[\{username\}]'

Creates a new account.

In the request body additional data for the account can be provided as
link:#account-input[AccountInput].

.Request
----
  PUT /accounts/john HTTP/1.0
  Content-Type: application/json;charset=UTF-8

  {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "ssh_key": "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA0T...YImydZAw==",
    "http_password": "19D9aIn7zePb",
    "groups": [
      "MyProject-Owners"
    ]
  }
----

As response a detailed link:#account-info[AccountInfo] entity is
returned that describes the created account.

.Response
----
  HTTP/1.1 201 Created
  Content-Disposition: attachment
  Content-Type: application/json;charset=UTF-8

  )]}'
  {
    "_account_id": 1000195,
    "name": "John Doe",
    "email": "john.doe@example.com"
  }
----

[[get-account-name]]
Get Account Name
~~~~~~~~~~~~~~~~
[verse]
'GET /accounts/link:#account-id[\{account-id\}]/name'

Retrieves the full name of an account.

.Request
----
  GET /accounts/self/name HTTP/1.0
----

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

  )]}'
  "John Doe"
----

If the account does not have a name an empty string is returned.

[[set-account-name]]
Set Account Name
~~~~~~~~~~~~~~~~
[verse]
'PUT /accounts/link:#account-id[\{account-id\}]/name'

Sets the full name of an account.

The new account name must be provided in the request body inside
a link:#account-name-input[AccountNameInput] entity.

.Request
----
  PUT /accounts/self/name HTTP/1.0
  Content-Type: application/json;charset=UTF-8

  {
    "name": "John F. Doe"
  }
----

As response the new account name is returned.

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

  )]}'
  "John F. Doe"
----

If the name was deleted the response is "`204 No Content`".

Some realms may not allow to modify the account name. In this case the
request is rejected with "`405 Method Not Allowed`".

[[delete-account-name]]
Delete Account Name
~~~~~~~~~~~~~~~~~~~
[verse]
'DELETE /accounts/link:#account-id[\{account-id\}]/name'

Deletes the name of an account.

.Request
----
  DELETE /accounts/self/name HTTP/1.0
----

.Response
----
  HTTP/1.1 204 No Content
----

[[get-username]]
Get Username
~~~~~~~~~~~~
[verse]
'GET /accounts/link:#account-id[\{account-id\}]/username'

Retrieves the username of an account.

.Request
----
  GET /accounts/self/username HTTP/1.0
----

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

  )]}'
  "john.doe"
----

If the account does not have a username the response is `404 Not Found`.

[[get-active]]
Get Active
~~~~~~~~~~
[verse]
'GET /accounts/link:#account-id[\{account-id\}]/active'

Checks if an account is active.

.Request
----
  GET /accounts/john.doe@example.com/active HTTP/1.0
----

As response `200 OK` is returned for an active account and
`404 Not Found` is returned for an inactive account.

.Response
----
  HTTP/1.1 200 OK
----

[[set-active]]
Set Active
~~~~~~~~~~
[verse]
'PUT /accounts/link:#account-id[\{account-id\}]/active'

Sets the account state to active.

.Request
----
  PUT /accounts/john.doe@example.com/active HTTP/1.0
----

.Response
----
  HTTP/1.1 201 Created
----

If the account was already active the response is `200 OK`.

[[delete-active]]
Delete Active
~~~~~~~~~~~~~
[verse]
'DELETE /accounts/link:#account-id[\{account-id\}]/active'

Sets the account state to inactive.

.Request
----
  DELETE /accounts/john.doe@example.com/active HTTP/1.0
----

.Response
----
  HTTP/1.1 204 No Content
----

If the account was already inactive the response is `404 Not Found`.

[[get-http-password]]
Get HTTP Password
~~~~~~~~~~~~~~~~~
[verse]
'GET /accounts/link:#account-id[\{account-id\}]/password.http'

Retrieves the HTTP password of an account.

.Request
----
  GET /accounts/john.doe@example.com/password.http HTTP/1.0
----

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

  )]}'
  "ETxgpih8xrNs"
----

If the account does not have an HTTP password the response is `404 Not Found`.

[[set-http-password]]
Set/Generate HTTP Password
~~~~~~~~~~~~~~~~~~~~~~~~~~
[verse]
'PUT /accounts/link:#account-id[\{account-id\}]/password.http'

Sets/Generates the HTTP password of an account.

The options for setting/generating the HTTP password must be provided
in the request body inside a link:#http-password-input[
HttpPasswordInput] entity.

.Request
----
  PUT /accounts/self/password.http HTTP/1.0
  Content-Type: application/json;charset=UTF-8

  {
    "generate": true
  }
----

As response the new HTTP password is returned.

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

  )]}'
  "ETxgpih8xrNs"
----

If the HTTP password was deleted the response is "`204 No Content`".

[[delete-http-password]]
Delete HTTP Password
~~~~~~~~~~~~~~~~~~~~
[verse]
'DELETE /accounts/link:#account-id[\{account-id\}]/password.http'

Deletes the HTTP password of an account.

.Request
----
  DELETE /accounts/self/password.http HTTP/1.0
----

.Response
----
  HTTP/1.1 204 No Content
----

[[list-account-emails]]
List Account Emails
~~~~~~~~~~~~~~~~~~~
[verse]
'GET /accounts/link:#account-id[\{account-id\}]/emails'

Returns the email addresses that are configured for the specified user.

.Request
----
  GET /accounts/self/emails HTTP/1.0
----

As response the email addresses of the user are returned as a list of
link:#email-info[EmailInfo] entities.

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

  )]}'
  [
    {
      "email": "john.doe@example.com",
      "preferred": true
    },
    {
      "email": "j.doe@example.com"
    }
  ]
----

[[get-account-email]]
Get Account Email
~~~~~~~~~~~~~~~~~
[verse]
'GET /accounts/link:#account-id[\{account-id\}]/emails/link:#email-id[\{email-id\}]'

Retrieves an email address of a user.

.Request
----
  GET /accounts/self/emails/john.doe@example.com HTTP/1.0
----

As response an link:#email-info[EmailInfo] entity is returned that
describes the email address.

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

  )]}'
  {
    "email": "john.doe@example.com",
    "preferred": true
  }
----

[[create-account-email]]
Create Account Email
~~~~~~~~~~~~~~~~~~~~
[verse]
'PUT /accounts/link:#account-id[\{account-id\}]/emails/link:#email-id[\{email-id\}]'

Registers a new email address for the user. A verification email is
sent with a link that needs to be visited to confirm the email address,
unless `DEVELOPMENT_BECOME_ANY_ACCOUNT` is used as authentication type.
For the development mode email addresses are directly added without
confirmation. A Gerrit administrator may add an email address without
confirmation by setting `no_confirmation` in the
link:#email-input[EmailInput].

In the request body additional data for the email address can be
provided as link:#email-input[EmailInput].

.Request
----
  PUT /accounts/self/emails/john.doe@example.com HTTP/1.0
----

As response the new email address is returned as
link:#email-info[EmailInfo] entity.

.Response
----
  HTTP/1.1 201 Created
  Content-Disposition: attachment
  Content-Type: application/json;charset=UTF-8

  )]}'
  {
    "email": "john.doe@example.com",
    "pending_confirmation": true
  }
----

[[delete-account-email]]
Delete Account Email
~~~~~~~~~~~~~~~~~~~~
[verse]
'DELETE /accounts/link:#account-id[\{account-id\}]/emails/link:#email-id[\{email-id\}]'

Deletes an email address of an account.

.Request
----
  DELETE /accounts/self/emails/john.doe@example.com HTTP/1.0
----

.Response
----
  HTTP/1.1 204 No Content
----

[[set-preferred-email]]
Set Preferred Email
~~~~~~~~~~~~~~~~~~~
[verse]
'PUT /accounts/link:#account-id[\{account-id\}]/emails/link:#email-id[\{email-id\}]/preferred'

Sets an email address as preferred email address for an account.

.Request
----
  PUT /accounts/self/emails/john.doe@example.com/preferred HTTP/1.0
----

.Response
----
  HTTP/1.1 201 Created
----

If the email address was already the preferred email address of the
account the response is "`200 OK`".

[[list-ssh-keys]]
List SSH Keys
~~~~~~~~~~~~~
[verse]
'GET /accounts/link:#account-id[\{account-id\}]/sshkeys'

Returns the SSH keys of an account.

.Request
----
  GET /accounts/self/sshkeys HTTP/1.0
----

As response the SSH keys of the account are returned as a list of
link:#ssh-key-info[SshKeyInfo] entities.

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

  )]}'
  [
    {
      "seq": 1,
      "ssh_public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA0T...YImydZAw\u003d\u003d john.doe@example.com",
      "encoded_key": "AAAAB3NzaC1yc2EAAAABIwAAAQEA0T...YImydZAw\u003d\u003d",
      "algorithm": "ssh-rsa",
      "comment": "john.doe@example.com",
      "valid": true
    }
  ]
----

[[get-ssh-key]]
Get SSH Key
~~~~~~~~~~~
[verse]
'GET /accounts/link:#account-id[\{account-id\}]/sshkeys/link:#ssh-key-id[\{ssh-key-id\}]'

Retrieves an SSH key of a user.

.Request
----
  GET /accounts/self/sshkeys/1 HTTP/1.0
----

As response an link:#ssh-key-info[SshKeyInfo] entity is returned that
describes the SSH key.

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

  )]}'
  {
    "seq": 1,
    "ssh_public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA0T...YImydZAw\u003d\u003d john.doe@example.com",
    "encoded_key": "AAAAB3NzaC1yc2EAAAABIwAAAQEA0T...YImydZAw\u003d\u003d",
    "algorithm": "ssh-rsa",
    "comment": "john.doe@example.com",
    "valid": true
  }
----

[[add-ssh-key]]
Add SSH Key
~~~~~~~~~~~
[verse]
'POST /accounts/link:#account-id[\{account-id\}]/sshkeys'

Adds an SSH key for a user.

The SSH public key must be provided as raw content in the request body.

.Request
----
  POST /accounts/self/sshkeys HTTP/1.0
  Content-Type: plain/text

  AAAAB3NzaC1yc2EAAAABIwAAAQEA0T...YImydZAw\u003d\u003d
----

As response an link:#ssh-key-info[SshKeyInfo] entity is returned that
describes the new SSH key.

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

  )]}'
  {
    "seq": 2,
    "ssh_public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA0T...YImydZAw\u003d\u003d john.doe@example.com",
    "encoded_key": "AAAAB3NzaC1yc2EAAAABIwAAAQEA0T...YImydZAw\u003d\u003d",
    "algorithm": "ssh-rsa",
    "comment": "john.doe@example.com",
    "valid": true
  }
----

[[delete-ssh-key]]
Delete SSH Key
~~~~~~~~~~~~~~
[verse]
'DELETE /accounts/link:#account-id[\{account-id\}]/sshkeys/link:#ssh-key-id[\{ssh-key-id\}]'

Deletes an SSH key of a user.

.Request
----
  DELETE /accounts/self/sshkeys/2 HTTP/1.0
----

.Response
----
  HTTP/1.1 204 No Content
----

[[list-account-capabilities]]
List Account Capabilities
~~~~~~~~~~~~~~~~~~~~~~~~~
[verse]
'GET /accounts/link:#account-id[\{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
link:#capability-info[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
  }
----

.Get your own capabilities
****
get::/accounts/self/capabilities
****

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

[[check-account-capability]]
Check Account Capability
~~~~~~~~~~~~~~~~~~~~~~~~
[verse]
'GET /accounts/link:#account-id[\{account-id\}]/capabilities/link:#capability-id[\{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
****

[[list-groups]]
List Groups
~~~~~~~~~~~
[verse]
'GET /accounts/link:#account-id[\{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 link:rest-api-groups.html#group-info[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/
****

[[get-avatar]]
Get Avatar
~~~~~~~~~~
[verse]
'GET /accounts/link:#account-id[\{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 Avatar Change URL
~~~~~~~~~~~~~~~~~~~~~
[verse]
'GET /accounts/link:#account-id[\{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 Diff Preferences
~~~~~~~~~~~~~~~~~~~~
[verse]
'GET /accounts/link:#account-id[\{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
link:#diff-preferences-info[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]]
Set Diff Preferences
~~~~~~~~~~~~~~~~~~~~
[verse]
'PUT /accounts/link:#account-id[\{account-id\}]/preferences.diff'

Sets the diff preferences of a user.

The new diff preferences must be provided in the request body as a
link:#diff-preferences-input[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
link:#diff-preferences-info[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
  }
----

[[get-starred-changes]]
Get Starred Changes
~~~~~~~~~~~~~~~~~~~
[verse]
'GET /accounts/link:#account-id[\{account-id\}]/starred.changes'

Gets the changes starred by the identified user account. This
URL endpoint is functionally identical to the changes query
`GET /changes/?q=is:starred`. The result is a list of
link:rest-api-changes.html#change-info[ChangeInfo] entities.

.Request
----
  GET /a/accounts/self/starred.changes
----

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

  )]}'
  [
    {
      "kind": "gerritcodereview#change",
      "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940",
      "project": "myProject",
      "branch": "master",
      "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940",
      "subject": "Implementing Feature X",
      "status": "NEW",
      "created": "2013-02-01 09:59:32.126000000",
      "updated": "2013-02-21 11:16:36.775000000",
      "mergeable": true,
      "_sortkey": "0023412400000f7d",
      "_number": 3965,
      "owner": {
        "name": "John Doe"
      }
    }
  ]
----

[[star-change]]
Star Change
~~~~~~~~~~~
[verse]
'PUT /accounts/link:#account-id[\{account-id\}]/starred.changes/link:rest-api-changes.html#change-id[\{change-id\}]'

Star a change. Starred changes are returned for the search query
`is:starred` or `starredby:USER` and automatically notify the user
whenever updates are made to the change.

.Request
----
  PUT /a/accounts/self/starred.changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940 HTTP/1.0
----

.Response
----
  HTTP/1.1 204 No Content
----

[[unstar-change]]
Unstar Change
~~~~~~~~~~~~~
[verse]
'DELETE /accounts/link:#account-id[\{account-id\}]/starred.changes/link:rest-api-changes#change-id[\{change-id\}]'

Unstar a change. Removes the starred flag, stopping notifications.

.Request
----
  DELETE /a/accounts/self/starred.changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940 HTTP/1.0
----

.Response
----
  HTTP/1.1 204 No Content
----

[[ids]]
IDs
---

[[account-id]]
\{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]]
\{capability-id\}
~~~~~~~~~~~~~~~~~
Identifier of a global capability. Valid values are all field names of
the link:#capability-info[CapabilityInfo] entity.

[[email-id]]
\{email-id\}
~~~~~~~~~~~~
An email address, or `preferred` for the preferred email address of the
user.

[[username]]
\{username\}
~~~~~~~~~~~~
The user name.

[[ssh-key-id]]
\{ssh-key-id\}
~~~~~~~~~~~~~~
The sequence number of the SSH key.


[[json-entities]]
JSON Entities
-------------

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

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

[[account-input]]
AccountInput
~~~~~~~~~~~~
The `AccountInput` entity contains information for the creation of
a new account.

[options="header",width="50%",cols="1,^2,4"]
|============================
|Field Name     ||Description
|`username`     |optional|
The user name. If provided, must match the user name from the URL.
|`name`         |optional|The full name of the user.
|`email`        |optional|The email address of the user.
|`ssh_key`      |optional|The public SSH key of the user.
|`http_password`|optional|The HTTP password of the user.
|`groups`       |optional|
A list of link:rest-api-groups.html#group-id[group IDs] that identify
the groups to which the user should be added.
|============================

[[account-name-input]]
AccountNameInput
~~~~~~~~~~~~~~~~
The `AccountNameInput` entity contains information for setting a name
for an account.

[options="header",width="50%",cols="1,^2,4"]
|=============================
|Field Name ||Description
|`name`     |optional|The new full name of the account. +
If not set or if set to an empty string, the account name is deleted.
|=============================

[[capability-info]]
CapabilityInfo
~~~~~~~~~~~~~~
The `CapabilityInfo` entity contains information about the global
capabilities of a user.

[options="header",width="50%",cols="1,^1,5"]
|=================================
|Field Name          ||Description
|`administrateServer`|not set if `false`|Whether the user has the
link:access-control.html#capability_administrateServer[Administrate
Server] capability.
|`queryLimit`||The link:access-control.html#capability_queryLimit[Query
Limit] of the user as link:#query-limit-info[QueryLimitInfo].
|`createAccount`     |not set if `false`|Whether the user has the
link:access-control.html#capability_createAccount[Create Account]
capability.
|`createGroup`       |not set if `false`|Whether the user has the
link:access-control.html#capability_createGroup[Create Group]
capability.
|`createProject`     |not set if `false`|Whether the user has the
link:access-control.html#capability_createProject[Create Project]
capability.
|`emailReviewers`    |not set if `false`|Whether the user has the
link:access-control.html#capability_emailReviewers[Email Reviewers]
capability.
|`killTask`          |not set if `false`|Whether the user has the
link:access-control.html#capability_kill[Kill Task] capability.
|`viewCaches`        |not set if `false`|Whether the user has the
link:access-control.html#capability_viewCaches[View Caches] capability.
|`flushCaches`       |not set if `false`|Whether the user has the
link:access-control.html#capability_flushCaches[Flush Caches]
capability.
|`viewConnections`   |not set if `false`|Whether the user has the
link:access-control.html#capability_viewConnections[View Connections]
capability.
|`viewQueue`         |not set if `false`|Whether the user has the
link:access-control.html#capability_viewQueue[View Queue] capability.
|`runGC`  |not set if `false`|Whether the user has the
link:access-control.html#capability_runGC[Run Garbage Collection]
capability.
|=================================

[[diff-preferences-info]]
DiffPreferencesInfo
~~~~~~~~~~~~~~~~~~~
The `DiffPreferencesInfo` entity contains information about the diff
preferences of a user.

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

[[diff-preferences-input]]
DiffPreferencesInput
~~~~~~~~~~~~~~~~~~~~
The `DiffPreferencesInput` entity contains information for setting the
diff preferences of a user. Fields which are not set will not be
updated.

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

[[email-info]]
EmailInfo
~~~~~~~~~
The `EmailInfo` entity contains information about an email address of a
user.

[options="header",width="50%",cols="1,^1,5"]
|========================
|Field Name ||Description
|`email`    ||The email address.
|`preferred`|not set if `false`|
Whether this is the preferred email address of the user.
|`pending_confirmation`|not set if `false`|
Set true if the user must confirm control of the email address
by following a verification link before Gerrit will permit use of
this address.
|========================

[[email-input]]
EmailInput
~~~~~~~~~~
The `EmailInput` entity contains information for registering a new
email address.

[options="header",width="50%",cols="1,^1,5"]
|==============================
|Field Name       ||Description
|`email`          ||
The email address. If provided, must match the email address from the
URL.
|`preferred`      |`false` if not set|
Whether the new email address should become the preferred email address
of the user (only supported if `no_confirmation` is set or if the
authentication type is `DEVELOPMENT_BECOME_ANY_ACCOUNT`).
|`no_confirmation`|`false` if not set|
Whether the email address should be added without confirmation. In this
case no verification email is sent to the user. +
Only Gerrit administrators are allowed to add email addresses without
confirmation.
|==============================

[[http-password-input]]
HttpPasswordInput
~~~~~~~~~~~~~~~~~
The `HttpPasswordInput` entity contains information for setting/generating
an HTTP password.

[options="header",width="50%",cols="1,^1,5"]
|============================
|Field Name     ||Description
|`generate`     |`false` if not set|
Whether a new HTTP password should be generated
|`http_password`|optional|
The new HTTP password. Only Gerrit administrators may set the HTTP
password directly. +
If empty or not set and `generate` is false or not set, the HTTP
password is deleted.
|============================

[[query-limit-info]]
QueryLimitInfo
~~~~~~~~~~~~~~
The `QueryLimitInfo` entity contains information about the
link:access-control.html#capability_queryLimit[Query Limit] of a user.

[options="header",width="50%",cols="1,6"]
|================================
|Field Name          |Description
|`min`               |Lower limit.
|`max`               |Upper limit.
|================================

[[ssh-key-info]]
SshKeyInfo
~~~~~~~~~~
The `SshKeyInfo` entity contains information about an SSH key of a
user.

[options="header",width="50%",cols="1,^1,5"]
|=============================
|Field Name      ||Description
|`seq`           ||The sequence number of the SSH key.
|`ssh_public_key`||The complete public SSH key.
|`encoded_key`   ||The encoded key.
|`algorithm`     ||The algorithm of the SSH key.
|`comment`       |optional|The comment of the SSH key.
|`valid`         ||Whether the SSH key is valid.
|=============================


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