This page describes the config related REST endpoints. Please also take note of the general information on the REST API.
GET /config/server/version
Returns the version of the Gerrit server.
Request.
GET /config/server/version HTTP/1.0
Response.
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 )]}' "2.7"
GET /config/server/info
Returns the information about the Gerrit server configuration.
Request.
GET /config/server/info HTTP/1.0
As result a ServerInfo entity is returned.
Response.
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 )]}' { "accounts": { "visibility": "ALL" }, "auth": { "auth_type": "LDAP", "use_contributor_agreements": true, "contributor_agreements": [ { "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" } ], "editable_account_fields": [ "FULL_NAME", "REGISTER_NEW_EMAIL" ] }, "download": { "schemes": { "anonymous http": { "url": "http://gerrithost:8080/${project}", "commands": { "Checkout": "git fetch http://gerrithost:8080/${project} ${ref} \u0026\u0026 git checkout FETCH_HEAD", "Format Patch": "git fetch http://gerrithost:8080/${project} ${ref} \u0026\u0026 git format-patch -1 --stdout FETCH_HEAD", "Pull": "git pull http://gerrithost:8080/${project} ${ref}", "Cherry Pick": "git fetch http://gerrithost:8080/${project} ${ref} \u0026\u0026 git cherry-pick FETCH_HEAD" }, "clone_commands": { "Clone": "git clone http://gerrithost:8080/${project}", "Clone with commit-msg hook": "git clone http://gerrithost:8080/${project} \u0026\u0026 scp -p -P 29418 jdoe@gerrithost:hooks/commit-msg ${project}/.git/hooks/" } }, "http": { "url": "http://jdoe@gerrithost:8080/${project}", "is_auth_required": true, "is_auth_supported": true, "commands": { "Checkout": "git fetch http://jdoe@gerrithost:8080/${project} ${ref} \u0026\u0026 git checkout FETCH_HEAD", "Format Patch": "git fetch http://jdoe@gerrithost:8080/${project} ${ref} \u0026\u0026 git format-patch -1 --stdout FETCH_HEAD", "Pull": "git pull http://jdoe@gerrithost:8080/${project} ${ref}", "Cherry Pick": "git fetch http://jdoe@gerrithost:8080/${project} ${ref} \u0026\u0026 git cherry-pick FETCH_HEAD" }, "clone_commands": { "Clone": "git clone http://jdoe@gerrithost:8080/${project}", "Clone with commit-msg hook": "git clone http://jdoe@gerrithost:8080/${project} \u0026\u0026 scp -p -P 29418 jdoe@gerrithost:hooks/commit-msg ${project}/.git/hooks/" } }, "ssh": { "url": "ssh://jdoe@gerrithost:29418/${project}", "is_auth_required": true, "is_auth_supported": true, "commands": { "Checkout": "git fetch ssh://jdoe@gerrithost:29418/${project} ${ref} \u0026\u0026 git checkout FETCH_HEAD", "Format Patch": "git fetch ssh://jdoe@gerrithost:29418/${project} ${ref} \u0026\u0026 git format-patch -1 --stdout FETCH_HEAD", "Pull": "git pull ssh://jdoe@gerrithost:29418/${project} ${ref}", "Cherry Pick": "git fetch ssh://jdoe@gerrithost:29418/${project} ${ref} \u0026\u0026 git cherry-pick FETCH_HEAD" }, "clone_commands": { "Clone": "git clone ssh://jdoe@gerrithost:29418/${project}", "Clone with commit-msg hook": "git clone ssh://jdoe@gerrithost:29418/${project} \u0026\u0026 scp -p -P 29418 jdoe@gerrithost:hooks/commit-msg ${project}/.git/hooks/" } } }, "archives": [ "tgz", "tar", "tbz2", "txz" ] }, "gerrit": { "all_projects": "All-Projects", "all_users": "All-Users" "doc_search": true, "web_uis": [ "gwt" ] }, "sshd": {}, "suggest": { "from": 0 }, "user": { "anonymous_coward_name": "Anonymous Coward" } }
POST /config/server/check.consistency
Runs consistency checks and returns detected problems.
Input for the consistency checks that should be run must be provided in the request body inside a ConsistencyCheckInput entity.
Request.
POST /config/server/check.consistency HTTP/1.0 Content-Type: application/json; charset=UTF-8 { "check_accounts": {}, "check_account_external_ids": {} }
As result a ConsistencyCheckInfo entity is returned that contains detected consistency problems.
Response.
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 )]}' { "check_accounts_result": { "problems": [ { "status": "ERROR", "message": "Account \u00271000024\u0027 has no external ID for its preferred email \u0027foo.bar@example.com\u0027" } ] } "check_account_external_ids_result": { "problems": [ { "status": "ERROR", "message": "External ID \u0027uuid:ccb8d323-1361-45aa-8874-41987a660c46\u0027 belongs to account that doesn\u0027t exist: 1000012" } ] } }
PUT /config/server/email.confirm
Confirms that the user owns an email address.
The email token must be provided in the request body inside an EmailConfirmationInput entity.
Request.
PUT /config/server/email.confirm HTTP/1.0 Content-Type: application/json; charset=UTF-8 { "token": "Enim+QNbAo6TV8Hur8WwoUypI6apG7qBPvF+bw==$MTAwMDAwNDp0ZXN0QHRlc3QuZGU=" }
The response is “204 No Content
”.
If the token is invalid or if it’s the token of another user the request fails and the response is “422 Unprocessable Entity
”.
GET /config/server/caches/
Lists the caches of the server. Caches defined by plugins are included.
The caller must be a member of a group that is granted one of the following capabilities:
As result a map of CacheInfo entities is returned.
The entries in the map are sorted by cache name.
Request.
GET /config/server/caches/ HTTP/1.0
Response.
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 )]}' { "accounts": { "type": "MEM", "entries": { "mem": 4 }, "average_get": "2.5ms", "hit_ratio": { "mem": 94 } }, "adv_bases": { "type": "MEM", "entries": {}, "hit_ratio": {} }, "change_kind": { "type": "DISK", "entries": { "space": "0.00k" }, "hit_ratio": {} }, "changes": { "type": "MEM", "entries": {}, "hit_ratio": {} }, "conflicts": { "type": "DISK", "entries": { "mem": 2, "disk": 3, "space": "2.75k" }, "hit_ratio": { "mem": 0, "disk": 100 } }, "diff": { "type": "DISK", "entries": { "mem": 177, "disk": 253, "space": "170.97k" }, "average_get": "1.1ms", "hit_ratio": { "mem": 67, "disk": 100 } }, "diff_intraline": { "type": "DISK", "entries": { "mem": 1, "disk": 1, "space": "0.37k" }, "average_get": "6.8ms", "hit_ratio": { "mem": 0 } }, "git_tags": { "type": "DISK", "entries": { "space": "0.00k" }, "hit_ratio": {} }, groups": { "type": "MEM", "entries": { "mem": 27 }, "average_get": "183.2us", "hit_ratio": { "mem": 12 } }, "groups_byinclude": { "type": "MEM", "entries": {}, "hit_ratio": {} }, "groups_byname": { "type": "MEM", "entries": {}, "hit_ratio": {} }, "groups_byuuid": { "type": "MEM", "entries": { "mem": 25 }, "average_get": "173.4us", "hit_ratio": { "mem": 13 } }, "groups_external": { "type": "MEM", "entries": {}, "hit_ratio": {} }, groups_members": { "type": "MEM", "entries": { "mem": 4 }, "average_get": "697.8us", "hit_ratio": { "mem": 82 } }, "permission_sort": { "type": "MEM", "entries": { "mem": 16 }, "hit_ratio": { "mem": 96 } }, "plugin_resources": { "type": "MEM", "entries": { "mem": 2 }, "hit_ratio": { "mem": 83 } }, "project_list": { "type": "MEM", "entries": { "mem": 1 }, "average_get": "18.6ms", "hit_ratio": { "mem": 0 } }, "projects": { "type": "MEM", "entries": { "mem": 35 }, "average_get": "8.6ms", "hit_ratio": { "mem": 99 } }, "quota-repo_size": { "type": "DISK", "entries": { "space": "0.00k" }, "hit_ratio": {} }, "sshkeys": { "type": "MEM", "entries": { "mem": 1 }, "average_get": "3.2ms", "hit_ratio": { "mem": 50 } }, "web_sessions": { "type": "DISK", "entries": { "mem": 1, "disk": 2, "space": "0.78k" }, "hit_ratio": { "mem": 82 } } }
It is possible to get different output formats by specifying the format
option:
LIST
:
Returns the cache names as JSON list.
The cache names are lexicographically sorted.
Request.
GET /config/server/caches/?format=LIST HTTP/1.0
Response.
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 )]}' [ "accounts", "adv_bases", "change_kind", "changes", "conflicts", "diff", "diff_intraline", "git_tags", "groups", "groups_byinclude", "groups_byname", "groups_byuuid", "groups_external", "groups_members", "permission_sort", "plugin_resources", "project_list", "projects", "quota-repo_size", "sshkeys", "web_sessions" ]
TEXT_LIST
:
Returns the cache names as a UTF-8 list that is base64 encoded. The cache names are delimited by \n.
The cache names are lexicographically sorted.
Request.
GET /config/server/caches/?format=TEXT_LIST HTTP/1.0
Response.
HTTP/1.1 200 OK Content-Type: text/plain; charset=UTF-8 YWNjb3VudHMKYW...ViX3Nlc3Npb25z
E.g. this could be used to flush all caches:
for c in $(curl --user jdoe:TNAuLkXsIV7w http://gerrit/a/config/server/caches/?format=TEXT_LIST | base64 -D) do curl --user jdoe:TNAuLkXsIV7w -X POST http://gerrit/a/config/server/caches/$c/flush done
POST /config/server/caches/
Executes a cache operation that is specified in the request body in a CacheOperationInput entity.
Request.
POST /config/server/caches/ HTTP/1.0 Content-Type: application/json; charset=UTF-8 { "operation": "FLUSH_ALL" }
Response.
HTTP/1.1 200 OK
Request.
POST /config/server/caches/ HTTP/1.0 Content-Type: application/json; charset=UTF-8 { "operation": "FLUSH", "caches": [ "projects", "project_list" ] }
Response.
HTTP/1.1 200 OK
GET /config/server/caches/{cache-name}
Retrieves information about a cache.
The caller must be a member of a group that is granted one of the following capabilities:
As result a CacheInfo entity is returned.
Request.
GET /config/server/caches/projects HTTP/1.0
Response.
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 )]}' { "name": "projects", "type": "MEM", "entries": { "mem": 35 }, "average_get": " 8.6ms", "hit_ratio": { "mem": 99 } }
POST /config/server/caches/{cache-name}/flush
Flushes a cache.
The caller must be a member of a group that is granted one of the following capabilities:
Flush Caches (any cache except “web_sessions”)
Maintain Server (any cache including “web_sessions”)
Administrate Server (any cache including “web_sessions”)
Request.
POST /config/server/caches/projects/flush HTTP/1.0
Response.
HTTP/1.1 200 OK
GET /config/server/summary
Retrieves a summary of the current server state.
The caller must be a member of a group that is granted the Administrate Server capability.
The following options are supported:
jvm
:
Includes a JVM summary.
gc
:
Requests a Java garbage collection before computing the information about the Java memory heap.
Request.
GET /config/server/summary?jvm HTTP/1.0
As result a SummaryInfo entity is returned.
Response.
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 )]}' { "task_summary": { "total": 2, "sleeping": 2 }, "mem_summary": { "total": "341.06m", "used": "57.16m", "free": "283.90m", "buffers": "0.00k", "max": "1.67g", } "thread_summary": { "cpus": 8, "threads": 44, "counts": { "HTTP": { "RUNNABLE": 3, "TIMED_WAITING": 2 }, "SSH-Interactive-Worker": { "WAITING": 1 }, "Other": { "WAITING": 10, "RUNNABLE": 2, "TIMED_WAITING": 25 }, "SshCommandStart": { "WAITING": 1 } } }, "jvm_summary": { "vm_vendor": "Oracle Corporation", "vm_name": "Java HotSpot(TM) 64-Bit Server VM", "vm_version": "23.25-b01", "os_name": "Mac OS X", "os_version": "10.8.5", "os_arch": "x86_64", "user": "gerrit", "host": "GERRIT", "current_working_directory": "/Users/gerrit/site", "site": "/Users/gerrit/site" } }
GET /config/server/capabilities
Lists the capabilities that are available in the system. There are two kinds of capabilities: core and plugin-owned capabilities.
As result a map of CapabilityInfo entities is returned.
The entries in the map are sorted by capability ID.
Request.
GET /config/server/capabilities/ HTTP/1.0
Response.
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 )]}' { "accessDatabase": { "id": "accessDatabase", "name": "Access Database" }, "administrateServer": { "id": "administrateServer", "name": "Administrate Server" }, "createAccount": { "id": "createAccount", "name": "Create Account" }, "createGroup": { "id": "createGroup", "name": "Create Group" }, "createProject": { "id": "createProject", "name": "Create Project" }, "emailReviewers": { "id": "emailReviewers", "name": "Email Reviewers" }, "flushCaches": { "id": "flushCaches", "name": "Flush Caches" }, "killTask": { "id": "killTask", "name": "Kill Task" }, "priority": { "id": "priority", "name": "Priority" }, "queryLimit": { "id": "queryLimit", "name": "Query Limit" }, "runGC": { "id": "runGC", "name": "Run Garbage Collection" }, "streamEvents": { "id": "streamEvents", "name": "Stream Events" }, "viewCaches": { "id": "viewCaches", "name": "View Caches" }, "viewConnections": { "id": "viewConnections", "name": "View Connections" }, "viewPlugins": { "id": "viewPlugins", "name": "View Plugins" }, "viewQueue": { "id": "viewQueue", "name": "View Queue" } }
GET /config/server/tasks/
Lists the tasks from the background work queues that the Gerrit daemon is currently performing, or will perform in the near future.
Gerrit contains an internal scheduler, similar to cron, that it uses to queue and dispatch both short and long term tasks.
Tasks that are completed or canceled exit the queue very quickly once they enter this state, but it can be possible to observe tasks in these states.
End-users may see a task only if they can also see the project the task is associated with. Tasks operating on other projects, or that do not have a specific project, are hidden.
The caller must be a member of a group that is granted one of the following capabilities:
As result a list of TaskInfo entities is returned.
The entries in the list are sorted by task state, remaining delay and command.
Request.
GET /config/server/tasks/ HTTP/1.0
Response.
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 )]}' [ { "id": "1e688bea", "state": "SLEEPING", "start_time": "2014-06-11 12:58:51.991000000", "delay": 3453, "command": "Reload Submit Queue" }, { "id": "3e6d4ffa", "state": "SLEEPING", "start_time": "2014-06-11 12:58:51.508000000", "delay": 3287966, "command": "Log File Compressor" } ]
GET /config/server/tasks/{task-id}
Retrieves a task from the background work queue that the Gerrit daemon is currently performing, or will perform in the near future.
End-users may see a task only if they can also see the project the task is associated with. Tasks operating on other projects, or that do not have a specific project, are hidden.
The caller must be a member of a group that is granted one of the following capabilities:
As result a TaskInfo entity is returned.
Request.
GET /config/server/tasks/1e688bea HTTP/1.0
Response.
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 )]}' { "id": "1e688bea", "state": "SLEEPING", "start_time": "2014-06-11 12:58:51.991000000", "delay": 3453, "command": "Reload Submit Queue" }
DELETE /config/server/tasks/{task-id}
Kills a task from the background work queue that the Gerrit daemon is currently performing, or will perform in the near future.
The caller must be a member of a group that is granted one of the following capabilities:
End-users may see a task only if they can also see the project the task is associated with. Tasks operating on other projects, or that do not have a specific project, are hidden.
Members of a group granted one of the following capabilities may view all tasks:
Request.
DELETE /config/server/tasks/1e688bea HTTP/1.0
Response.
HTTP/1.1 204 No Content
GET /config/server/top-menus
Returns the list of additional top menu entries.
Request.
GET /config/server/top-menus HTTP/1.0
As response a list of the additional top menu entries as TopMenuEntryInfo entities is returned.
Response.
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 )]}' [ { "name": "Top Menu Entry", "items": [ { "url": "http://gerrit.googlecode.com/", "name": "Gerrit", "target": "_blank" } ] } ]
GET /config/server/preferences
Returns the default user preferences for the server.
Request.
GET /a/config/server/preferences HTTP/1.0
As response a PreferencesInfo is returned.
Response.
HTTP/1.1 200 OK 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": "NONE", "mute_common_path_prefixes": true, "publish_comments_on_push": true, "my": [ { "url": "#/dashboard/self", "name": "Changes" }, { "url": "#/q/has:draft", "name": "Draft Comments" }, { "url": "#/q/has:edit", "name": "Edits" }, { "url": "#/q/is:watched+is:open", "name": "Watched Changes" }, { "url": "#/q/is:starred", "name": "Starred Changes" }, { "url": "#/groups/self", "name": "Groups" } ], "email_strategy": "ENABLED" }
PUT /config/server/preferences
Sets the default user preferences for the server.
The new user preferences must be provided in the request body as a PreferencesInput entity.
To be allowed to set default preferences, a user must be a member of a group that is granted the Administrate Server capability.
Request.
PUT /a/config/server/preferences HTTP/1.0 Content-Type: application/json; charset=UTF-8 { "changes_per_page": 50 }
As response a PreferencesInfo is returned.
Response.
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 )]}' { "changes_per_page": 50, "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": "NONE", "mute_common_path_prefixes": true, "publish_comments_on_push": true, "my": [ { "url": "#/dashboard/self", "name": "Changes" }, { "url": "#/q/has:draft", "name": "Draft Comments" }, { "url": "#/q/has:edit", "name": "Edits" }, { "url": "#/q/is:watched+is:open", "name": "Watched Changes" }, { "url": "#/q/is:starred", "name": "Starred Changes" }, { "url": "#/groups/self", "name": "Groups" } ], "email_strategy": "ENABLED" }
GET /config/server/preferences.diff
Returns the default diff preferences for the server.
Request.
GET /a/config/server/preferences.diff HTTP/1.0
As response a DiffPreferencesInfo is returned.
Response.
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 )]}' { "context": 10, "tab_size": 8, "line_length": 100, "cursor_blink_rate": 0, "intraline_difference": true, "show_line_endings": true, "show_tabs": true, "show_whitespace_errors": true, "syntax_highlighting": true, "auto_hide_diff_table_header": true, "theme": "DEFAULT", "ignore_whitespace": "IGNORE_NONE" }
PUT /config/server/preferences.diff
Sets the default diff preferences for the server.
The new diff preferences must be provided in the request body as a DiffPreferencesInput entity.
To be allowed to set default diff preferences, a user must be a member of a group that is granted the Administrate Server capability.
Request.
PUT /a/config/server/preferences.diff HTTP/1.0 Content-Type: application/json; charset=UTF-8 { "context": 10, "tab_size": 8, "line_length": 80, "cursor_blink_rate": 0, "intraline_difference": true, "show_line_endings": true, "show_tabs": true, "show_whitespace_errors": true, "syntax_highlighting": true, "auto_hide_diff_table_header": true, "theme": "DEFAULT", "ignore_whitespace": "IGNORE_NONE" }
As response a DiffPreferencesInfo is returned.
Response.
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 )]}' { "context": 10, "tab_size": 8, "line_length": 80, "cursor_blink_rate": 0, "intraline_difference": true, "show_line_endings": true, "show_tabs": true, "show_whitespace_errors": true, "syntax_highlighting": true, "auto_hide_diff_table_header": true, "theme": "DEFAULT", "ignore_whitespace": "IGNORE_NONE" }
The name of the cache.
If the cache is defined by a plugin the cache name must include the plugin name: “<plugin-name>-<cache-name>”.
Gerrit core caches can optionally be prefixed with “gerrit”: “gerrit-<cache-name>”.
The ID of the task (hex string).
The AccountsConfigInfo
entity contains information about Gerrit configuration from the accounts section.
The AuthInfo
entity contains information about the authentication configuration of the Gerrit server.
The CacheInfo
entity contains information about a cache.
The CacheOperationInput
entity contains information about an operation that should be executed on caches.
The CapabilityInfo
entity contains information about a capability.
The ChangeConfigInfo
entity contains information about Gerrit configuration from the change section.
The CheckAccountExternalIdsInput
entity contains input for the account external IDs consistency check.
Currently this entity contains no fields.
The CheckAccountExternalIdsResultInfo
entity contains the result of running the account external IDs consistency check.
The ConsistencyCheckInfo
entity contains the results of running consistency checks.
The ConsistencyCheckInput
entity contains information about which consistency checks should be run.
The ConsistencyProblemInfo
entity contains information about a consistency problem.
The DownloadInfo
entity contains information about supported download options.
The DownloadSchemeInfo
entity contains information about a supported download scheme and its commands.
The EmailConfirmationInput
entity contains information for confirming an email address.
The EntriesInfo
entity contains information about the entries in a cache.
The GerritInfo
entity contains information about Gerrit configuration from the gerrit section.
The HitRatioInfo
entity contains information about the hit ratio of a cache.
The JvmSummaryInfo
entity contains information about the JVM.
The MemSummaryInfo
entity contains information about the current memory usage.
The PluginConfigInfo
entity contains information about Gerrit extensions by plugins.
The ReceiveInfo
entity contains information about the configuration of git-receive-pack behavior on the server.
The ServerInfo
entity contains information about the configuration of the Gerrit server.
The SshdInfo
entity contains information about Gerrit configuration from the sshd section.
This entity doesn’t contain any data, but the presence of this (empty) entity in the ServerInfo entity means that SSHD is enabled on the server.
The SuggestInfo
entity contains information about Gerrit configuration from the suggest section.
The SummaryInfo
entity contains information about the current state of the server.
The TaskInfo
entity contains information about a task in a background work queue.
The TaskSummaryInfo
entity contains information about the current tasks.
The ThreadSummaryInfo
entity contains information about the current threads.
The TopMenuEntryInfo
entity contains information about a top menu entry.
The TopMenuItemInfo
entity contains information about a menu item in a top menu entry.
The UserConfigInfo
entity contains information about Gerrit configuration from the user section.
Part of Gerrit Code Review