Help CenterClumio Terraform ProviderClumio Python SDKClumio GO SDK
BlogChangelogLogin

Getting Started with the Clumio REST API

The Clumio REpresentational State Transfer (REST) Application Programming Interface (API) provides a simple interface for the Clumio operations you need to perform to fully protect your data. This guide details how to communicate with the Clumio REST API to manage Clumio's resources and perform operations including data protection and on-demand restore.

The Clumio REST API works with any language that supports HTTP/HTTPS requests. The Clumio REST API can be accessed using HTTP/HTTPS requests. Programmatic scripts and cURL are popular ways to interact with APIs. In this guide, most of the examples are written in cURL.

Each REST API request includes a URL comprised of a domain name and a path. The following example represents a well-formed URL that lists all users:

  • URL = https:/example.com/users
  • domain name = example.com
  • path = /users

The domain to use depends on the Clumio portal for which your credentials have been generated. The following is a list of ports and their associated API domains:

Note: To display a full list of Clumio resources and their endpoints, use the Clumio Discovery API. See Discovery API.

In addition to passing a well-formed URL with the appropriate parameters, each request must include the following headers:

  • Authorization provides the required authentication token. For example, Authorization: Bearer $(BEARER_TOKEN)
  • Accept provides the version of the API to be used. For example, Accept: application/api.clumio.*=v1+json
  • X-Clumio-OrganizationalUnit-Context sets the organizational unit in which to perform the request. For example, X-Clumio-OrganizationalUnit-Context: a12345bc-67d8-912a=345b-c67891234567

The Accept header specifies the version of the API to be used. If you do not specify the header, then the value defaults to the latest version of the API endpoint. See Versioning for more information.

The Authorization header specifies the JWT Bearer token you are using to authenticate with Clumio. See Authentication for more information.

The Organizational Unit (OU) header specifies the organizational unit where you want to run a request. This is used when you belong to more than one OU. See Organizational Units for more information.

Building on the previous example, the full request including the required headers would look like this in cURL:

curl -X GET  
  [https://us-west-2.api.clumio.com/alerts/individual/32e6f210-0b83-4308-b437-8c9ac11f306c](<>)  
  -H 'Accept: application/api.clumio.\*=v1+json'  
  -H 'Authorization: Bearer ${BEARER_TOKEN}' \\

GET requests query the API and return information specific to the request. To fine-tune the response and narrow down the results of a GET request, append query parameters to the end of the URL. For example, using the sort query parameter, send the following request to retrieve a list of all individual alerts, sorted by the time (in ascending chronological order) at which each alert was last updated (e.g., ?sort=updated_timestamp):

curl -X GET \
  https://us-west-2.api.clumio.com/alerts/individual?sort=updated_timestamp \
  -H 'Accept: application/api.clumio.*=v1+json' \
  -H 'Authorization: Bearer ${BEARER_TOKEN}' \

For more information about query parameters, see Filtering, Sorting, and Pagination.

POST, PUT, PATCH, and most DELETE requests change the state of a resource. Therefore, body parameters must be included in the request to specify the changes to be performed. For example, send the following PATCH request to disable user ID 40 from the system by setting the body parameter "is_enabled" to false (is_enabled":false):

Request

curl -X PATCH \
     https://us-west-2.api.clumio.com/users/40 \
     -H 'Accept: application/api.clumio.*=v1+json' \
     -H 'Authorization: Bearer ${BEARER_TOKEN}' \
     -d '{
       "is_enabled": false
     }'

Response

STATUS: OK 200

{
    "full_name":"test person",
    "email":"[email protected]",
    "is_confirmed":false,"id":"40",
    "is_enabled":false,
    "last_activity_timestamp":"1985-04-12T23:20:50Z",
    "inviter":"1",
    "_links": {
        "_self": {
            "href":"/users/40",
            "type":"get",
            "templated":false
        },
        "update-user": {
            "href":"/users/40",
            "type":"patch",
            "templated":false
        },
        "delete-user": {
            "href":"/users/40",
            "type":"delete",
            "templated":false
        }
    }
}

A successful request is indicated by the response status (OK 200) and body response (where "is_enabled":false).