API Guide 

Overview 

The Comet Server can be controlled via an API over HTTP / HTTPS. Every action that can be performed via the Comet Server web interface or the Comet Backup client software interface can also be performed by the API.

You can see the full list of Comet Server API endpoints in the "API Reference" document. This document includes information about

  • Supported API endpoints,
  • Data structures used by the API, and
  • Constant values used by the API.

Compatibility 

The Comet Server API is backward compatible, so we recommend using the latest available online documentation.

However, you can refer to the documentation for a specific version of Comet Server, included as local files with your copy of Comet Server.

Quick Start (examples) 

These examples make a network request to a Comet Server at http://127.0.0.1/, with the Auth Role enabled, using the administrator credentials admin:admin, to retrieve a list of user accounts.

cURL 

curl -X POST -d 'Username=admin&AuthType=Password&Password=admin' 'http://127.0.0.1/api/v1/admin/list-users'

PHP (Composer) 

A set of PHP classes are available to simplify using the Comet Server API. Please see CometBackup/comet-php-sdk at GitHub for more information.

$server = new \Comet\Server("http://127.0.0.1:8060/", "admin", "admin");
var_dump( $server->AdminListAccounts() );

PHP (cURL) 

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,  'http://127.0.0.1/api/v1/admin/list-users');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
    'Username' => 'admin',
    'AuthType' => 'Password',
    'Password' => 'admin',
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);

var_export($response);

Powershell 

Invoke-Webrequest -Uri http://127.0.0.1/api/v1/admin/list-users -Method POST -Body @{Username="admin"; AuthType="Password"; Password="admin"} | select Content

Modifying an account 

# Look up an account profile

$lookup = Invoke-Webrequest -Uri http://127.0.0.1/api/v1/admin/get-user-profile -Method POST -Body @{
    Username="admin"; AuthType="Password"; Password="admin";
    TargetUser="testuser"
}
$profile = ConvertFrom-Json $lookup

# Modify the profile however you like

$profile.PolicyID = "8876b0d8-8f26-4fab-9ac9-9274ae030cfc"

# Convert back to JSON and submit to the server

$updated_json = ConvertTo-JSON $profile -Depth 99

Invoke-WebRequest -Uri http://127.0.0.1/api/v1/admin/set-user-profile -Method POST -Body @{
    Username="admin"; AuthType="Password"; Password="admin";
    TargetUser="testuser";
    ProfileData=$updated_json
}

Find all Comet-type Storage Vault URLs 

# Look up all account profiles

$lookup = Invoke-Webrequest -Uri http://127.0.0.1/api/v1/admin/list-users-full -Method POST -Body @{
    Username="admin"; AuthType="Password"; Password="admin";
}
$all_users = ConvertFrom-Json $lookup

# CSV header

Write-Host "Username,Storage Vault Description,Comet Server URL"

# Look at each user's profile

foreach ($user in $all_users | Get-Member -type NoteProperty) { 
    foreach ($storage_vault_id in $all_users."$($user.Name)".Destinations | Get-Member -type NoteProperty) {

        $storage_vault = $all_users."$($user.Name)".Destinations."$($storage_vault_id.Name)"

        if ($storage_vault.DestinationType -eq 1003) { # DESTINATIONTYPE_COMET = 1003
            Write-Host "$($user.Name),$($storage_vault.Description),$($storage_vault.CometServer)"
        }
    }
}

Set policies for all user accounts 


# Class keyword requires PowerShell 5.0+ or greater
class CometServer {
    [string]$Address
    [string]$AdminUsername
    [string]$AdminPassword

    CometServer([string]$Address, [string]$AdminUsername, [string]$AdminPassword) {
        $this.Address = $Address
        $this.AdminUsername = $AdminUsername
        $this.AdminPassword = $AdminPassword
    }

    [string[]]ListUsers() {
        return $this._request("api/v1/admin/list-users")
    }

    [Object]GetUserProfile([string]$Username) {
        return $this._request("api/v1/admin/get-user-profile", @{"TargetUser"= $Username})
    }

