manage-ghes.md

title	REST API endpoints for managing GitHub Enterprise Server
allowTitleToDifferFromFilename	true
shortTitle	Manage GHES
intro	Use the REST API to manage your {% data variables.product.prodname_ghe_server %} instance.
versions	ghes *
autogenerated	rest
category	Administer enterprises and billing

About the Manage {% data variables.product.prodname_ghe_server %} API

You can manage {% data variables.location.product_location %} using the Manage {% data variables.product.prodname_ghe_server %} API. For example, you can retrieve information about the version of the {% data variables.product.prodname_ghe_server %} software running on the instance, or on instances with multiple nodes, view the status of replication.

[!TIP] You can use this API to replace the functionality of the Management Console API, which was removed in {% data variables.product.prodname_ghe_server %} version 3.15.

Specify the port number when making API calls to endpoints for the Manage {% data variables.product.prodname_ghe_server %} API. If your instance uses TLS, the port number is 8443. Otherwise, the port number is 8080. If you cannot provide a port number, you'll need to configure your client to automatically follow redirects. For more information, see AUTOTITLE.

You can also use the {% data variables.product.prodname_ghe_server %} extension of the {% data variables.product.prodname_cli %} to invoke endpoints in the Manage {% data variables.product.prodname_ghe_server %} API. For more information, see the github/gh-es repository.

Authentication

To authenticate requests to endpoints for the Manage {% data variables.product.prodname_ghe_server %} API, specify the password for the instance's root site administrator account as an authentication token. Use standard HTTP authentication to send the password. The api_key user identifies the root site administrator. The following example demonstrates authentication for this API. Replace ROOT-SITE-ADMINISTRATOR-PASSWORD with the password, and ADMINISTRATION-PORT with either 8443 or 8080.

curl -L -u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" 'http(s)://HOSTNAME:ADMINISTRATION-PORT/manage'

Authentication as a {% data variables.enterprise.management_console %} user

{% data variables.enterprise.management_console %} user accounts can also authenticate to access these endpoints. For more information, see AUTOTITLE.

To authenticate with the password for a {% data variables.enterprise.management_console %} user account, use standard HTTP authentication. In the following example, replace YOUR_USER_NAME and YOUR_PASSWORD with the account's user name and password.

curl -L -u "YOUR_USER_NAME:YOUR_PASSWORD" 'http(s)://HOSTNAME:ADMINISTRATION-PORT/manage'

Query parameters

By default, the response includes information from about all configured nodes for the instance. On an instance with multiple nodes, the details originate from /data/user/common/cluster.conf. You can use the following query parameters to filter the response for information about specific nodes.

Query parameter	Description
uuid	Unique identifier for the node.
cluster_role	For nodes in a cluster, the roles that apply to the node. For more information, see AUTOTITLE.

You can specify multiple values for the query parameter by delimiting the values with a comma. For example, the following request uses curl to return any nodes with the web-server or storage-server role.

curl -L -u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" 'http(s)://HOSTNAME:ADMINISTRATION-PORT/manage/v1/config/nodes?cluster_role=WebServer,StorageServer'