CrashPlan API syntax and usage

This article applies to CrashPlan Enterprise and MSPs.png

Overview

The CrashPlan API is a powerful tool for gaining specific insights or taking programmatic actions on all parts of your CrashPlan environment. This article describes the syntax of the CrashPlan API and how to write commands.

The examples in this article use the command line tool cURL to interact with the CrashPlan API. For a list of tools that can be used to interact with the API, see Tools for interacting with the CrashPlan API.

In addition, the examples in this article use resource https://console.us1.crashplan.com, but the resource you use depends on your CrashPlan cloud address:

Considerations

API resources themselves only work for you under these conditions:

  • You have a product plan that includes access to the CrashPlan API.
  • Your credentials rely on local authentication. SSO or authentication through any third-party provider will not work.
  • Your role provides permission to access the data necessary to a given API resource. For example, if you do not have permission to change device settings in the CrashPlan console, then you don't have permission to change device settings with the API.

If your API calls fail because you do not have permission to use them, you will see reply messages like these:

  • HTTP 401 Unauthorized
  • HTTP 401 Could not authenticate user
  • Your CrashPlan product plan does not permit use of the CrashPlan API.

CrashPlan API syntax

Use the CrashPlan API by sending HTTP requests to the CrashPlan cloud. In your requests, specify the path, resource, and parameters that define your request. 

Example commands


curl -X GET 'https://console.us1.crashplan.com/api/v1/User?q=eg@ex.com&active=true' -H 'Authorization: Bearer <auth_token>' curl -X POST 'https://console.us1.crashplan./api/v3/ping/error' -H 'Authorization: Bearer <auth_token>' curl -X GET 'https://console.us1.crashplan./api/v4/role/view' -H 'Authorization: Bearer <auth_token>'

 Authenticating with curl

In the example curl commands listed here, replace <auth_token> with an authentication token

Example commands explained

HTTP
method
Request URL Base
path
API
resource
Query parameters
GET https://console.us1.crashplan.com /api/v1 User ?q=eg@ex.com
&active=true
POST https://console.us1.crashplan.com /api/v3/ ping/error  
GET https://console.us1.crashplan.com /api/v4/ role/view  


HTTP methods

  • GET: Retrieve a resource.
  • POST: Create a new resource.
  • PUT: Update an existing resource.
  • DELETE: Destroy an existing resource.

Request URL

Replace the request URL with the URL path for your CrashPlan cloud. For example:

API resources

The resources provide information about various components of the CrashPlan platform. For example:

  • The Computer resource provides access to your users' devices.
  • The Org resource provides access to your organizations.
  • The User resource provides access to your users.

Parameters

Parameters further specify the action of a method and resource. The API documentation describes the parameters for a given method and resource.

Query parameters go at the end of URLs with a leading question mark and separated by ampersands:  


curl -X GET 'https://console.us1.crashplan.com/api/v1/User?q=joe@acme.com&active=true' -H 'Authorization: Bearer <auth_token>' curl -X GET 'https://console.us1.crashplan.com/api/v1/User/123?idType=uid' -H 'Authorization: Bearer <auth_token>'

Request body parameters, common for POST and PUT requests, travel as JSON data in the body of an HTTP request. Specify the content-type application/json (In curl commands, -d indicates body data).


curl -X POST -d '{ "company": "Test1", "email": "test@test.com", "customerId" : "123", "firstname": "test", "lastname": "test" }' -H 'Content-Type: application/json' 'https://console.us1.crashplan.com/api/v1/user' -H 'Authorization: Bearer <auth_token>'

Return values

Some API requests simply return an HTTP response code: 200, for example, indicates success. Other requests also return JSON data

  • Return values can be one resource or an array of resources.
  • To make the output more readable, pipe it to the Python JSON decoder. To do so, add the following to a  curl command:
    | python3 -mjson.tool

Single return values

GET requests that have an ID specified on the main URL return one resource. For example:


curl -X GET -i 'https://console.us1.crashplan.com/api/v1/User/123' -H 'Authorization: Bearer <auth_token>' | python3 -mjson.tool


The user with ID "123" is returned:

{
   "metadata":{
      "timestamp":"2013-08-27T14:05:44.733-05:00",<
      "params":{
      }
   },
   "data":{
      "userId":123,
      "userUid":"c6ec2d26ce3805c1",
      "status":"Active",
      "username":"joe@acme.com",
      "email":"joe@acme.com",
      "firstName":"Joe",
      "lastName":"Jones",
      "orgId":42,
      "orgName":"Finance",
      "active":true,
      "blocked":false,
      "orgType":"CONSUMER",
      "creationDate":"2007-01-07T18:00:13.273-06:00",
      "modificationDate":"2013-05-13T13:40:52.279-05:00"
   }
}

Note that POST requests usually return the resource that was created with the generated ID for convenience.

Multiple return values

GET requests with query parameters return an array of resources. For example:


curl -X GET 'https://console.us1.crashplan.com/api/v1/User?active=true&pgNum=1&pgSize=2' -H 'Authorization: Bearer <auth_token>' | python3 -mjson.tool

An array of active users is returned:

{
   "metadata":{
      "timestamp":"2013-08-27T14:05:44.733-05:00",
      "params":{
      }
   },
   "data": {
      totalCount:5432,
      users: [
         {
            "userId":123,
            "userUid":"c6ec2d26ce3805c1",
            "status":"Active",
            "username":"joe@acme.com",
            "email":"joe@acme.com",
            ... [snipped]
         },
         {
            "userId":456,
            "userUid":"f1ad1da8b74328bz",
            "status":"Active",
            "username":"jim@slim.com",
            "email":"jim@slim.com",
            ... [snipped]
         },
      ]
   }
}

Example requests for device information

The example in this section uses curl to interact with the Computer API resource.

Input

The following command lists the devices in your CrashPlan environment:

curl -X GET -k "https://console.us1.crashplan.com/api/v1/Computer" -H 'Authorization: Bearer <auth_token>' | python3 -mjson.tool
Command Element Description
curl Invokes the curl command.
-X GET

Sets the method to GET.

-k Ignores security errors related to self-signed certificates. Refer to curl's man page for details.
http://console.us1.crashplan.com The request URL of the CrashPlan cloud
/api/v# The network location of API resources on the CrashPlan cloud, required for all API requests.
/Computer The specific API resource you wish to use. 
<auth_token> The authentication token for your request. All CrashPlan API requests must be authenticated.
| python3 -mjson.tool Makes the output more readable by sending it to the Python json decoder.

Output

The output contains the requested information as formatted by the Python json.tool:

{
    "data": {
        "computers": [
            {
                "active": false,
                "address": "192.168.95.128:4242",
                "alertState": 0,
                "alertStates": [
                    "OK"
                ],
                "blocked": false,
                "buildVersion": null,
                "computerId": 13,
                "creationDate": "2015-03-18T16:39:04.241-05:00",
                "guid": "681099810721783680",
                "javaVersion": "1.7.0_45",
                "lastConnected": "2015-03-18T16:42:55.482-05:00",
                "loginDate": "2015-03-18T16:39:07.570-05:00",
                "modelInfo": null,
                "modificationDate": "2015-03-18T16:42:55.482-05:00",
                "name": "WIN-FQNN6BGK47K",
                "orgId": 2,
                "osArch": "amd64",
                "osName": "win",
                "osVersion": "6.2",
                "parentComputerId": null,
                "productVersion": "3.7.0",
                "remoteAddress": "172.16.239.1",
                "service": "CrashPlan",
                "status": "Deactivated",
                "timeZone": "America/Chicago",
                "type": "COMPUTER",
                "userId": 2,
                "version": 1388728800370
            },
            {
                "active": true,
                "address": "192.168.95.128:4252",
                "alertState": 0,
                "alertStates": [
                    "OK"
                ],
                "blocked": false,
                "buildVersion": 31,
                "computerId": 12,
                "creationDate": "2015-03-12T11:53:40.861-05:00",
                "guid": "680201360538886016",
                "javaVersion": null,
                "lastConnected": "2015-03-12T17:17:23.909-05:00",
                "loginDate": "2015-03-12T16:23:12.272-05:00",
                "modelInfo": null,
                "modificationDate": "2015-03-12T17:17:23.909-05:00",
                "name": "WIN-FQNN6BGK47K",
                "orgId": 2,
                "osArch": null,
                "osName": "win",
                "osVersion": "6.2.9200.0",
                "parentComputerId": null,
                "productVersion": "3.7.0",
                "remoteAddress": "172.16.239.1",
                "service": "CrashPlan",
                "status": "Active",
                "timeZone": null,
                "type": "COMPUTER",
                "userId": 2,
                "version": 1413349200416
            }
        ]
    },
    "metadata": {
        "params": {},
        "timestamp": "2015-03-23T16:57:19.687-05:00"
    }
}

Adding parameters as described below can improve on this initial request.

Add parameters

Each API resource includes additional parameters, which can be used to search for specific data, filter and sort results, or specify other additional options. The parameters are not the same for each resource, so use the API documentation to review the available options for each resource you use.

To improve on the Computer request above, add parameters and specify values to tailor your results. The examples included below are only a few of the parameters available in the Computer resource.

Example Parameter API Documentation Description
srtKey key to sort on Sorts the results of the Computer request by one of several values, such as the computer's name or lastCompletedBackup.
srtDir direction of sort Sorts results in ascending or descending order.
pgSize the max number of objects to return Specifies a maximum number of results.
active optional filter to show only active or deactivated objects Allows the request to respond with only active or deactivated computers.
export option to specify an export Instructs the Computer request to return results in an exported format, such as a comma-separated values (CSV) file.

You can attach parameters to a curl request by adding one or more parameters and their values after a ? as shown below.

Example 1: Sort by recent connections

If you want to see which computers have most recently connected to your CrashPlan environment, you can sort the results of a Computer API request. This command sorts the Computer results by the last connection of the computer to a CrashPlan cloud instance:


curl -X GET -k "https://console.us1.crashplan.com/api/v1/Computer?srtKey=lastConnected" -H 'Authorization: Bearer <auth_token>' | python3 -mjson.tool

Example 2: Export to CSV

If you want to see a more readable information format, or store reports to review information on your CrashPlan environment over time, you can export the data of a Computer request to a CSV file. This command exports its results in a CSV format:


curl -X GET -k "https://console.us1.crashplan.com/api/v1/Computer?export=csv" -H 'Authorization: Bearer <auth_token>' | python3 -mjson.tool

Example 3: Sort and export to CSV

Combine multiple parameters in a single curl command by using the & character. This command sorts the Computer results by the last connection and exports the results in a CSV format:


curl -X GET -k "https://console.us1.crashplan.com/api/v1/Computer?srtKey=lastConnected&export=csv" -H 'Authorization: Bearer <auth_token>' | python3 -mjson.tool

Use cases for the computer resource

By combining the available resources, methods, and parameters of the CrashPlan API, you can create solutions for the specific needs of your CrashPlan environment. These examples show solutions that use only the Computer resource.

Report all devices

The CrashPlan API can help you regularly gather information on your CrashPlan environment for later use in reporting and statistics. This request exports a list of all your devices as a CSV:


curl -X GET -k "https://console.us1.crashplan.com/api/v1/Computer?srtKey=name&srtDir=asc&targetComputerGuid=rollup&incBackupUsage=true&incActivity=true&incCounts=true&active=true&alerted=false&obeyQueryLimit=true&export=csv" -H 'Authorization: Bearer <auth_token>' | python3 -mjson.tool

In fact, this curl command uses the same API request that the CrashPlan console uses when you select Devices > action menu > Export All. For information about how to convert CrashPlan console actions into curl commands, see our CrashPlan API tools article.

Identify inactive devices

You may have devices in your CrashPlan environment that have not connected to the CrashPlan cloud in some time, perhaps due to simply being powered down. This request creates a CSV of the computers in your CrashPlan environment beginning with those that have not connected to your CrashPlan environment in the longest time:


curl -X GET -k "https://console.us1.crashplan.com/api/v1/Computer?srtKey=lastConnected&active=true&export=csv" -H 'Authorization: Bearer <auth_token>' | python3 -mjson.tool

Identify largest device backups

Identifying the devices that are backing up the most information can help you more effectively manage your storage. This request lists the ten devices that are backing up the most data:


curl -X GET -k "https://console.us1.crashplan.com/api/v1/Computer?srtKey=archiveBytes&srtDir=DESC&pgSize=10&pagNum=1&active=true" -H 'Authorization: Bearer <auth_token>' | python3 -mjson.tool

To make this command more easily readable on a command line, process the output with the Python JSON decoder and filter the results to show only the device name using a command-line tool like grep:


curl -X GET -k "https://console.us1.crashplan.com/api/v1/Computer?srtKey=archiveBytes&srtDir=DESC&pgSize=10&pagNum=1&active=true" -H 'Authorization: Bearer <auth_token>' | python3 -mjson.tool | grep -w name

What's next

The Computer resource is just one of many resources in the CrashPlan API. After you understand the examples in this introduction, review the API documentation to learn about the other resources available.

Was this article helpful?
0 out of 0 found this helpful

Articles in this section