Using the API

In Elastic Cloud Enterprise, you can use API endpoints to work with:

  • Authentication
  • Elasticsearch clusters
  • Kibana instances
  • Deployments
  • Deployment templates
  • Elastic Cloud Enterprise platform infrastructure
  • Elastic Stack versions

Authentication

Elastic Cloud Enterprise supports token-based authentication using the same username and password that you use to log into the Cloud UI. If you want to use the credentials that were provided when you installed Elastic Cloud Enterprise on your first host, for example admin, you can retrieve them separately.

For operations that only read information, but don’t create, update or delete, you can authenticate with a user that has restricted permissions, such as the readonly user.

API calls

The API base path is /api/v1/.

You communicate with our RESTful API through the HTTP and HTTPS protocols. We recommend that you use HTTPS on port 12443, because it is much more secure.

RESTful API calls are stateless: Every request that you make happens in isolation from other calls and must include all the information necessary for ECE to fulfill the request. API requests return JSON ouput, which is a format that is machine-readable and works well for automation.

Calls to API endpoints require different request methods, depending on what they do. Here are request methods you use when communicating with our RESTful API for ECE:

  • To fetch information: GET
  • To add new information: POST
  • To update existing information: PUT or PATCH
  • To delete information: DELETE

Our API Reference, specifies the request method you need to use for each endpoint, along with supported parameters and the possible responses that you get returned.

Each API endpoint is represented as an object that contains:

  • A description of what the endpoint does
  • The parameters that the endpoint accepts
  • The format of the request body
  • The response body and all of the possible returned status codes
  • Authentication requirements

For example, the slightly abridged specification for shutting down an Elasticsearch cluster that is running on ECE is:

"/clusters/elasticsearch/{cluster_id}/_shutdown": {
  "post": {
    "tags": ["ClustersElasticsearch"],
    "summary": "Shut down cluster",
    "description": "Shuts down the active Elasticsearch cluster and removes all of the cluster nodes. The cluster plan is retained. WARNING: To avoid data loss, save the data outside of the cluster before you shut the cluster down.",
    "operationId": "shutdown-es-cluster",
    "parameters": [{
      "name": "cluster_id",
      "in": "path",
      "description": "The Elasticsearch cluster identifier.",
      "required": true,
      "type": "string"
    }, {
      "name": "skip_snapshot",
      "in": "query",
      "description": "When `true`, skips the snapshot when the cluster is shut down.",
      "required": false,
      "type": "boolean",
      "default": false
    }, {
      "name": "hide",
      "in": "query",
      "description": "Hides the clusters during shutdown. NOTE: By default, hidden clusters are not listed.",
      "required": false,
      "type": "boolean",
      "default": false
    }],
    "responses": {
      "202": {
        "description": "The shutdown command was issued successfully, use the \"GET\" command on the /{cluster_id} resource to monitor progress",
        "schema": {
          "$ref": "#/definitions/ClusterCommandResponse"
        }
      },
      "404": {
        "description": "The cluster specified by {cluster_id} cannot be found (code: 'clusters.cluster_not_found')",
        "schema": {
          "$ref": "#/definitions/BasicFailedReply"
        }
      },
      "449": {
        "description": "elevated permissions are required. (code: '\"root.needs_elevated_permissions\"')",
        "schema": {
          "$ref": "#/definitions/BasicFailedReply"
        }
      }
    },
    ...
    }
  }
},

Access the API from the Command Line

The simplest way to interact with the full RESTful API for ECE is from the command line through the curl command. In order to interact with the API, you first need to acquire a bearer token. You do this by sending your credentials to the login endpoint.

Endpoint URLs look like this example:

curl -k -X POST -H 'Content-Type: application/json' --data-binary "{\"username": \"$USER\", \"password\": \":$PASSWORD\"}" https://$COORDINATOR_HOST:12443/api/v1/users/auth/_login

A user with sufficient privileges, such as the admin user

The password for the user

A host that you installed Elastic Cloud Enterprise on that holds the coordinator role

Using HTTPS requires that you have a TLS certificate already installed. For testing purposes only, you can specify the -k option to turn off certificate verification, as shown in our examples, or use HTTP over port 12400 until you get your TLS certificate sorted out.

If your credentials are valid, the response from the login API will contain a JSON Web Token (JWT):

{ "token": "eyJ0eXa...<very long string>...MgBmsw4s" }" }

You then need to include this token in an HTTP "Authentication" header when making API requests:

curl -k -X GET -H "Authorization: Bearer $TOKEN" https://$COORDINATOR_HOST:12443/api/v1/clusters/elasticsearch

A token for a user with sufficient privileges, such as the admin user

A host that you installed Elastic Cloud Enterprise on that holds the coordinator role

Tokens have a short life span, so you should not save them for the long term, and should expect to handle HTTP responses that indicate that you need to reauthenticate e.g. 401.

If this is your first time exploring the API, you can take a look at our API examples to learn more.

Generate your own client

To build API clients in the language of your choice or to use your favorite OpenAPI-enabled development tool, the Elastic Cloud Enterprise RESTful API specification is also available in OpenAPI 2.0 format.

Alternatively, you can obtain the RESTful API specification directly from Elastic Cloud Enterprise:

curl -k -X GET -H "Authorization: Bearer $TOKEN" https://$COORDINATOR_HOST:12443/api/v1/api-docs/swagger.json

A token for a user with sufficient privileges, such as the admin user

A host that you installed Elastic Cloud Enterprise on that holds the coordinator role, such as a host where you can log into the Cloud UI.

We use the OpenAPI specification to generate our own API Reference, but you can also use it for automation and to develop your own software layer around Elastic Cloud Enterprise. For example, you can use the API specification in the Swagger Editor to read through our reference content and to generate a client in many different languages.

To learn more, see Generating an Elastic Cloud Enterprise Client