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:

RelaxLicense 

Relax an existing Comet Server serial number.

  • Endpoint: POST https://cometbackup.com/api/v1/relax_license
  • 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

CreateLicense 

Generate a new Comet Server serial number.

  • Endpoint: POST https://cometbackup.com/api/v1/create_license
  • 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

ArchiveLicense 

Deactivate and archive an existing Comet Server serial number

  • Endpoint: POST https://cometbackup.com/api/v1/archive_license
  • 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

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