    [Object]SetUserProfile([string]$Username, [Object]$Profile) {
        $ProfileJSON = ConvertTo-JSON $Profile -Depth 99

        return $this._request("api/v1/admin/set-user-profile", @{"TargetUser"=$Username; "ProfileData"=$ProfileJSON})
    }

    [Object]_request([string]$Endpoint) {
        return $this._request($Endpoint, @{})
    }

    [Object]_request([string]$Endpoint, [hashtable]$extraParams) {
        $allParams = @{
            Username = $this.AdminUsername;
            AuthType = "Password";
            Password = $this.AdminPassword;
        }
        foreach ($h in $extraParams.GetEnumerator()) {
            $allParams[$h.Name] = $h.Value
        }

        $response = Invoke-Webrequest -Uri ($this.Address + $Endpoint) -Method POST -Body $allParams
        $ret = ConvertFrom-Json $response
        return $ret
    }
}

$cs = [CometServer]::new("http://127.0.0.1:8060/", "adminuser", "adminpass")

$all_users = $cs.ListUsers()
foreach($username in $all_users) {
    $profile = $cs.GetUserProfile($username)
    $profile.PolicyID = "00000000-0000-4a00-0000-000000000000"
    $cs.SetUserProfile($username, $profile)
}

VBScript 

set oRequest = CreateObject("Microsoft.XMLHTTP")
oRequest.open "POST", "http://127.0.0.1/api/v1/admin/list-users", false
oRequest.setRequestHeader "Content-Type", "application/x-www-form-urlencoded"
oRequest.send "Username=admin&AuthType=Password&Password=admin"
MsgBox oRequest.responseText

Go (golang) 

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func ListUsers() {
    resp, err := http.Post(
        "http://127.0.0.1/api/v1/admin/list-users",
        "application/x-www-form-urlencoded",
        []byte("Username=admin&AuthType=Password&Password=admin"),
    )
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(body))
}

Python 3 

#!/usr/bin/python3

import json
import urllib.parse
import urllib.request

class CometServer(object):
    def __init__(self, url, adminuser, adminpass):
        self.url = url
        self.adminuser = adminuser
        self.adminpass = adminpass

    def AdminListUsers(self):
        """List all usernames on the Comet Server"""
        return self._request("api/v1/admin/list-users", {})

    def _request(self, endpoint, extraparams):
        """Make API request to Comet Server and parse response JSON"""
        apiRequest = urllib.request.Request(
            url = self.url + endpoint,
            data = urllib.parse.urlencode({
                "Username": self.adminuser,
                "AuthType": "Password",
                "Password": self.adminpass,
                **extraparams
            }).encode('utf-8')
        )

        ret = None
        with urllib.request.urlopen(apiRequest) as apiResponse:
            ret = json.loads( apiResponse.read() )

        return ret

def main():
    cs = CometServer("http://127.0.0.1:8060/", "admin", "admin")
    print( cs.AdminListUsers() )

if __name__ == "__main__":
    main()

Other API - Comet Server web interface postMessage API 

As well as making API requests to your Comet Server instances described above, an API is also available for the Comet Server web interface frontend.

This additional API allows you to control some parts of the web interface by making postMessage calls in Javascript. Messages will be sent in either direction, as Javascript objects, in the general form {msg: "message_type", other_parameters: .... }.

To use this API, create a Comet Server web interface window (e.g. by using window.open() or <iframe>), and add a message event listener to wait for the AppLoaded API message described below.

AppLoaded 

Notification sent to the opener window when the Comet Server web interface is ready to receive other postMessage requests.

  • Message format: Object
  • Direction: Response (Sent by Comet Server web interface to caller)

Object parameters:

Parameter name Value
msg app_loaded

SessionLogin 

Perform a single sign-on (SSO) login to the Comet Server web interface, as an administrator account.

  • Message format: Object
  • Direction: Request (Sent by caller to Comet Server web interface)

Object parameters:

Parameter name Value
msg session_login
username Admin username
sessionkey Pre-generated admin session key from the AdminAccountSessionStart or HybridSessionStart server API

UserSessionLogin 

Perform a single sign-on (SSO) login to the Comet Server web interface, as an end-user account.

  • Message format: Object
  • Direction: Request (Sent by caller to Comet Server web interface)

Object parameters:

Parameter name Value
msg user_session_login
username Customer username
sessionkey Pre-generated end-user session key from the UserWebSessionStart or AdminAccountSessionStartAsUser or HybridSessionStart server API

Other API - Comet Server special APIs 

As well as making API requests to your Comet Server instances described above, some special-purpose APIs are available that do not fit the general documented pattern.

Live event streaming 

You can use Comet's API to receive live notifications of new events on the Comet server. This includes notifications of new jobs, completed jobs, and user profile configuration changes.

  1. Make a GET request to /api/v1/events/stream.

  2. The server will perform an HTTP Upgrade to a WebSocket connection.

  3. The client must emit five text message frames in order, containing Username, AuthType, Password, SessionKey, and TOTP parameter values respectively.

  4. If the authentication failed, the server will emit a text message frame containing the string 403 Unauth, and then drop the connection. If the authentication succeeded, the server will emit a text message frame containing the string 200 OK.

  5. Communication then proceeds in an API-specific manner.

Other API - CometBackup.com API 

As well as making API requests to your Comet Server instances described above, an API is also available for the CometBackup.com web application.

This additional API allows you to control some parts of your CometBackup.com account by making HTTP POST requests:

LicenseRelax 

Relax an existing Comet Server serial number.

  • Endpoint: POST https://cometbackup.com/api/v1/license/relax
  • Request body in application/x-www-form-urlencoded format

Request parameters:

Parameter name Value
email Email address to log in to CometBackup.com
password Password to log in to CometBackup.com
serial Target serial number to relax

Possible responses:

HTTP Code Content-Type Response Body
200 text/plain OK, the serial was relaxed successfully
400 text/plain Invalid or missing parameter
403 text/plain Invalid credentials
500 text/plain Internal error

This API can be accessed via an additional 1 endpoint(s) for backward compatibility. These aliases will be maintained indefinitely, but new applications should not use them.

  • POST https://cometbackup.com/api/v1/relax_license ("RelaxLicense")

LicenseCreate 

Generate a new Comet Server serial number.

  • Endpoint: POST https://cometbackup.com/api/v1/license/create
  • Request body in application/x-www-form-urlencoded format

Request parameters:

Parameter name Value
email Email address to log in to CometBackup.com
password Password to log in to CometBackup.com

Possible responses:

HTTP Code Content-Type Response Body
200 text/plain Newly generated serial (plain text)
400 text/plain Invalid or missing parameter
403 text/plain Invalid credentials
500 text/plain Internal error

This API can be accessed via an additional 1 endpoint(s) for backward compatibility. These aliases will be maintained indefinitely, but new applications should not use them.

  • POST https://cometbackup.com/api/v1/create_license ("CreateLicense")

LicenseArchive 

Deactivate and archive an existing Comet Server serial number

  • Endpoint: POST https://cometbackup.com/api/v1/license/archive
  • Request body in application/x-www-form-urlencoded format

Request parameters:

Parameter name Value
email Email address to log in to CometBackup.com
password Password to log in to CometBackup.com
serial Target serial number to relax

Possible responses:

HTTP Code Content-Type Response Body
200 text/plain OK, the serial was archived successfully
400 text/plain Invalid or missing parameter
403 text/plain Invalid credentials
500 text/plain Internal error

This API can be accessed via an additional 1 endpoint(s) for backward compatibility. These aliases will be maintained indefinitely, but new applications should not use them.

  • POST https://cometbackup.com/api/v1/archive_license ("ArchiveLicense")

LicenseListAll 

List all your current Comet Server serial numbers

  • Endpoint: POST https://cometbackup.com/api/v1/license/list_all
  • Request body in application/x-www-form-urlencoded format

Request parameters:

Parameter name Value
email Email address to log in to CometBackup.com
password Password to log in to CometBackup.com

Possible responses:

HTTP Code Content-Type Response Body
200 application/json Array of objects, each object describing the Comet Server serial license
400 text/plain Invalid or missing parameter
403 text/plain Invalid credentials
500 text/plain Internal error

ReportActiveServices 

List all currently active services

  • Endpoint: POST https://cometbackup.com/api/v1/report/active_services
  • Request body in application/x-www-form-urlencoded format

Request parameters:

Parameter name Value
email Email address to log in to CometBackup.com
password Password to log in to CometBackup.com
format One of csv, json, or xlsx

Possible responses:

HTTP Code Content-Type Response Body
200 text/csv My Active Services report in CSV format (if format=csv was supplied)
200 application/json My Active Services report in JSON format (if format=json was supplied)
200 application/vnd.openxmlformats-officedocument.spreadsheetml.sheet My Active Services report in XLSX format (if format=xlsx was supplied)
400 text/plain Invalid or missing parameter
403 text/plain Invalid credentials
500 text/plain Internal error

ReportBillingHistory 

List all deductions from your account balance

  • Endpoint: POST https://cometbackup.com/api/v1/report/billing_history
  • Request body in application/x-www-form-urlencoded format

Request parameters:

Parameter name Value
email Email address to log in to CometBackup.com
password Password to log in to CometBackup.com
format One of csv, json, or xlsx

Possible responses:

HTTP Code Content-Type Response Body
200 text/csv Credit Usage report in CSV format (if format=csv was supplied)
200 application/json Credit Usage report in JSON format (if format=json was supplied)
200 application/vnd.openxmlformats-officedocument.spreadsheetml.sheet Credit Usage report in XLSX format (if format=xlsx was supplied)
400 text/plain Invalid or missing parameter
403 text/plain Invalid credentials
500 text/plain Internal error

LatestVersion 

Retrieve information about the latest available version of Comet Server to download.

  • Endpoint: GET https://cometbackup.com/latestversion
  • No request body

Request parameters:

  • No request parameters

Possible responses:

HTTP Code Content-Type Response Body
200 application/json Comet Server version information in JSON format
500 text/plain Internal error

Appendix 

Two-Factor Authentication for the Comet Server API 

We would recommend against using two-factor authentication for the Comet API. It is possible to do this, but (A) it's not really meaningful for an automated process to have two factors of authentication; and also (B) it's not currently supported by our PHP SDK on GitHub.

We would recommend creating a new Comet Server admin account just for API purposes with a long random password.

Advanced usage 

If it's really seriously needed, it is possible to make any of the API requests using these authentication types: any Comet Server API request needs to be authenticated, and you can authenticate by setting the AuthType parameter to any one of Password, SessionKey, PasswordTOTP, or PasswordU2F; the latter two (TOTP / U2F) being the two currently supported methods of two-factor authentication in Comet Server.

We would suggest only using PasswordTOTP and PasswordU2F only with the AdminAccountSessionStart API, that will give you a single SessionKey token to use with other API calls. Performing the entire TOTP / U2F handshake on every API call is probably an unreasonable amount of overhead. To authenticate using SessionKey mode, the API request should contain a valid SessionKey parameter that you get from the AdminAccountSessionStart API back in the SessionKeyRegeneratedResponse response structure.

To authenticate using Password mode, the API request should contain a valid Password parameter (of the admin account's password), as per the examples in https://cometbackup.com/docs/api#quick-start-examples . Then, if a password-only is insufficient for the account, the API will respond with a HTTP 449 status ("Retry With"), and a X-Comet-TOTP-Requested: 1 header or a X-Comet-U2F-Challenge: ... header. You should use this information to determine if a TOTP or U2F login is suitable.

To authenticate using PasswordTOTP mode, the API request should contain both a valid Password parameter (of the admin account's password) and a valid TOTP parameter. A TOTP code is a 6-digit number that changes every 30 seconds. Both the client and server calculate it from a shared secret. You should find the current secret by decoding the QR code for the user, and then use a library in your programming language to generate the current 6-digit value for the current timestamp.

To authenticate using PasswordU2F mode, the API request should contain a valid Password parameter (of the admin account's password) and a valid U2FSign POST parameter. You can use the information from the previous X-Comet-U2F-Challenge response header, to generate a U2F signature with your U2F hardware device, and fill in the U2FSign POST parameter as a U2FSignResponse struct in JSON encoding.