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:

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:

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:

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:

Possible responses:

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:

Possible responses:

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:

Possible responses:

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:

Possible responses:

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:

Possible responses:

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:

Possible responses:

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:

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.