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: