Skip to main content

Clumio REST API

Introduction

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.

Getting Started​

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, which is 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 portals and their associated API domains:

All requests share the same domain name. The domain name is also referred to as the base URL or the API server URL.

The path is the suffix of the web address. The path specifies which resource to operate upon and may include variable components called path parameters. Path parameters are used to point to a specific item within a resource collection, such as a user identified by ID ({user_id}).

In this guide, each operation is listed in the following format:


METHOD <path>

The METHOD is one of GET, POST, PUT, PATCH, or DELETE to indicate the HTTP method to be performed, and <path> represents the resource and its path parameter(s), where applicable. The endpoint is often used with the method to define the operation being performed with the resource, so in this guide, the term endpoint may refer to both the endpoint and the accompanying method.

For example, the endpoint used to get a list of all users looks like this:


GET /user

In cURL, the equivalent format is the following:


curl -X GET \
  https://us-west-2.api.clumio.com/users \

The Clumio Discovery API displays a full list of Clumio resources and their available endpoints. For more information about the Discovery API, go to Discovery API.

In addition to passing a well-formed URL with the appropriate parameters, every request should also include the following three 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 will default to the newest API version. For more information about versioning, go to Versioning.

The Authorization header specifies the JWT Bearer token you are using to authenticate into Clumio. This header is required. For more information about authenticating into the Clumio REST API, go to Authentication.

If you belong to more than one organizational unit (OU), set X-Clumio-OrganizationalUnit-Context to the UUID of the top-level OU you want to perform your request in.

The request is served in the specified OU and all of its descendant OUs. Use the GET /organizational-units endpoint to fetch the UUID.

To perform a request in the global OU, set X-Clumio-OrganizationalUnit-Context: 00000000-0000-0000-0000-000000000000. The request is served in the global OU and all of its descendant OUs (in other words, across all organizational units).

If you do not specify the header, the value will default to the OU you were first assigned to. If you belong to only one OU, you do not need to send the header. For more information about organizational units, refer to the Clumio User Guide by logging in to the Clumio UI and selecting Help > Clumio User Guide.

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, go to 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 body parameter "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":"clumian@clumio.com",
    "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
        }
    }
}

The request was successful, as indicated by the response status (OK 200) and body response (where "is_enabled":false).

Authentication​

Accessing the Clumio REST API requires authentication. To ensure data is transmitted between parties securely, each Clumio user must authenticate into the REST API using a signed JSON Web Token (JWT). These tokens store the user's ID and other critical identifying information. Unauthenticated requests generate a 401 Unauthorized HTTP status code.

Authenticating into the Clumio REST API involves the following high-level steps:

  1. Generate an API token through the Clumio UI (Account Settings > API Tokens). The API token is a long-lived JWT bearer token that can be used until it is manually refreshed or deleted. For more information about REST API authentication and generating API tokens, refer to the Clumio User Guide by logging in to the Clumio UI and selecting Help > Clumio User Guide.

  2. Send the API token as a bearer token in the Authorization header with each Clumio REST API request that requires authentication. For example, 

    ```
        curl -X GET \
          https://us-west-2.api.clumio.com/users \
          -H 'Authorization: Bearer ${BEARER_TOKEN}' \
    ```

Discovery API​

The Discovery endpoint (GET /) provides a machine-readable list of Clumio REST API resources. The response includes a list of resources and, within each of the resources, their associated operation IDs. Each set of resources is organized by release version, starting with the earliest available version.

In the following example, the consolidated-alerts resource includes a list of operation IDs. Operation ID list-consolidated-alerts was released in v1, while v2 saw three operation IDs released: a newer version of list-consolidated-alerts, read-consolidated-alerts, and update-consolidated-alerts.


{
    "consolidated-alerts": {
        "supported_versions": [
            "v2", "v1"
        ],
        "v1": {
            "list-consolidated-alerts": {
                "href": "/alerts/consolidated",
                "type": "get",
                "templated": false
            }
        },
        "v2": {
            "list-consolidated-alerts": {
                "href": "/alerts/consolidated",
                "type": "get",
                "templated": false
            },
            "read-consolidated-alert": {
                "href": "/alerts/consolidated/{consolidated_alert_id}",
                "type": "get",
                "templated": true
            },
            "update-consolidated-alert": {
                "href": "/alerts/consolidated/{consolidated_alert_id}",
                "type": "patch",
                "templated": true
            }
        }
    }
}

To protect clients from encountering broken links due to server-side URL changes, when referring to a resource location (URL) within a script, use the resource name and operation ID to retrieve the URL rather than by hard-coding the URL itself. For example, to list consolidated alerts, use the resource name consolidated-alerts and its operation ID list-consolidated-alerts.

To avoid network calls at each request, cache the Discovery REST API response.

In addition to displaying a list of Clumio REST API resources, the Discovery response also contains the version string of the current release in the Content-Type HTTP response header. For example:


Content-Type: application/api.clumio.*=v1+json

The version string must be included in the header of every request to specify the version used at the resource level.

For more information about versioning, go to Versioning.

Versioning​

The Clumio REST API is designed to be versioned by resource rather than at the API level.

Each resource may support multiple versions, and each version supports a list of operations. For example, the users resource may include one set of operation IDs in major version 1, and another set of operation IDs in major version 2.

Each resource can be versioned independently.

When backwards-incompatible changes to a resource occur, a new version of that resource will be released. Clients who continue to use the old version are protected from backwards incompatible changes. Examples of backward incompatible changes include:

  • Renaming a response field.

  • Removing a response field.

  • Adding a required request parameter.

  • Renaming a request parameter.

  • Changing the order of the items in an array response.

Changes which are guaranteed to be backward compatible will not introduce a new version. Examples of backward compatible changes include:

  • Adding an optional request parameter.

  • Adding new fields to a response.

To see a list of resources and their supported versions, run the Discovery endpoint (GET /).

Every request must include an HTTP header with the Accept key

to define the version of the API to be used. The value of the Accept header should be specified in the following format, where <version> represents the version to be used.


Accept: application/api.clumio.*=v<version>+json

In the following example, the request header uses *=v1, meaning all resources use v1:


Accept: application/api.clumio.*=v1+json

To determine the newest version for each resource, run the Discovery endpoint GET /. The newest version string is sent in the response header and looks similar to the following example:


Content-Type: application/api.clumio.*=v1+json

For more information about the Discovery endpoint, go to Discovery API.

The version string can be customized to specify different versions for different resources using the following ampersand-separated format.


Accept: application/api.clumio.*=v2&users=v3&tasks=v1+json

For example, when a request is submitted with the above version string, every resource will use v2 except for users and tasks, which will use v3 and v1 respectively.

Note that since each resource can be versioned independently, the same URL may provide different request/response formats based on the resource version specified.

To upgrade to a newer REST API version, change the version string.

Important! Before you upgrade to a major version, test your code against the target version by modifying your version string, and adjust your script accordingly. For more information about Clumio releases, refer to the Clumio Release Notes.

Version Deprecation​

The Clumio REST API will remove support for old versions according to the following policy:

  • 6 months after the release of a new version, support for the old version will be removed.

  • Depending on the adoption rate of the endpoint, if the impact of a change is deemed to be minimal to clients, old versions may have their support discontinued more quickly, but the old version will always persist for at least one month after the release of the new version.

REST Methods​

The Clumio REST API uses HTTP requests to interact with the Clumio resources, manipulating these resources through JSON-encoded requests and responses.

The Clumio REST API architecture strives to follow CRUDL (Create,

Read, Update, Delete, List) principles and their mappings to common REST API methods. The Clumio REST API supports the following REST API methods:
MethodDescription
GETRetrieves a representation of the specified resource.
POSTSubmits data to the specified resource, often causing a change in state on the server.
PUTUpdates an existing resource by replacement.
PATCHApplies partial modifications to an existing resource.
DELETEDeletes a resource.

GET​

The GET method requests a representation of the specified resource. Requests using GET only retrieve data and never cause a side effect or state change in the server.

For resources that support CRUDL operations, the GET method is used for Read and List operations. For example, send the following GET request to retrieve a list of all registered users.

Request​


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

Response​


{
    "start": "1",
    "total_count": 5,
    "total_pages_count": 1,
    "current_count": 5,
    "limit": 20,
    "_links": {
        "_self": {
            "href": "/users",
            "type": "get",
            "templated": false
        },
        "_first": {
            "href": "/users?start=1",
            "type": "get",
            "templated": false
        },
        ... more links
    },
    "_embedded": {
        "items": [
            {
                "full_name": "Clumian",
                "email": "clumian@example.com",
                "is_confirmed": true,
                "id": "36",
                "is_enabled": true,
                "last_activity_timestamp": "2020-04-12T23:20:50Z",
                "inviter": "1",
                "_links": {
                    "_self": {
                        "href": "/users/36",
                        "type": "get",
                        "templated": false
                    },
                    "update-user": {
                        "href": "/users/36",
                        "type": "patch",
                        "templated": false
                    },
                    "delete-user": {
                        "href": "/users/36",
                        "type": "delete",
                        "templated": false
                    }
                },
                ... Four (4) more items
            }
        ]
    }
}

When using GET to perform list operations, you may include query parameters for filtering, sorting, and pagination to better manage the results. For more information about query parameters, go to Filtering, Sorting, and Pagination.

When using GET to perform read operations, use path parameters to point to a specific resource within a collection.

Using the response in the previous example to get the ID for the user named "Clumian" ("id": "36"), set the {user_id} path parameter to 36 in the following request to only retrieve data for the user "Clumian":

Endpoint​


GET /users/{user_id}

Request​


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

POST​

The POST method submits data to the specified resource, often causing a state change in the server.

For resources that support CRUDL operations, the POST method is used to

create a new instance of the specified resource. The request body must include all required fields. The response includes the newly created item.

For example, send the following POST /policies/definitions request with its required body parameters name, seed_setting, and slas to create a new backup policy:

Endpoint (with body parameters)​


POST /policies/definitions

{
    "name": "Just One Backup",
    "sla_sets": [
        {
            "operation": "vmware_vm_backup",
            "seed_setting": "immediate",
            "slas": [
                "rpo_frequency": {
                    "units": "year",
                    "value": 1
                }
                "retention_duration": {
                    "units": "year",
                    "value": 1
                }
            ]
        }
    ]
}

Request​


curl -X POST \
  https://us-west-2.api.clumio.com/policies/definitions \
  -H 'Accept: application/api.clumio.*=v1+json' \
  -H 'Authorization: Bearer ${BEARER_TOKEN}' \
  -d '{
    "name": "Just One Backup",
    "sla_sets": [
        {
            "operation": "vmware_vm_backup",
            "seed_setting": "immediate",
            "slas": [
                "rpo_frequency": {
                    "units": "year",
                    "value": 1
                }
                "retention_duration": {
                    "units": "year",
                    "value": 1
                }
            ]
        }
    ]
}'

PUT​

The PUT method updates the state of a resource.

For resources that support CRUDL operations, the PUT method is used to

update a resource by providing an entire replacement object in the request body, and all overwritable fields will be overwritten. The request body for `POST` and `PUT` are often similar. The updated resource is returned in the response.

For example, send the following request with the accompanying body parameters to update the policy created above:

Endpoint (with body parameters)​


PUT /policies/definitions/da9cd728-e272-436c-9b80-119229260004

{
    "name": "Just One Backup Renamed",
    "sla_sets": [
        {
            "operation": "vmware_vm_backup",
            "seed_setting": "immediate",
            "slas": [
                "rpo_frequency": {
                    "units": "year",
                    "value": 1
                }
                "retention_duration": {
                    "units": "year",
                    "value": 1
                }
            ]
        }
    ]
}

Request​


curl -X PUT \
  https://us-west-2.api.clumio.com/policies/definitions/da9cd728-e272-436c-9b80-119229260004 \
  -H 'Accept: application/api.clumio.*=v1+json' \
  -H 'Authorization: Bearer ${BEARER_TOKEN}' \
  -d '{
    "name": "Just One Backup Renamed",
    "sla_sets": [
        {
            "operation": "vmware_vm_backup",
            "seed_setting": "immediate",
            "slas": [
                "rpo_frequency": {
                    "units": "year",
                    "value": 1
                }
                "retention_duration": {
                    "units": "year",
                    "value": 1
                }
            ]
        }
    ]
}'

PATCH​

The PATCH method applies partial modifications to a resource.

For resources that support CRUDL operations, the PATCH method expects a partial object to be provided in the body, and only the fields provided in the PATCH request will be overwritten.

For example, send the following request with the accompanying body parameter full_name to change the name of the user with the user ID 35 to "Clumio Clumian":

Endpoint (with body parameters)​


PATCH /users/35

{
    "full_name":"Clumio Clumian"
}

Request​


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

The response includes a representation of the updated resource.

DELETE​

The DELETE method deletes a resource.

For example, send the following request to delete the user with the user ID 35 from the Clumio system:

Endpoint​


DELETE /users/35

Request​


curl -X DELETE \
  https://us-west-2.api.clumio.com/users/35 \
  -H 'Accept: application/api.clumio.*=v1+json' \
  -H 'Authorization: Bearer ${BEARER_TOKEN}' \

Once an item has been successfully deleted, the server returns an empty body.

HATEOAS / HAL Architecture​

The Clumio REST API implements Hypermedia as the Engine of Application State (HATEOAS) application architecture and JSON Hypermedia API Language (HAL) conventions as the media type format.

HATEOAS enables users to traverse hypermedia links returned in API responses that are most closely associated with the request, eliminating the need for clients to manually specify resource locations (URLs) in their code. Within the HATEOAS implementation, HAL conventions are used to support the programmatic usage of Clumio resources via scripted clients. TO learn more about HAL, go to the HAL - Hypertext Application Language.

With the HATEOAS/HAL architecture, API responses contain:

  • Links to all possible actions on the resource in its current state.

  • Links to all resources that have a relationship with the current resource.

Most responses include a _links field. The _links field contains links to help the client navigate to other related resources. Examples of _links fields include _self, which represents the resource path to the current request, and _next, which contains the path to the next page of results within List requests, incrementing the start query parameter by one. _links may also include resource-specific links. For example, a policy definition contains links to backup statistics about entities protected by that policy. For more information about the _links field, go to Pagination.

The _embedded property contains a collection of items - known as an array of embedded resources - representing the properties of the resource.

In the following sample response for a GET /tasks request, the _links property displays several links that can be used to navigate to the first, last, or next page of the current request, respectively, while the _embedded property displays the properties of each task, broken down by task ID.

Request​

GET /tasks

Response​

{
    "current_count": 10,
    "limit": 10,
    "start": "1",
    "total_count": 10088,
    "total_pages_count": 1009,
    "filter_applied": "{\"start_timestamp\":{\"$lte\":"2020-04-12T23:20:50Z"}}",
    "_links": {
        "_self": {
            "href": "/tasks",
            "type": "get",
            "templated": false
        },
        "_first": {
            "href": "/tasks?filter=%7B%22start_timestamp%22%3A%7B%22%24lte%22%3A"2020-04-12T23:20:50Z"%7D%7D&start=1",
            "type": "get",
            "templated": false
        },
        "_last": {
            "href": "/tasks?filter=%7B%22start_timestamp%22%3A%7B%22%24lte%22%3A"2020-04-12T23:20:50Z"%7D%7D&start=1009",
            "type": "get",
            "templated": false
        },
        "_next": {
            "href": "/tasks?filter=%7B%22start_timestamp%22%3A%7B%22%24lte%22%"2020-04-12T23:20:50Z"%7D%7D&start=2",
            "type": "get",
            "templated": false
        }
    },
    "_embedded": {
        "items": [
            {
                "id": "143717",
                "type": "aws_ebs_volume_incremental_backup",
                "parent_entity": {
                    "type": "aws_account_region",
                    "id": "9c2934fc-ff4d-11e9-8e11-76706df7fe01",
                    "value": "891106093485/us-west-2"
                },
                "primary_entity": {
                    "type": "aws_ebs_volume",
                    "id": "12e91a96-01e9-11ea-92e9-b68591d87ad1",
                    "value": "vol-026b0c4326beded57"
                },
                "status": "completed",
                "progress_percentage": 100,
                "start_timestamp": "2020-04-12T22:20:50Z",
                "end_timestamp": "2020-04-12T22:24:50Z",
                "_links": {
                    "_self": {
                        "href": "/tasks/143717",
                        "type": "get",
                        "templated": false
                    }
                }
            },
            {
                "id": "143587",
                "type": "aws_ebs_volume_incremental_backup",
                "parent_entity": {
                    "type": "aws_account_region",
                    "id": "9c2934fc-ff4d-11e9-8e11-76706df7fe01",
                    "value": "891106093485/us-west-2"
                },
                "primary_entity": {
                    "type": "aws_ebs_volume",
                    "id": "12e91a96-01e9-11ea-92e9-b68591d87ad1",
                    "value": "vol-026b0c4326beded57"
                },
                "status": "completed",
                "progress_percentage": 100,
                "start_timestamp": "2020-04-11T23:20:50Z",
                "end_timestamp": "2020-04-11T23:23:50Z",
                "_links": {
                    "_self": {
                        "href": "/tasks/143587",
                        "type": "get",
                        "templated": false
                    }
                }
            },
            ... plus another 8 other tasks on this page
        ]
    }
}

Embedding Referenced Resources​

Certain operations allow you to embed the response of an associated resource. For example, the GET request for an individual alert can include an embedded field to show a representation of its associated consolidated alert. Refer to the resource descriptions in this guide to determine which links are embeddable.

Embedded fields are added to a response by using ?embed=<embeddable_link> as a query parameter, where <embeddable_link> is the operation ID of the embeddable link. This will embed the requested payload in the _embedded field of the response.

For example, the GET /datasources/aws/environments endpoint supports the read-aws-environments-backup-status-stats embeddable link as a referenced resource to embed backup statistics about the environment into each environment response.

In the request, use the embed query parameter and set it to the read-aws-environments-backup-status-stats. For example,


https://us-west-2.api.clumio.com/datasources/aws/environments?embed=read-aws-environments-backup-status-stats

In each item of the response, the referenced resource is embedded (_embedded). In the following example, the response embeds read-aws-environments-backup-status-stats for each registered AWS environment:

Request​


curl -X GET \
  'https://us-west-2.api.clumio.com/datasources/aws/environments?embed=read-aws-environments-backup-status-stats' \
  -H 'Accept: application/api.clumio.*=v1+json' \
  -H 'Accept-Encoding: application/api.clumio.*=v1&users=v2+json' \
  -H 'Authorization: Bearer ${BEARER_TOKEN}' \
  ...

Response​


{
    ...
    "_embedded": {
        "items": [
            {
                ...
                "_embedded": {
                    "read-aws-environments-backup-status-stats": {
                        "ebs_backup_status_stats": {
                            "failure_count": 0,
                            "no_backup_count": ,
                            "partial_success_count": 0,
                            "success_count": 506
                        },
                        "ec2_backup_status_stats": {
                            "failure_count": 0,
                            "no_backup_count": 3,
                            "partial_success_count": 20,
                            "success_count": 308
                        },
                        ....
                    }
                }
            }
        ]
    }
}

The Clumio REST API versioning and API discovery conventions used along with HATEOAS/HAL standards enable client scripts to evolve independently across resources and versions.

Filtering, Sorting, and Pagination​

When performing list operations, you may include query parameters for filtering, sorting, and pagination to better manage the results.

Certain operations also support the embed query parameter, providing an even richer output by embedding related resources into the current request. For more information about the embed query parameter, go to Embedding Referenced Resources.

Filtering​

The filter query parameter narrows down the results of a GET List request to only the items that satisfy the filter criteria. Certain endpoints support the filter parameter. To determine if an endpoint supports the filter parameter, refer to the endpoint descriptions in this guide.

Filter query parameters are specified in the following JSON format:

?filter={
  "FIELD_NAME": {
      "FILTER_CONDITION":VALUE
  },
  "FIELD_NAME":{
      "FILTER_CONDITION":VALUE
  }
}

The Clumio REST API supports the following filter conditions. Different endpoints support a subset of these filter conditions on a subset of their fields:

<table>
<tr><th><b>Filter Condition</b></th><th><b>Description</b></th></tr>
<tr><td>$eq</td><td>equal to</td></tr>
<tr><td>$neq</td><td>not equal to</td></tr>
<tr><td>$gte</td><td>greater than or equal to</td></tr>
<tr><td>$lte</td><td>less than or equal to</td></tr>
<tr><td>$gt</td><td>greater than</td></tr>
<tr><td>$lt</td><td>less than</td></tr>
<tr><td>$in</td><td>value of the field in given input set</td></tr>
<tr><td>$all</td></td><td>matches all fields</td></tr>
<tr><td>$contains </td><td>partial match</td></tr>
<tr><td>$begins_with</td><td>begins with</td></tr>
</table>

For example, the /tasks resource supports several filter parameters, including the start_timestamp field, which can be set to query only the tasks that began before the given time (specified in RFC-3339).


GET /tasks?filter={"start_timestamp":{"$lte":"2020-04-12T23:20:50Z"}}

Common Filters​

The following table lists the supported Clumio protection statuses:

Protection StatusDescription
protectedAn entity that is protected by a policy.
unprotectedAn entity that is not protected by a policy.
unsupportedAn asset whose backup is not supported by Clumio.
nullAn asset that has been deleted.

The following table lists the supported Clumio backup statuses:

Backup StatusDescription
successThe status of an asset for which all backups and snapshots have succeeded in the specified look back period.
partial_successThe status of an asset for which all backups or snapshots have not succeeded in the specified look back period but the most recent backup was successful.
failureThe status of an asset for which the most recent backup in the specified look back period has failed.
no_backupThe status of asset for which there have been no backups or snapshots taken in the specified look back period.

Sorting​

The sort query parameter returns the response items of a GET list operation in the order based on the specified field name.

For example, to sort a list of individual alerts in the order in which they were last updated from first to last (e.g., chronological ascending order), append the ?sort=updated_timestamp query parameter to the /alerts/individual path:


GET /alerts/individual?sort=updated_timestamp

To sort the items in reverse order (e.g., chronological descending order), prefix the field name with a minus (-) sign.

For, example, to sort the same list of individual alerts in reverse order so that the alert that was most recently updated appears at the beginning of the output, set ?sort=-updated_timestamp:


GET /alerts/individual?sort=-updated_timestamp

Only certain fields can be used for sorting. Refer to the resource descriptions in this guide to determine the default sort order of each collection and to determine which fields can be used for sorting.

Pagination​

Pagination controls the size and starting point of a page.

The limit query parameter controls the number of results returned per page. The default value of limit depends on the resource. The start query parameter defines the starting point from where results are to be returned. Depending on the resource, the parameter may take a page number to start from or a token that identifies the starting point of results.

In the following example, the number of results per page has been limited to 5 tasks.


GET /tasks?limit=5

The limit parameter controls the number of response items returned per page, but the consistency of the content returned may not be guaranteed in that, as you are paginating, items that are inserted or deleted between requests may cause rows in your response to be skipped or duplicated.

The Clumio REST API uses HATEOAS _links for pagination by leveraging the start query parameter to traverse between pages.

Pagination _links include the following:

LinkDescription
_firstLink to the first page of results.
_lastLink to the last page of results.
_nextLink to the next page of results. Only appears if there are results to display on the next page.
_prevLink to the previous page or results. Only appears if there are results to display on the previous page.

The _next token represents the link to the next page of results relative to the current start page, while the _prev token represents the link to the previous page of results relative to the current start page.

In the following example, the GET /tasks request returns a response of "start": "1", representing the first page of results.

The _first link is set to the first page (start=1) of results.

The _last link is set to the last page (start=1009) of results.

The _next link is set to the next page (start=2) of results. If "start": "2", the _next link would be set to start=3.

To freeze the results in time while browsing, a filter on the start_timestamp value is automatically applied to the HATEOAS links to other pages.


{
    "current_count": 10,
    "limit": 10,
    "start": "1",
    "total_count": 10088,
    "total_pages_count": 1009,
    "filter_applied": "{\"start_timestamp\":{\"$lte\":"2020-04-12T23:20:50Z"}}",
    "_links": {
        "_self": {
            "href": "/tasks",
            "type": "get",
            "templated": false
        },
        "_first": {
            "href": "/tasks?filter=%7B%22start_timestamp%22%3A%7B%22%24lte%22%3A"2020-04-12T23:20:50Z"%7D%7D&start=1",
            "type": "get",
            "templated": false
        },
        "_next": {
            "href": "/tasks?filter=%7B%22start_timestamp%22%3A%7B%22%24lte%22%3A"2020-04-12T23:20:50Z"%7D%7D&start=2",
            "type": "get",
            "templated": false
        },
        "_last": {
            "href": "/tasks?filter=%7B%22start_timestamp%22%3A%7B%22%24lte%22%3A"2020-04-12T23:20:50Z"%7D%7D&start=1009",
            "type": "get",
            "templated": false
        }
    }
}

Response Codes​

The Clumio REST API uses the following HTTP status codes:

HTTP Status CodeDescription
200 OKSuccessful.
201 CreatedThe request has led to the creation of a resource on the server.
202 AcceptedThe request has been accepted for processing, but the processing has not been completed.
400 Bad RequestInvalid action or missing data. Refer to the error message in the response payload for more information.
401 UnauthorizedToken expired. Reauthenticate into the REST API.
403 ForbiddenClient not authorized to perform this action.
404 Not FoundResource not found.
409 ConflictDuplicate item, such as user, data source, or policy, specified.
412 Precondition FailedAction being performed does not meet certain preconditions. Refer to the error message in the response payload for more information.
429 Too Many RequestsRequest failed due to API rate-limit throttling. After some back-off time, retry the request. For more information, go to API Throttling.

A 200 OK status code confirms that the REST API action was successful. A 201 Created status code indicates that the request has led to the creation of the resource on the server. A 202 Accepted status code confirms that the request has been accepted and is in progress. All other responses generate a 4xx status code indicating an unsuccessful action that requires resolution. Go to the HTTP Status Code chart for steps on how to resolve the issue.

API Throttling​

API throttling regulates the way the Clumio REST API is used by controlling the data a client can access. Throttling processes enhance performance levels by preventing the API from being overwhelmed by too many requests, and adds a layer of security by preventing clients from performing abusive actions.

Rate-limit throttling ensures that requests sent to the Clumio REST API do not exceed the maximum limit. At Clumio, each organization can send up to 100 requests per second, where each request is a resource. For example, for the endpoint GET /tasks, the /tasks resource represents a single request. Throttling is enforced at the API gateway and cannot be disabled. The rate limit is calculated in real time and cannot be changed.

Throttling kicks in after the rate limit is reached. Reqests that have been sent before the limit is reached are processed through to completion. All other requests that are sent after that time are not processed, and a 429 Too Many Requests HTTP status code is returned for each of those requests. After some back-off time, retry the requests. Any scheduled processes, such as backups, are not affected and will continue running.

Compression Using GZIP​

To reduce the amount of data being transferred over the network as part of the API response, the gzip compression data compression utility is enabled to compress payload sizes greater than 1400 bytes.

To compress large responses, pass the following key/value pair as part of the header request:


Accept-Encoding: application/gzip

If the data is compressed, the following key/value pair will be returned in the response header:


Content-Encoding: application/gzip

You must go to the header of the response to determine if the data compressed. If the content is compressed, decompress it using the necessary client libraries.

Concurrency Control​

Certain Clumio REST API resources use

ETag and If-Match HTTP response headers to provide optimistic concurrency control when handling PUT and PATCH requests. The ETag value is generated from the current state of the resource, and any updates to the resource changes the ETag value.

The "If-Match" request header uses the ETag value in its PUT and PATCH requests to validate whether the changes to the resource are made on the latest state of the resource. To achieve this requires the following assumptions and requirements:

  • The GET request for the resource must return the ETag HTTP response header.

  • When the client sends a PUT or PATCH request, the client must send the "If-Match" HTTP request header with the value of the ETag. If the "If-Match" header is not specified, an HTTP 403 Forbidden status code is returned.

  • If the "If-Match" header value does not match the generated ETag value, an HTTP 412 status code is returned.

Limitations and Constraints​

Consider the following constraints when working with the Clumio REST API:

  • In requests, pipe characters (|) must be in URL-encoded format %7C. Plain text pipe characters are not supported.

  • In requests, semicolon characters (;) are not supported.

Authentication​

Security Scheme Type:http
HTTP Authorization Scheme:bearer
Bearer format: