| = 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 |
| |
| [[query-account]] |
| === Query Account |
| -- |
| 'GET /accounts/' |
| -- |
| |
| Queries accounts visible to the caller. The |
| link:user-search-accounts.html#_search_operators[query string] must be |
| provided by the `q` parameter. The `n` parameter can be used to limit |
| the returned results. |
| |
| As result a list of link:#account-info[AccountInfo] entities is |
| returned. |
| |
| .Request |
| ---- |
| GET /accounts/?q=name:John+email:example.com&n=2 HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| [ |
| { |
| "_account_id": 1000096, |
| }, |
| { |
| "_account_id": 1001439, |
| "_more_accounts": true |
| } |
| ] |
| ---- |
| |
| If the number of accounts matching the query exceeds either the |
| internal limit or a supplied `n` query parameter, the last account |
| object has a `_more_accounts: true` JSON field set. |
| |
| The `S` or `start` query parameter can be supplied to skip a number |
| of accounts from the list. |
| |
| Additional fields can be obtained by adding `o` parameters, each |
| option slows down the query response time to the client so they are |
| generally disabled by default. Optional fields are: |
| |
| [[details]] |
| -- |
| * `DETAILS`: Includes full name, preferred email, username and avatars |
| for each account. |
| -- |
| |
| [[all-emails]] |
| -- |
| * `ALL_EMAILS`: Includes all registered emails. |
| -- |
| |
| [[suggest-account]] |
| To get account suggestions set the parameter `suggest` and provide the |
| typed substring as query `q`. If a result limit `n` is not specified, |
| then the default 10 is used. |
| |
| For account suggestions link:#details[account details] and |
| link:#all-emails[all emails] are always returned. |
| |
| .Request |
| ---- |
| GET /accounts/?suggest&q=John 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" |
| }, |
| { |
| "_account_id": 1001439, |
| "name": "John Smith", |
| "email": "john.smith@example.com", |
| "username": "jsmith" |
| }, |
| ] |
| ---- |
| |
| [[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-detail]] |
| === Get Account Details |
| -- |
| 'GET /accounts/link:#account-id[\{account-id\}]/detail' |
| -- |
| |
| Retrieves the details of an account as an link:#account-detail-info[ |
| AccountDetailInfo] entity. |
| |
| .Request |
| ---- |
| GET /accounts/self/detail HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "registered_on": "2015-07-23 07:01:09.296000000", |
| "_account_id": 1000096, |
| "name": "John Doe", |
| "email": "john.doe@example.com", |
| "username": "john" |
| } |
| ---- |
| |
| [[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 |
| an 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-account-status]] |
| === Get Account Status |
| -- |
| 'GET /accounts/link:#account-id[\{account-id\}]/status' |
| -- |
| |
| Retrieves the status of an account. |
| |
| .Request |
| ---- |
| GET /accounts/self/status HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| "Available" |
| ---- |
| |
| If the account does not have a status an empty string is returned. |
| |
| [[set-account-status]] |
| === Set Account Status |
| -- |
| 'PUT /accounts/link:#account-id[\{account-id\}]/status' |
| -- |
| |
| Sets the status of an account. |
| |
| The new account status must be provided in the request body inside |
| an link:#account-status-input[AccountStatusInput] entity. |
| |
| .Request |
| ---- |
| PUT /accounts/self/status HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "status": "Out Of Office" |
| } |
| ---- |
| |
| As response the new account status is returned. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| "Out Of Office" |
| ---- |
| |
| If the name was deleted the response is "`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`". |
| |
| [[set-username]] |
| === Set Username |
| -- |
| 'PUT /accounts/link:#account-id[\{account-id\}]/username' |
| -- |
| |
| The new username must be provided in the request body inside |
| a link:#username-input[UsernameInput] entity. |
| |
| Once set, the username cannot be changed or deleted. If attempted this |
| fails with "`405 Method Not Allowed`". |
| |
| .Request |
| ---- |
| PUT /accounts/self/username HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "username": "jdoe" |
| } |
| ---- |
| |
| As response the new username is returned. |
| |
| [[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 "`409 Conflict`". |
| |
| [[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 |
| ---- |
| |
| [[get-oauth-token]] |
| === Get OAuth Access Token |
| -- |
| 'GET /accounts/link:#account-id[\{account-id\}]/oauthtoken' |
| -- |
| |
| Returns a previously obtained OAuth access token. |
| |
| .Request |
| ---- |
| GET /accounts/self/oauthtoken HTTP/1.1 |
| ---- |
| |
| As a response, an link:#oauth-token-info[OAuthTokenInfo] entity is returned |
| that describes the OAuth access token. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "username": "johndow", |
| "resource_host": "gerrit.example.org", |
| "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOi", |
| "provider_id": "oauth-plugin:oauth-provider", |
| "expires_at": "922337203775807", |
| "type": "bearer" |
| } |
| ---- |
| |
| If there is no token available, or the token has already expired, |
| "`404 Not Found`" is returned as response. Requests to obtain an access |
| token of another user are rejected with "`403 Forbidden`". |
| |
| [[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]. |
| If link:config-gerrit.html#sendemail.allowrcpt[sendemail.allowrcpt] is |
| configured, the added email address must belong to a domain that is |
| allowed, unless `no_confirmation` is set. |
| |
| The link:#email-input[EmailInput] object in the request body may |
| contain additional options for the email address. |
| |
| .Request |
| ---- |
| PUT /accounts/self/emails/john.doe@example.com HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| Content-Length: 3 |
| |
| {} |
| ---- |
| |
| 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. |
| |
| Trying to add an SSH key that already exists succeeds, but no new SSH |
| key is persisted. |
| |
| .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-gpg-keys]] |
| === List GPG Keys |
| -- |
| 'GET /accounts/link:#account-id[\{account-id\}]/gpgkeys' |
| -- |
| |
| Returns the GPG keys of an account. |
| |
| .Request |
| ---- |
| GET /accounts/self/gpgkeys HTTP/1.0 |
| ---- |
| |
| As a response, the GPG keys of the account are returned as a map of |
| link:#gpg-key-info[GpgKeyInfo] entities, keyed by ID. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "AFC8A49B": { |
| "fingerprint": "0192 723D 42D1 0C5B 32A6 E1E0 9350 9E4B AFC8 A49B", |
| "user_ids": [ |
| "John Doe \u003cjohn.doe@example.com\u003e" |
| ], |
| "key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\nVersion: BCPG v1.52\n\nmQENBFXUpNcBCACv4paCiyKxZ0EcKy8VaWVNkJlNebRBiyw9WxU85wPOq5Gz/3GT\nRQwKqeY0SxVdQT8VNBw2sBe2m6eqcfZ2iKmesSlbXMe15DA7k8Bg4zEpQ0tXNG1L\nhceZDVQ1Xk06T2sgkunaiPsXi82nwN3UWYtDXxX4is5e6xBNL48Jgz4lbqo6+8D5\nvsVYiYMx4AwRkJyt/oA3IZAtSlY8Yd445nY14VPcnsGRwGWTLyZv9gxKHRUppVhQ\nE3o6ePXKEVgmONnQ4CjqmkGwWZvjMF2EPtAxvQLAuFa8Hqtkq5cgfgVkv/Vrcln4\nnQZVoMm3a3f5ODii2tQzNh6+7LL1bpqAmVEtABEBAAG0H0pvaG4gRG9lIDxqb2hu\nLmRvZUBleGFtcGxlLmNvbT6JATgEEwECACIFAlXUpNcCGwMGCwkIBwMCBhUIAgkK\nCwQWAgMBAh4BAheAAAoJEJNQnkuvyKSbfjoH/2OcSQOu1kJ20ndjhgY2yNChm7gd\ntU7TEBbB0TsLeazkrrLtKvrpW5+CRe07ZAG9HOtp3DikwAyrhSxhlYgVsQDhgB8q\nG0tYiZtQ88YyYrncCQ4hwknrcWXVW9bK3V4ZauxzPv3ADSloyR9tMURw5iHCIeL5\nfIw/pLvA3RjPMx4Sfow/bqRCUELua39prGw5Tv8a2ZRFbj2sgP5j8lUFegyJPQ4z\ntJhe6zZvKOzvIyxHO8llLmdrImsXRL9eqroWGs0VYqe6baQpY6xpSjbYK0J5HYcg\nTO+/u80JI+ROTMHE6unGp5Pgh/xIz6Wd34E0lWL1eOyNfGiPLyRWn1d0", |
| "status": "TRUSTED", |
| "problems": [], |
| }, |
| } |
| ---- |
| |
| [[get-gpg-key]] |
| === Get GPG Key |
| -- |
| 'GET /accounts/link:#account-id[\{account-id\}]/gpgkeys/link:#gpg-key-id[\{gpg-key-id\}]' |
| -- |
| |
| Retrieves a GPG key of a user. |
| |
| .Request |
| ---- |
| GET /accounts/self/gpgkeys/AFC8A49B HTTP/1.0 |
| ---- |
| |
| As a response, a link:#gpg-key-info[GpgKeyInfo] entity is returned that |
| describes the GPG key. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "id": "AFC8A49B", |
| "fingerprint": "0192 723D 42D1 0C5B 32A6 E1E0 9350 9E4B AFC8 A49B", |
| "user_ids": [ |
| "John Doe \u003cjohn.doe@example.com\u003e" |
| ], |
| "key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\nVersion: BCPG v1.52\n\nmQENBFXUpNcBCACv4paCiyKxZ0EcKy8VaWVNkJlNebRBiyw9WxU85wPOq5Gz/3GT\nRQwKqeY0SxVdQT8VNBw2sBe2m6eqcfZ2iKmesSlbXMe15DA7k8Bg4zEpQ0tXNG1L\nhceZDVQ1Xk06T2sgkunaiPsXi82nwN3UWYtDXxX4is5e6xBNL48Jgz4lbqo6+8D5\nvsVYiYMx4AwRkJyt/oA3IZAtSlY8Yd445nY14VPcnsGRwGWTLyZv9gxKHRUppVhQ\nE3o6ePXKEVgmONnQ4CjqmkGwWZvjMF2EPtAxvQLAuFa8Hqtkq5cgfgVkv/Vrcln4\nnQZVoMm3a3f5ODii2tQzNh6+7LL1bpqAmVEtABEBAAG0H0pvaG4gRG9lIDxqb2hu\nLmRvZUBleGFtcGxlLmNvbT6JATgEEwECACIFAlXUpNcCGwMGCwkIBwMCBhUIAgkK\nCwQWAgMBAh4BAheAAAoJEJNQnkuvyKSbfjoH/2OcSQOu1kJ20ndjhgY2yNChm7gd\ntU7TEBbB0TsLeazkrrLtKvrpW5+CRe07ZAG9HOtp3DikwAyrhSxhlYgVsQDhgB8q\nG0tYiZtQ88YyYrncCQ4hwknrcWXVW9bK3V4ZauxzPv3ADSloyR9tMURw5iHCIeL5\nfIw/pLvA3RjPMx4Sfow/bqRCUELua39prGw5Tv8a2ZRFbj2sgP5j8lUFegyJPQ4z\ntJhe6zZvKOzvIyxHO8llLmdrImsXRL9eqroWGs0VYqe6baQpY6xpSjbYK0J5HYcg\nTO+/u80JI+ROTMHE6unGp5Pgh/xIz6Wd34E0lWL1eOyNfGiPLyRWn1d0", |
| "status": "TRUSTED", |
| "problems": [], |
| } |
| ---- |
| |
| [[add-delete-gpg-keys]] |
| === Add/Delete GPG Keys |
| -- |
| 'POST /accounts/link:#account-id[\{account-id\}]/gpgkeys' |
| -- |
| |
| Add or delete one or more GPG keys for a user. |
| |
| The changes must be provided in the request body as a |
| link:#gpg-keys-input[GpgKeysInput] entity. Each new GPG key is provided in |
| ASCII armored format, and must contain a self-signed certification |
| matching a registered email or other identity of the user. |
| |
| .Request |
| ---- |
| POST /accounts/link:#account-id[\{account-id\}]/gpgkeys |
| Content-Type: application/json |
| |
| { |
| "add": [ |
| "-----BEGIN PGP PUBLIC KEY BLOCK-----\nVersion: GnuPG v1\n\nmQENBFXUpNcBCACv4paCiyKxZ0EcKy8VaWVNkJlNebRBiyw9WxU85wPOq5Gz/3GT\nRQwKqeY0SxVdQT8VNBw2sBe2m6eqcfZ2iKmesSlbXMe15DA7k8Bg4zEpQ0tXNG1L\nhceZDVQ1Xk06T2sgkunaiPsXi82nwN3UWYtDXxX4is5e6xBNL48Jgz4lbqo6+8D5\nvsVYiYMx4AwRkJyt/oA3IZAtSlY8Yd445nY14VPcnsGRwGWTLyZv9gxKHRUppVhQ\nE3o6ePXKEVgmONnQ4CjqmkGwWZvjMF2EPtAxvQLAuFa8Hqtkq5cgfgVkv/Vrcln4\nnQZVoMm3a3f5ODii2tQzNh6+7LL1bpqAmVEtABEBAAG0H0pvaG4gRG9lIDxqb2hu\nLmRvZUBleGFtcGxlLmNvbT6JATgEEwECACIFAlXUpNcCGwMGCwkIBwMCBhUIAgkK\nCwQWAgMBAh4BAheAAAoJEJNQnkuvyKSbfjoH/2OcSQOu1kJ20ndjhgY2yNChm7gd\ntU7TEBbB0TsLeazkrrLtKvrpW5+CRe07ZAG9HOtp3DikwAyrhSxhlYgVsQDhgB8q\nG0tYiZtQ88YyYrncCQ4hwknrcWXVW9bK3V4ZauxzPv3ADSloyR9tMURw5iHCIeL5\nfIw/pLvA3RjPMx4Sfow/bqRCUELua39prGw5Tv8a2ZRFbj2sgP5j8lUFegyJPQ4z\ntJhe6zZvKOzvIyxHO8llLmdrImsXRL9eqroWGs0VYqe6baQpY6xpSjbYK0J5HYcg\nTO+/u80JI+ROTMHE6unGp5Pgh/xIz6Wd34E0lWL1eOyNfGiPLyRWn1d0yZO5AQ0E\nVdSk1wEIALUycrH2HK9zQYdR/KJo1yJJuaextLWsYYn881yDQo/p06U5vXOZ28lG\nAq/Xs96woVZPbgME6FyQzhf20Z2sbr+5bNo3OcEKaKX3Eo/sWwSJ7bXbGLDxMf4S\netfY1WDC+4rTqE30JuC++nQviPRdCcZf0AEgM6TxVhYEMVYwV787YO1IH62EBICM\nSkIONOfnusNZ4Skgjq9OzakOOpROZ4tki5cH/5oSDgdcaGPy1CFDpL9fG6er2zzk\nsw3qCbraqZrrlgpinWcAduiao67U/dV18O6OjYzrt33fTKZ0+bXhk1h1gloC21MQ\nya0CXlnfR/FOQhvuK0RlbR3cMfhZQscAEQEAAYkBHwQYAQIACQUCVdSk1wIbDAAK\nCRCTUJ5Lr8ikm8+QB/4uE+AlvFQFh9W8koPdfk7CJF7wdgZZ2NDtktvLL71WuMK8\nPOmf9f5JtcLCX4iJxGzcWogAR5ed20NgUoHUg7jn9Xm3fvP+kiqL6WqPhjazd89h\nk06v9hPE65kp4wb0fQqDrtWfP1lFGuh77rQgISt3Y4QutDl49vXS183JAfGPxFxx\n8FgGcfNwL2LVObvqCA0WLqeIrQVbniBPFGocE3yA/0W9BB/xtolpKfgMMsqGRMeu\n9oIsNxB2oE61OsqjUtGsnKQi8k5CZbhJaql4S89vwS+efK0R+mo+0N55b0XxRlCS\nfaURgAcjarQzJnG0hUps2GNO/+nM7UyyJAGfHlh5\n=EdXO\n-----END PGP PUBLIC KEY BLOCK-----\n" |
| ], |
| "delete": [ |
| "DEADBEEF", |
| ] |
| }' |
| ---- |
| |
| As a response, the modified GPG keys are returned as a map of |
| link:#gpg-key-info[GpgKeyInfo] entities, keyed by ID. Deleted keys are |
| represented by an empty object. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "AFC8A49B": { |
| "fingerprint": "0192 723D 42D1 0C5B 32A6 E1E0 9350 9E4B AFC8 A49B", |
| "user_ids": [ |
| "John Doe \u003cjohn.doe@example.com\u003e" |
| ], |
| "key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\nVersion: BCPG v1.52\n\nmQENBFXUpNcBCACv4paCiyKxZ0EcKy8VaWVNkJlNebRBiyw9WxU85wPOq5Gz/3GT\nRQwKqeY0SxVdQT8VNBw2sBe2m6eqcfZ2iKmesSlbXMe15DA7k8Bg4zEpQ0tXNG1L\nhceZDVQ1Xk06T2sgkunaiPsXi82nwN3UWYtDXxX4is5e6xBNL48Jgz4lbqo6+8D5\nvsVYiYMx4AwRkJyt/oA3IZAtSlY8Yd445nY14VPcnsGRwGWTLyZv9gxKHRUppVhQ\nE3o6ePXKEVgmONnQ4CjqmkGwWZvjMF2EPtAxvQLAuFa8Hqtkq5cgfgVkv/Vrcln4\nnQZVoMm3a3f5ODii2tQzNh6+7LL1bpqAmVEtABEBAAG0H0pvaG4gRG9lIDxqb2hu\nLmRvZUBleGFtcGxlLmNvbT6JATgEEwECACIFAlXUpNcCGwMGCwkIBwMCBhUIAgkK\nCwQWAgMBAh4BAheAAAoJEJNQnkuvyKSbfjoH/2OcSQOu1kJ20ndjhgY2yNChm7gd\ntU7TEBbB0TsLeazkrrLtKvrpW5+CRe07ZAG9HOtp3DikwAyrhSxhlYgVsQDhgB8q\nG0tYiZtQ88YyYrncCQ4hwknrcWXVW9bK3V4ZauxzPv3ADSloyR9tMURw5iHCIeL5\nfIw/pLvA3RjPMx4Sfow/bqRCUELua39prGw5Tv8a2ZRFbj2sgP5j8lUFegyJPQ4z\ntJhe6zZvKOzvIyxHO8llLmdrImsXRL9eqroWGs0VYqe6baQpY6xpSjbYK0J5HYcg\nTO+/u80JI+ROTMHE6unGp5Pgh/xIz6Wd34E0lWL1eOyNfGiPLyRWn1d0" |
| "status": "TRUSTED", |
| "problems": [], |
| } |
| "DEADBEEF": {} |
| } |
| ---- |
| |
| [[delete-gpg-key]] |
| === Delete GPG Key |
| -- |
| 'DELETE /accounts/link:#account-id[\{account-id\}]/gpgkeys/link:#gpg-key-id[\{gpg-key-id\}]' |
| -- |
| |
| Deletes a GPG key of a user. |
| |
| .Request |
| ---- |
| DELETE /accounts/self/gpgkeys/AFC8A49B 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 basic authentication: |
| |
| .Request |
| ---- |
| GET /a/accounts/self/capabilities HTTP/1.0 |
| Authorization: Basic ABCDECF.. |
| ---- |
| |
| .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, |
| "viewPlugins": 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: Basic ABCDEF... |
| ---- |
| |
| .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 |
| |
| )]}' |
| [ |
| { |
| "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" |
| }, |
| { |
| "id": "834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7", |
| "url": "#/admin/groups/uuid-834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7", |
| "options": { |
| "visible_to_all": true, |
| }, |
| "group_id": 6, |
| "owner_id": "834ec36dd5e0ed21a2ff5d7e2255da082d63bbd7" |
| }, |
| { |
| "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-user-preferences]] |
| === Get User Preferences |
| -- |
| 'GET /accounts/link:#account-id[\{account-id\}]/preferences' |
| -- |
| |
| Retrieves the user's preferences. |
| |
| .Request |
| ---- |
| GET /a/accounts/self/preferences HTTP/1.0 |
| ---- |
| |
| As result the account preferences of the user are returned as a |
| link:#preferences-info[PreferencesInfo] entity. |
| |
| Users may only retrieve the preferences for their own account, |
| unless they are an |
| link:access-control.html#administrators[Administrator] or a member |
| of a group that is granted the |
| link:access-control.html#capability_modifyAccount[ModifyAccount] |
| capability, in which case they can retrieve the preferences for |
| any account. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "changes_per_page": 25, |
| "show_site_header": true, |
| "use_flash_clipboard": true, |
| "download_command": "CHECKOUT", |
| "date_format": "STD", |
| "time_format": "HHMM_12", |
| "diff_view": "SIDE_BY_SIDE", |
| "size_bar_in_change_table": true, |
| "review_category_strategy": "ABBREV", |
| "mute_common_path_prefixes": true, |
| "publish_comments_on_push": true, |
| "work_in_progress_by_default": true, |
| "default_base_for_merges": "FIRST_PARENT", |
| "my": [ |
| { |
| "url": "#/dashboard/self", |
| "name": "Changes" |
| }, |
| { |
| "url": "#/q/has:draft", |
| "name": "Draft Comments" |
| }, |
| { |
| "url": "#/q/is:watched+is:open", |
| "name": "Watched Changes" |
| }, |
| { |
| "url": "#/q/is:starred", |
| "name": "Starred Changes" |
| }, |
| { |
| "url": "#/groups/self", |
| "name": "Groups" |
| }, |
| change_table: [] |
| ] |
| } |
| ---- |
| |
| [[set-user-preferences]] |
| === Set User Preferences |
| -- |
| 'PUT /accounts/link:#account-id[\{account-id\}]/preferences' |
| -- |
| |
| Sets the user's preferences. |
| |
| The new preferences must be provided in the request body as a |
| link:#preferences-input[PreferencesInput] entity. |
| |
| .Request |
| ---- |
| PUT /a/accounts/self/preferences HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "changes_per_page": 50, |
| "show_site_header": true, |
| "use_flash_clipboard": true, |
| "expand_inline_diffs": true, |
| "download_command": "CHECKOUT", |
| "date_format": "STD", |
| "time_format": "HHMM_12", |
| "size_bar_in_change_table": true, |
| "review_category_strategy": "NAME", |
| "diff_view": "SIDE_BY_SIDE", |
| "mute_common_path_prefixes": true, |
| "my": [ |
| { |
| "url": "#/dashboard/self", |
| "name": "Changes" |
| }, |
| { |
| "url": "#/q/has:draft", |
| "name": "Draft Comments" |
| }, |
| { |
| "url": "#/q/is:watched+is:open", |
| "name": "Watched Changes" |
| }, |
| { |
| "url": "#/q/is:starred", |
| "name": "Starred Changes" |
| }, |
| { |
| "url": "#/groups/self", |
| "name": "Groups" |
| } |
| ], |
| "change_table": [ |
| "Subject", |
| "Owner" |
| ] |
| } |
| ---- |
| |
| As result the new preferences of the user are returned as a |
| link:#preferences-info[PreferencesInfo] entity. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| { |
| "changes_per_page": 50, |
| "show_site_header": true, |
| "use_flash_clipboard": true, |
| "expand_inline_diffs": true, |
| "download_command": "CHECKOUT", |
| "date_format": "STD", |
| "time_format": "HHMM_12", |
| "size_bar_in_change_table": true, |
| "review_category_strategy": "NAME", |
| "diff_view": "SIDE_BY_SIDE", |
| "publish_comments_on_push": true, |
| "work_in_progress_by_default": true, |
| "mute_common_path_prefixes": true, |
| "my": [ |
| { |
| "url": "#/dashboard/self", |
| "name": "Changes" |
| }, |
| { |
| "url": "#/q/has:draft", |
| "name": "Draft Comments" |
| }, |
| { |
| "url": "#/q/is:watched+is:open", |
| "name": "Watched Changes" |
| }, |
| { |
| "url": "#/q/is:starred", |
| "name": "Starred Changes" |
| }, |
| { |
| "url": "#/groups/self", |
| "name": "Groups" |
| } |
| ], |
| "change_table": [ |
| "Subject", |
| "Owner" |
| ] |
| } |
| ---- |
| |
| [[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, |
| "theme": "DEFAULT", |
| "ignore_whitespace": "IGNORE_ALL", |
| "intraline_difference": true, |
| "line_length": 100, |
| "cursor_blink_rate": 500, |
| "show_tabs": true, |
| "show_whitespace_errors": true, |
| "syntax_highlighting": true, |
| "tab_size": 8, |
| "font_size": 12 |
| } |
| ---- |
| |
| [[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 |
| ---- |
| PUT /a/accounts/self/preferences.diff HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "context": 10, |
| "theme": "ECLIPSE", |
| "ignore_whitespace": "IGNORE_ALL", |
| "intraline_difference": true, |
| "line_length": 100, |
| "cursor_blink_rate": 500, |
| "show_line_endings": true, |
| "show_tabs": true, |
| "show_whitespace_errors": true, |
| "syntax_highlighting": true, |
| "tab_size": 8, |
| "font_size": 12 |
| } |
| ---- |
| |
| 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, |
| "theme": "ECLIPSE", |
| "ignore_whitespace": "IGNORE_ALL", |
| "intraline_difference": true, |
| "line_length": 100, |
| "show_line_endings": true, |
| "show_tabs": true, |
| "show_whitespace_errors": true, |
| "syntax_highlighting": true, |
| "tab_size": 8, |
| "font_size": 12 |
| } |
| ---- |
| |
| [[get-edit-preferences]] |
| === Get Edit Preferences |
| -- |
| 'GET /accounts/link:#account-id[\{account-id\}]/preferences.edit' |
| -- |
| |
| Retrieves the edit preferences of a user. |
| |
| .Request |
| ---- |
| GET /a/accounts/self/preferences.edit HTTP/1.0 |
| ---- |
| |
| As result the edit preferences of the user are returned as a |
| link:#edit-preferences-info[EditPreferencesInfo] entity. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json;charset=UTF-8 |
| |
| )]}' |
| { |
| "theme": "ECLIPSE", |
| "key_map_type": "VIM", |
| "tab_size": 4, |
| "line_length": 80, |
| "indent_unit": 2, |
| "cursor_blink_rate": 530, |
| "hide_top_menu": true, |
| "show_whitespace_errors": true, |
| "hide_line_numbers": true, |
| "match_brackets": true, |
| "line_wrapping": false, |
| "indent_with_tabs": false, |
| "auto_close_brackets": true |
| } |
| ---- |
| |
| [[set-edit-preferences]] |
| === Set Edit Preferences |
| -- |
| 'PUT /accounts/link:#account-id[\{account-id\}]/preferences.edit' |
| -- |
| |
| Sets the edit preferences of a user. |
| |
| The new edit preferences must be provided in the request body as a |
| link:#edit-preferences-info[EditPreferencesInfo] entity. |
| |
| .Request |
| ---- |
| PUT /a/accounts/self/preferences.edit HTTP/1.0 |
| Content-Type: application/json;charset=UTF-8 |
| |
| { |
| "theme": "ECLIPSE", |
| "key_map_type": "VIM", |
| "tab_size": 4, |
| "line_length": 80, |
| "indent_unit": 2, |
| "cursor_blink_rate": 530, |
| "hide_top_menu": true, |
| "show_tabs": true, |
| "show_whitespace_errors": true, |
| "syntax_highlighting": true, |
| "hide_line_numbers": true, |
| "match_brackets": true, |
| "line_wrapping": false, |
| "auto_close_brackets": true |
| } |
| ---- |
| |
| As result the new edit preferences of the user are returned as a |
| link:#edit-preferences-info[EditPreferencesInfo] entity. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json;charset=UTF-8 |
| |
| )]}' |
| { |
| "theme": "ECLIPSE", |
| "key_map_type": "VIM", |
| "tab_size": 4, |
| "line_length": 80, |
| "cursor_blink_rate": 530, |
| "hide_top_menu": true, |
| "show_whitespace_errors": true, |
| "hide_line_numbers": true, |
| "match_brackets": true, |
| "auto_close_brackets": true |
| } |
| ---- |
| |
| [[get-watched-projects]] |
| === Get Watched Projects |
| -- |
| 'GET /accounts/link:#account-id[\{account-id\}]/watched.projects' |
| -- |
| |
| Retrieves all projects a user is watching. |
| |
| .Request |
| ---- |
| GET /a/accounts/self/watched.projects HTTP/1.0 |
| ---- |
| |
| As result the watched projects of the user are returned as a list of |
| link:#project-watch-info[ProjectWatchInfo] entities. |
| The result is sorted by project name in ascending order. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| [ |
| { |
| "project": "Test Project 1", |
| "notify_new_changes": true, |
| "notify_new_patch_sets": true, |
| "notify_all_comments": true, |
| }, |
| { |
| "project": "Test Project 2", |
| "filter": "branch:experimental", |
| "notify_all_comments": true, |
| "notify_submitted_changes": true, |
| "notify_abandoned_changes": true |
| } |
| ] |
| ---- |
| |
| [[set-watched-projects]] |
| === Add/Update a List of Watched Project Entities |
| -- |
| 'POST /accounts/link:#account-id[\{account-id\}]/watched.projects' |
| -- |
| |
| Add new projects to watch or update existing watched projects. |
| Projects that are already watched by a user will be updated with |
| the provided configuration. All other projects in the request |
| will be watched using the provided configuration. The posted body |
| can contain link:#project-watch-info[ProjectWatchInfo] entities. |
| Omitted boolean values will be set to false. |
| |
| .Request |
| ---- |
| POST /a/accounts/self/watched.projects HTTP/1.0 |
| Content-Type: application/json;charset=UTF-8 |
| |
| [ |
| { |
| "project": "Test Project 1", |
| "notify_new_changes": true, |
| "notify_new_patch_sets": true, |
| "notify_all_comments": true, |
| } |
| ] |
| ---- |
| |
| As result the watched projects of the user are returned as a list of |
| link:#project-watch-info[ProjectWatchInfo] entities. |
| The result is sorted by project name in ascending order. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| [ |
| { |
| "project": "Test Project 1", |
| "notify_new_changes": true, |
| "notify_new_patch_sets": true, |
| "notify_all_comments": true, |
| }, |
| { |
| "project": "Test Project 2", |
| "notify_new_changes": true, |
| "notify_new_patch_sets": true, |
| "notify_all_comments": true, |
| } |
| ] |
| ---- |
| |
| [[delete-watched-projects]] |
| === Delete Watched Projects |
| -- |
| 'POST /accounts/link:#account-id[\{account-id\}]/watched.projects:delete' |
| -- |
| |
| Projects posted to this endpoint will no longer be watched. The posted body |
| can contain a list of link:#project-watch-info[ProjectWatchInfo] entities. |
| |
| .Request |
| ---- |
| POST /a/accounts/self/watched.projects:delete HTTP/1.0 |
| Content-Type: application/json;charset=UTF-8 |
| |
| [ |
| { |
| "project": "Test Project 1", |
| "filter": "branch:master" |
| } |
| ] |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| [[get-account-external-ids]] |
| === Get Account External IDs |
| -- |
| 'GET /accounts/link:#account-id[\{account-id\}]/external.ids' |
| -- |
| |
| Retrieves the external ids of a user account. |
| |
| .Request |
| ---- |
| GET /a/accounts/self/external.ids HTTP/1.0 |
| ---- |
| |
| As result the external ids of the user are returned as a list of |
| link:#account-external-id-info[AccountExternalIdInfo] entities. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| [ |
| { |
| "identity": "username:john", |
| "email": "john.doe@example.com", |
| "trusted": true |
| } |
| ] |
| ---- |
| |
| [[delete-account-external-ids]] |
| === Delete Account External IDs |
| -- |
| 'POST /accounts/link:#account-id[\{account-id\}]/external.ids:delete' |
| -- |
| |
| Delete a list of external ids for a user account. The target external ids must |
| be provided as a list in the request body. |
| |
| Only external ids belonging to the caller may be deleted. |
| |
| .Request |
| ---- |
| POST /a/accounts/self/external.ids:delete HTTP/1.0 |
| Content-Type: application/json;charset=UTF-8 |
| |
| [ |
| "mailto:john.doe@example.com" |
| ] |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| [[default-star-endpoints]] |
| == Default Star Endpoints |
| |
| [[get-changes-with-default-star]] |
| === Get Changes With Default Star |
| -- |
| 'GET /accounts/link:#account-id[\{account-id\}]/starred.changes' |
| -- |
| |
| Gets the changes that were starred with the default star 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 |
| |
| )]}' |
| [ |
| { |
| "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", |
| "starred": true, |
| "stars": [ |
| "star" |
| ], |
| "mergeable": true, |
| "submittable": false, |
| "insertions": 145, |
| "deletions": 12, |
| "_number": 3965, |
| "owner": { |
| "name": "John Doe" |
| } |
| } |
| ] |
| ---- |
| |
| [[star-change]] |
| === Put Default Star On Change |
| -- |
| 'PUT /accounts/link:#account-id[\{account-id\}]/starred.changes/link:rest-api-changes.html#change-id[\{change-id\}]' |
| -- |
| |
| Star a change with the default label. Changes starred with the default |
| label 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]] |
| === Remove Default Star From Change |
| -- |
| 'DELETE /accounts/link:#account-id[\{account-id\}]/starred.changes/link:rest-api-changes.html#change-id[\{change-id\}]' |
| -- |
| |
| Remove the default star label from a change. This stops notifications. |
| |
| .Request |
| ---- |
| DELETE /a/accounts/self/starred.changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940 HTTP/1.0 |
| ---- |
| |
| .Response |
| ---- |
| HTTP/1.1 204 No Content |
| ---- |
| |
| [[star-endpoints]] |
| == Star Endpoints |
| |
| [[get-starred-changes]] |
| === Get Starred Changes |
| -- |
| 'GET /accounts/link:#account-id[\{account-id\}]/stars.changes' |
| -- |
| |
| Gets the changes that were starred with any label by the identified |
| user account. This URL endpoint is functionally identical to the |
| changes query `GET /changes/?q=has:stars`. The result is a list of |
| link:rest-api-changes.html#change-info[ChangeInfo] entities. |
| |
| .Request |
| ---- |
| GET /a/accounts/self/stars.changes |
| ---- |
| |
| .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", |
| "stars": [ |
| "ignore", |
| "risky" |
| ], |
| "mergeable": true, |
| "submittable": false, |
| "insertions": 145, |
| "deletions": 12, |
| "_number": 3965, |
| "owner": { |
| "name": "John Doe" |
| } |
| } |
| ] |
| ---- |
| |
| [[get-stars]] |
| === Get Star Labels From Change |
| -- |
| 'GET /accounts/link:#account-id[\{account-id\}]/stars.changes/link:rest-api-changes.html#change-id[\{change-id\}]' |
| -- |
| |
| Get star labels from a change. |
| |
| .Request |
| ---- |
| GET /a/accounts/self/stars.changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940 HTTP/1.0 |
| ---- |
| |
| As response the star labels that the user applied on the change are |
| returned. The labels are lexicographically sorted. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| [ |
| "blue", |
| "green", |
| "red" |
| ] |
| ---- |
| |
| [[set-stars]] |
| === Update Star Labels On Change |
| -- |
| 'POST /accounts/link:#account-id[\{account-id\}]/stars.changes/link:rest-api-changes.html#change-id[\{change-id\}]' |
| -- |
| |
| Update star labels on a change. The star labels to be added/removed |
| must be specified in the request body as link:#stars-input[StarsInput] |
| entity. Starred changes are returned for the search query `has:stars`. |
| |
| .Request |
| ---- |
| POST /a/accounts/self/stars.changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940 HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "add": [ |
| "blue", |
| "red" |
| ], |
| "remove": [ |
| "yellow" |
| ] |
| } |
| ---- |
| |
| As response the star labels that the user applied on the change are |
| returned. The labels are lexicographically sorted. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| [ |
| "blue", |
| "green", |
| "red" |
| ] |
| ---- |
| |
| [[list-contributor-agreements]] |
| === List Contributor Agreements |
| -- |
| 'GET /accounts/link:#account-id[\{account-id\}]/agreements' |
| -- |
| |
| Gets a list of the user's signed contributor agreements. |
| |
| .Request |
| ---- |
| GET /a/accounts/self/agreements HTTP/1.0 |
| ---- |
| |
| As response the user's signed agreements are returned as a list |
| of link:#contributor-agreement-info[ContributorAgreementInfo] entities. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| [ |
| { |
| "name": "Individual", |
| "description": "If you are going to be contributing code on your own, this is the one you want. You can sign this one online.", |
| "url": "static/cla_individual.html" |
| } |
| ] |
| ---- |
| |
| [[sign-contributor-agreement]] |
| === Sign Contributor Agreement |
| -- |
| 'PUT /accounts/link:#account-id[\{account-id\}]/agreements' |
| -- |
| |
| Signs a contributor agreement. |
| |
| The contributor agreement must be provided in the request body as |
| a link:#contributor-agreement-input[ContributorAgreementInput]. |
| |
| .Request |
| ---- |
| PUT /accounts/self/agreements HTTP/1.0 |
| Content-Type: application/json; charset=UTF-8 |
| |
| { |
| "name": "Individual" |
| } |
| ---- |
| |
| As response the contributor agreement name is returned. |
| |
| .Response |
| ---- |
| HTTP/1.1 200 OK |
| Content-Disposition: attachment |
| Content-Type: application/json; charset=UTF-8 |
| |
| )]}' |
| "Individual" |
| ---- |
| |
| [[index-account]] |
| === Index Account |
| -- |
| 'POST /accounts/link:#account-id[\{account-id\}]/index' |
| -- |
| |
| Adds or updates the account in the secondary index. |
| |
| .Request |
| ---- |
| POST /accounts/1000096/index 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. |
| |
| [[gpg-key-id]] |
| === \{gpg-key-id\} |
| A GPG key identifier, either the 8-character hex key reported by |
| `gpg --list-keys`, or the 40-character hex fingerprint (whitespace is |
| ignored) reported by `gpg --list-keys --with-fingerprint`. |
| |
| |
| [[json-entities]] |
| == JSON Entities |
| |
| [[account-detail-info]] |
| === AccountDetailInfo |
| The `AccountDetailInfo` entity contains detailed information about an |
| account. |
| |
| `AccountDetailInfo` has the same fields as link:#account-info[ |
| AccountInfo]. In addition `AccountDetailInfo` has the following fields: |
| |
| [options="header",cols="1,^1,5"] |
| |================================= |
| |Field Name ||Description |
| |`registered_on` || |
| The link:rest-api.html#timestamp[timestamp] of when the account was |
| registered. |
| |`inactive` |not set if `false`| |
| Whether the account is inactive. |
| |================================= |
| |
| [[account-external-id-info]] |
| === AccountExternalIdInfo |
| The `AccountExternalIdInfo` entity contains information for an external id of |
| an account. |
| |
| [options="header",cols="1,^1,5"] |
| |============================ |
| |Field Name ||Description |
| |`identity` ||The account external id. |
| |`email` |optional|The email address for the external id. |
| |`trusted` |not set if `false`| |
| Whether the external id is trusted. |
| |`can_delete` |not set if `false`| |
| Whether the external id can be deleted by the calling user. |
| |============================ |
| |
| [[account-info]] |
| === AccountInfo |
| The `AccountInfo` entity contains information about an account. |
| |
| [options="header",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 detailed account information is requested. + |
| See option link:rest-api-changes.html#detailed-accounts[ |
| DETAILED_ACCOUNTS] for change queries + |
| and option link:#details[DETAILS] for account queries. |
| |`email` |optional| |
| The email address the user prefers to be contacted through. + |
| Only set if detailed account information is requested. + |
| See option link:rest-api-changes.html#detailed-accounts[ |
| DETAILED_ACCOUNTS] for change queries + |
| and options link:#details[DETAILS] and link:#all-emails[ |
| ALL_EMAILS] for account queries. |
| |`secondary_emails`|optional| |
| A list of the secondary email addresses of the user. + |
| Only set for account queries when the link:#all-emails[ALL_EMAILS] |
| option is set. |
| |`username` |optional|The username of the user. + |
| Only set if detailed account information is requested. + |
| See option link:rest-api-changes.html#detailed-accounts[ |
| DETAILED_ACCOUNTS] for change queries + |
| and option link:#details[DETAILS] for account queries. |
| |`_more_accounts` |optional, not set if `false`| |
| Whether the query would deliver more results if not limited. + |
| Only set on the last account that is returned. |
| |=============================== |
| |
| [[account-input]] |
| === AccountInput |
| The `AccountInput` entity contains information for the creation of |
| a new account. |
| |
| [options="header",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",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. |
| |============================= |
| |
| [[account-status-input]] |
| === AccountStatusInput |
| The `AccountStatusInput` entity contains information for setting a status |
| for an account. |
| |
| [options="header",cols="1,^2,4"] |
| |============================= |
| |Field Name ||Description |
| |`status` |optional|The new status of the account. + |
| If not set or if set to an empty string, the account status is deleted. |
| |============================= |
| |
| [[capability-info]] |
| === CapabilityInfo |
| The `CapabilityInfo` entity contains information about the global |
| capabilities of a user. |
| |
| [options="header",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. |
| |`maintainServer` |not set if `false`|Whether the user has the |
| link:access-control.html#capability_maintainServer[Maintain |
| Server] 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. |
| |`viewAllAccounts` |not set if `false`|Whether the user has the |
| link:access-control.html#capability_viewAllAccounts[View All Accounts] |
| 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. |
| |`viewPlugins` |not set if `false`|Whether the user has the |
| link:access-control.html#capability_viewPlugins[View Plugins] capability. |
| |`viewQueue` |not set if `false`|Whether the user has the |
| link:access-control.html#capability_viewQueue[View Queue] capability. |
| |================================= |
| |
| [[contributor-agreement-info]] |
| === ContributorAgreementInfo |
| |
| The `ContributorAgreementInfo` entity contains information about a |
| contributor agreement. |
| |
| [options="header",cols="1,6"] |
| |================================= |
| |Field Name |Description |
| |`name` |The name of the agreement. |
| |`description` |The description of the agreement. |
| |`url` |The URL of the agreement. |
| |================================= |
| |
| [[contributor-agreement-input]] |
| === ContributorAgreementInput |
| The `ContributorAgreementInput` entity contains information about a |
| new contributor agreement. |
| |
| [options="header",cols="1,6"] |
| |================================= |
| |Field Name |Description |
| |`name` |The name of the agreement. |
| |================================= |
| |
| [[diff-preferences-info]] |
| === DiffPreferencesInfo |
| The `DiffPreferencesInfo` entity contains information about the diff |
| preferences of a user. |
| |
| [options="header",cols="1,^1,5"] |
| |=========================================== |
| |Field Name ||Description |
| |`context` || |
| The number of lines of context when viewing a patch. |
| |`theme` || |
| The CodeMirror theme name in upper case, for example `DEFAULT`. All the themes |
| from the CodeMirror release that Gerrit is using are available. |
| |`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_TRAILING`, |
| `IGNORE_LEADING_AND_TRAILING`, `IGNORE_ALL`. |
| |`intraline_difference` |not set if `false`| |
| Whether intraline differences should be highlighted. |
| |`line_length` || |
| Number of characters that should be displayed in one line. |
| |`cursor_blink_rate` || |
| Half-period in milliseconds used for cursor blinking. |
| Setting it to 0 disables cursor blinking. |
| |`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. |
| |`hide_top_menu` |not set if `false`| |
| If true the top menu header and site header are hidden. |
| |`auto_hide_diff_table_header` |not set if `false`| |
| If true the diff table header is automatically hidden when |
| scrolling down more than half of a page. |
| |`hide_line_numbers` |not set if `false`| |
| If true the line numbers are hidden. |
| |`tab_size` || |
| Number of spaces that should be used to display one tab. |
| |`font_size` || |
| Default font size in pixels for change to be displayed in the diff view. |
| |'hide_empty_pane' |not set if `false`| |
| Whether empty panes should be hidden. The left pane is empty when a |
| file was added; the right pane is empty when a file was deleted. |
| |`match_brackets` |not set if `false`| |
| Whether matching brackets should be highlighted. |
| |`line_wrapping` |not set if `false`| |
| Whether to enable line wrapping or not. |
| |=========================================== |
| |
| [[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",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_TRAILING`, |
| `IGNORE_LEADING_AND_TRAILING`, `IGNORE_ALL`. |
| |`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. |
| |`hide_top_menu` |optional| |
| True if the top menu header and site header should be hidden. |
| |`auto_hide_diff_table_header` |optional| |
| True if the diff table header is automatically hidden when |
| scrolling down more than half of a page. |
| |`hide_line_numbers` |optional| |
| True if the line numbers should be hidden. |
| |`tab_size` |optional| |
| Number of spaces that should be used to display one tab. |
| |`font_size` |optional| |
| Default font size in pixels for change to be displayed in the diff view. |
| |`line_wrapping` |optional| |
| Whether to enable line wrapping or not. |
| |`indent_with_tabs` |optional| |
| Whether to enable indent with tabs or not. |
| |=========================================== |
| |
| [[edit-preferences-info]] |
| === EditPreferencesInfo |
| The `EditPreferencesInfo` entity contains information about the edit |
| preferences of a user. |
| |
| [options="header",cols="1,^1,5"] |
| |=========================================== |
| |Field Name ||Description |
| |`theme` || |
| The CodeMirror theme name in upper case, for example `DEFAULT`. All the themes |
| from the CodeMirror release that Gerrit is using are available. |
| |`key_map_type` || |
| The CodeMirror key map. Currently only a subset of key maps are |
| supported: `DEFAULT`, `EMACS`, `SUBLIME`, `VIM`. |
| |`tab_size` || |
| Number of spaces that should be used to display one tab. |
| |`line_length` || |
| Number of characters that should be displayed per line. |
| |`indent_unit` || |
| Number of spaces that should be used for auto-indent. |
| |`cursor_blink_rate` || |
| Half-period in milliseconds used for cursor blinking. |
| Setting it to 0 disables cursor blinking. |
| |`hide_top_menu` |not set if `false`| |
| If true the top menu header and site header is hidden. |
| |`show_tabs` |not set if `false`| |
| Whether tabs should be shown. |
| |`show_whitespace_errors` |not set if `false`| |
| Whether whitespace errors should be shown. |
| |`syntax_highlighting` |not set if `false`| |
| Whether syntax highlighting should be enabled. |
| |`hide_line_numbers` |not set if `false`| |
| Whether line numbers should be hidden. |
| |`match_brackets` |not set if `false`| |
| Whether matching brackets should be highlighted. |
| |`line_wrapping` |not set if `false`| |
| Whether to enable line wrapping or not. |
| |`indent_with_tabs` |not set if `false`| |
| Whether to indent with tabs or not. |
| |`auto_close_brackets` |not set if `false`| |
| Whether brackets and quotes should be auto-closed during typing. |
| |`show_base` |not set if `false`| |
| Whether to show the inline edit base version or not. |
| |=========================================== |
| |
| [[email-info]] |
| === EmailInfo |
| The `EmailInfo` entity contains information about an email address of a |
| user. |
| |
| [options="header",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",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. |
| |============================== |
| |
| [[gpg-key-info]] |
| === GpgKeyInfo |
| The `GpgKeyInfo` entity contains information about a GPG public key. |
| |
| [options="header",cols="1,^1,5"] |
| |======================== |
| |Field Name ||Description |
| |`id` |Not set in map context|The 8-char hex GPG key ID. |
| |`fingerprint`|Not set for deleted keys|The 40-char (plus spaces) hex GPG key fingerprint. |
| |`user_ids` |Not set for deleted keys| |
| link:https://tools.ietf.org/html/rfc4880#section-5.11[OpenPGP User IDs] |
| associated with the public key. |
| |`key` |Not set for deleted keys|ASCII armored public key material. |
| |`status` |Not set for deleted keys| |
| The result of server-side checks on the key; one of `BAD`, `OK`, or `TRUSTED`. |
| `BAD` keys have serious problems and should not be used. If a key is `OK, |
| inspecting only that key found no problems, but the system does not fully trust |
| the key's origin. A `TRUSTED` key is valid, and the system knows enough about |
| the key and its origin to trust it. |
| |`problems` |Not set for deleted keys| |
| A list of human-readable problem strings found in the course of checking whether |
| the key is valid and trusted. |
| |======================== |
| |
| [[gpg-keys-input]] |
| === GpgKeysInput |
| The `GpgKeysInput` entity contains information for adding/deleting GPG keys. |
| |
| [options="header",cols="1,6"] |
| |======================== |
| |Field Name|Description |
| |`add` |List of ASCII armored public key strings to add. |
| |`delete` |List of link:#gpg-key-id[`\{gpg-key-id\}`]s to delete. |
| |======================== |
| |
| [[http-password-input]] |
| === HttpPasswordInput |
| The `HttpPasswordInput` entity contains information for setting/generating |
| an HTTP password. |
| |
| [options="header",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. |
| |============================ |
| |
| [[oauth-token-info]] |
| === OAuthTokenInfo |
| The `OAuthTokenInfo` entity contains information about an OAuth access token. |
| |
| [options="header",cols="1,^1,5"] |
| |======================== |
| |Field Name ||Description |
| |`username` ||The owner of the OAuth access token. |
| |`resource_host` ||The host of the Gerrit instance. |
| |`access_token` ||The actual token value. |
| |`provider_id` |optional| |
| The identifier of the OAuth provider in the form `plugin-name:provider-name`. |
| |`expires_at` |optional|Time of expiration of this token in milliseconds. |
| |`type` ||The type of the OAuth access token, always `bearer`. |
| |======================== |
| |
| [[preferences-info]] |
| === PreferencesInfo |
| The `PreferencesInfo` entity contains information about a user's preferences. |
| |
| [options="header",cols="1,^1,5"] |
| |============================================ |
| |Field Name ||Description |
| |`changes_per_page` || |
| The number of changes to show on each page. |
| Allowed values are `10`, `25`, `50`, `100`. |
| |`show_site_header` |not set if `false`| |
| Whether the site header should be shown. |
| |`use_flash_clipboard` |not set if `false`| |
| Whether to use the flash clipboard widget. |
| |`expand_inline_diffs` |not set if `false`| |
| Whether to expand diffs inline instead of opening as separate page |
| (PolyGerrit only). |
| |`download_scheme` |optional| |
| The type of download URL the user prefers to use. May be any key from |
| the `schemes` map in |
| link:rest-api-config.html#download-info[DownloadInfo]. |
| |`download_command` || |
| The type of download command the user prefers to use. |
| |`date_format` || |
| The format to display the date in. |
| Allowed values are `STD`, `US`, `ISO`, `EURO`, `UK`. |
| |`time_format` || |
| The format to display the time in. |
| Allowed values are `HHMM_12`, `HHMM_24`. |
| |`relative_date_in_change_table`|not set if `false`| |
| Whether to show relative dates in the changes table. |
| |`diff_view` || |
| The type of diff view to show. |
| Allowed values are `SIDE_BY_SIDE`, `UNIFIED_DIFF`. |
| |`size_bar_in_change_table` |not set if `false`| |
| Whether to show the change sizes as colored bars in the change table. |
| |`legacycid_in_change_table` |not set if `false`| |
| Whether to show change number in the change table. |
| |`review_category_strategy` || |
| The strategy used to displayed info in the review category column. |
| Allowed values are `NONE`, `NAME`, `EMAIL`, `USERNAME`, `ABBREV`. |
| |`mute_common_path_prefixes` |not set if `false`| |
| Whether to mute common path prefixes in file names in the file table. |
| |`signed_off_by` |not set if `false`| |
| Whether to insert Signed-off-by footer in changes created with the |
| inline edit feature. |
| |`my` || |
| The menu items of the `MY` top menu as a list of |
| link:rest-api-config.html#top-menu-item-info[TopMenuItemInfo] entities. |
| |`change_table` || |
| The columns to display in the change table (PolyGerrit only). The default is |
| empty, which will default columns as determined by the frontend. |
| |`url_aliases` |optional| |
| A map of URL path pairs, where the first URL path is an alias for the |
| second URL path. |
| |`email_strategy` || |
| The type of email strategy to use. On `ENABLED`, the user will receive emails |
| from Gerrit. On `CC_ON_OWN_COMMENTS` the user will also receive emails for |
| their own comments. On `DISABLED` the user will not receive any email |
| notifications from Gerrit. |
| Allowed values are `ENABLED`, `CC_ON_OWN_COMMENTS`, `DISABLED`. |
| |`default_base_for_merges` || |
| The base which should be pre-selected in the 'Diff Against' drop-down |
| list when the change screen is opened for a merge commit. |
| Allowed values are `AUTO_MERGE` and `FIRST_PARENT`. |
| |`publish_comments_on_push` |not set if `false`| |
| Whether to link:user-upload.html#publish-comments[publish draft comments] on |
| push by default. |
| |`work_in_progress_by_default` |not set if `false`| |
| Whether to link:user-upload.html#wip[set work-in-progress] on |
| push or on create changes online by default. |
| |============================================ |
| |
| [[preferences-input]] |
| === PreferencesInput |
| The `PreferencesInput` entity contains information for setting the |
| user preferences. Fields which are not set will not be updated. |
| |
| [options="header",cols="1,^1,5"] |
| |============================================ |
| |Field Name ||Description |
| |`changes_per_page` |optional| |
| The number of changes to show on each page. |
| Allowed values are `10`, `25`, `50`, `100`. |
| |`show_site_header` |optional| |
| Whether the site header should be shown. |
| |`use_flash_clipboard` |optional| |
| Whether to use the flash clipboard widget. |
| |`expand_inline_diffs` |not set if `false`| |
| Whether to expand diffs inline instead of opening as separate page |
| (PolyGerrit only). |
| |`download_scheme` |optional| |
| The type of download URL the user prefers to use. |
| |`download_command` |optional| |
| The type of download command the user prefers to use. |
| |`date_format` |optional| |
| The format to display the date in. |
| Allowed values are `STD`, `US`, `ISO`, `EURO`, `UK`. |
| |`time_format` |optional| |
| The format to display the time in. |
| Allowed values are `HHMM_12`, `HHMM_24`. |
| |`relative_date_in_change_table`|optional| |
| Whether to show relative dates in the changes table. |
| |`diff_view` |optional| |
| The type of diff view to show. |
| Allowed values are `SIDE_BY_SIDE`, `UNIFIED_DIFF`. |
| |`size_bar_in_change_table` |optional| |
| Whether to show the change sizes as colored bars in the change table. |
| |`legacycid_in_change_table` |optional| |
| Whether to show change number in the change table. |
| |`review_category_strategy` |optional| |
| The strategy used to displayed info in the review category column. |
| Allowed values are `NONE`, `NAME`, `EMAIL`, `USERNAME`, `ABBREV`. |
| |`mute_common_path_prefixes` |optional| |
| Whether to mute common path prefixes in file names in the file table. |
| |`signed_off_by` |optional| |
| Whether to insert Signed-off-by footer in changes created with the |
| inline edit feature. |
| |`my` |optional| |
| The menu items of the `MY` top menu as a list of |
| link:rest-api-config.html#top-menu-item-info[TopMenuItemInfo] entities. |
| |`change_table` || |
| The columns to display in the change table (PolyGerrit only). The default is |
| empty, which will default columns as determined by the frontend. |
| |`url_aliases` |optional| |
| A map of URL path pairs, where the first URL path is an alias for the |
| second URL path. |
| |`email_strategy` |optional| |
| The type of email strategy to use. On `ENABLED`, the user will receive emails |
| from Gerrit. On `CC_ON_OWN_COMMENTS` the user will also receive emails for |
| their own comments. On `DISABLED` the user will not receive any email |
| notifications from Gerrit. |
| Allowed values are `ENABLED`, `CC_ON_OWN_COMMENTS`, `DISABLED`. |
| |`default_base_for_merges` |optional| |
| The base which should be pre-selected in the 'Diff Against' drop-down |
| list when the change screen is opened for a merge commit. |
| Allowed values are `AUTO_MERGE` and `FIRST_PARENT`. |
| |============================================ |
| |
| [[query-limit-info]] |
| === QueryLimitInfo |
| The `QueryLimitInfo` entity contains information about the |
| link:access-control.html#capability_queryLimit[Query Limit] of a user. |
| |
| [options="header",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",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. |
| |============================= |
| |
| [[stars-input]] |
| === StarsInput |
| The `StarsInput` entity contains star labels that should be added to |
| or removed from a change. |
| |
| [options="header",cols="1,^1,5"] |
| |======================== |
| |Field Name ||Description |
| |`add` |optional|List of labels to add to the change. |
| |`remove` |optional|List of labels to remove from the change. |
| |======================== |
| |
| [[username-input]] |
| === UsernameInput |
| The `UsernameInput` entity contains information for setting the |
| username for an account. |
| |
| [options="header",cols="1,6"] |
| |======================= |
| |Field Name |Description |
| |`username` |The new username of the account. |
| |======================= |
| |
| [[project-watch-info]] |
| === ProjectWatchInfo |
| The `WatchedProjectsInfo` entity contains information about a project watch |
| for a user. |
| |
| [options="header",cols="1,^1,5"] |
| |======================= |
| |Field Name | |Description |
| |`project` | |The name of the project. |
| |`filter` |optional|A filter string to be applied to the project. |
| |`notify_new_changes` |optional|Notify on new changes. |
| |`notify_new_patch_sets` |optional|Notify on new patch sets. |
| |`notify_all_comments` |optional|Notify on comments. |
| |`notify_submitted_changes` |optional|Notify on submitted changes. |
| |`notify_abandoned_changes` |optional|Notify on abandoned changes. |
| |======================= |
| |
| GERRIT |
| ------ |
| Part of link:index.html[Gerrit Code Review] |
| |
| SEARCHBOX |
| --------- |
