| 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 |
| ~~~~~~~~~~~ |
| -- |
| '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 |
| ~~~~~~~~~~~~~~ |
| -- |
| '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 |
| ~~~~~~~~~~~~~~~~ |
| -- |
| '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 |
| ~~~~~~~~~~~~~~~~ |
| -- |
| '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 |
| ~~~~~~~~~~~~~~~~~~~ |
| -- |
| '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 |
| ~~~~~~~~~~~~ |
| -- |
| '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 |
| ~~~~~~~~~~ |
| -- |
| '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 |
| ---- |
| |
| If the account is active the string `ok` is returned. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| |
| ok |
| ---- |
| |
| If the account is inactive the response is `204 No Content`. |
| |
| [[set-active]] |
| Set Active |
| ~~~~~~~~~~ |
| -- |
| '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 |
| ~~~~~~~~~~~~~ |
| -- |
| '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 |
| ~~~~~~~~~~~~~~~~~ |
| -- |
| '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 |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| -- |
| '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 |
| ~~~~~~~~~~~~~~~~~~~~ |
| -- |
| '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 |
| ~~~~~~~~~~~~~~~~~~~ |
| -- |
| '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 |
| ~~~~~~~~~~~~~~~~~ |
| -- |
| '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 |
| ~~~~~~~~~~~~~~~~~~~~ |
| -- |
| '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 |
| ~~~~~~~~~~~~~~~~~~~~ |
| -- |
| '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 |
| ~~~~~~~~~~~~~~~~~~~ |
| -- |
| '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 |
| ~~~~~~~~~~~~~ |
| -- |
| '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 |
| ~~~~~~~~~~~ |
| -- |
| '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 |
| ~~~~~~~~~~~ |
| -- |
| '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 |
| ~~~~~~~~~~~~~~ |
| -- |
| '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 |
| ~~~~~~~~~~~~~~~~~~~~~~~~~ |
| -- |
| '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 |
| ~~~~~~~~~~~~~~~~~~~~~~~~ |
| -- |
| '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 |
| ~~~~~~~~~~~ |
| -- |
| '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 |
| ~~~~~~~~~~ |
| -- |
| '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 |
| ~~~~~~~~~~~~~~~~~~~~~ |
| -- |
| '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 |
| ~~~~~~~~~~~~~~~~~~~~ |
| -- |
| '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 |
| ~~~~~~~~~~~~~~~~~~~~ |
| -- |
| '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 |
| ~~~~~~~~~~~~~~~~~~~ |
| -- |
| '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 |
| ~~~~~~~~~~~ |
| -- |
| '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 |
| ~~~~~~~~~~~~~ |
| -- |
| '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 |
| |`accessDatabase` |not set if `false`|Whether the user has the |
| link:access-control.html#capability_accessDatabase[Access Database] |
| capability. |
| |`administrateServer`|not set if `false`|Whether the user has the |
| link:access-control.html#capability_administrateServer[Administrate |
| Server] capability. |
| |`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. |
| |`flushCaches` |not set if `false`|Whether the user has the |
| link:access-control.html#capability_flushCaches[Flush Caches] |
| capability. |
| |`killTask` |not set if `false`|Whether the user has the |
| link:access-control.html#capability_kill[Kill Task] capability. |
| |`priority` |not set if `INTERACTIVE`|The name of the thread |
| pool used by the user, see link:access-control.html#capability_priority[ |
| Priority] capability. |
| |`queryLimit` ||The link:access-control.html#capability_queryLimit[ |
| Query Limit] of the user as link:#query-limit-info[QueryLimitInfo]. |
| |`runAs` |not set if `false`|Whether the user has the |
| link:access-control.html#capability_runAs[Run As] capability. |
| |`runGC` |not set if `false`|Whether the user has the |
| link:access-control.html#capability_runGC[Run Garbage Collection] |
| capability. |
| |`streamEvents` |not set if `false`|Whether the user has the |
| link:access-control.html#capability_streamEvents[Stream Events] |
| capability. |
| |`viewCaches` |not set if `false`|Whether the user has the |
| link:access-control.html#capability_viewCaches[View 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. |
| |================================= |
| |
| [[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] |
| |
| SEARCHBOX |
| --------- |
