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 dedicated documentation sections for API Methods, API Constants, and API Data Structures.

The Comet Server web interface is developed solely using this publicly documented API. You are invited to use the Web Browser network inspector tools to help find real-world example API calls.

Compatibility

The Comet Server API is backward compatible: Integration code developed against older versions of Comet Server should continue to work with newer versions of Comet Server. For the API endpoints publicly documented in this section, our company intends to maintain this compatibility in perpetuity.

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

Compatibility with Server 2012 R2 and earlier

If your Comet Server is using HTTPS, the version of Powershell on Windows Server 2012 R2 will not make a TLS 1.2 connection by default. Comet Server requires TLS 1.2 or higher when accessed over HTTPS. You can resolve this issue by adding this line to the top of your Powershell script:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

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:8060/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.PSObject.Properties) { 
    foreach ($storage_vault in $user.Value.Destinations.PSObject.Properties) { 
        
        if ($storage_vault.Value.DestinationType -eq 1003) { # DESTINATIONTYPE_COMET = 1003
            Write-Host "$($user.Value.Username),$($storage_vault.Value.Description),$($storage_vault.Value.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)

A Go SDK is available to simplify using the Comet Server API. Please see CometBackup/comet-go-sdk at GitHub for more information. The repo includes some code examples using the SDK as well.

Here's a small example:

import (
    "encoding/json"
    "fmt"

    cometsdk "github.com/CometBackup/comet-go-sdk"
)

func PrintRecentJobs() {
    client, err := cometsdk.NewCometAPIClient("http://localhost:8060", "admin", "admin")
    if err != nil {
        panic(err)
    }

    profile, err := client.AdminGetJobsRecent()
    if err != nil {
        panic(err)
    }

    bytes, err := json.MarshalIndent(profile, "", "   ")
    if err != nil {
        panic(err)
    }

    fmt.Println(string(bytes))
}

Alternatively, you can handcraft the request, but you lose the benefit of having data types to marshal/unmarshal JSON with:

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()

Ruby (Gem)

A Ruby Gem is available to simplify using the Comet Server API. Please see comet_backup_ruby_sdk at RubyGems.org for more information.

require 'comet_backup_ruby_sdk'

client = Comet::CometServer.new("http://127.0.0.1:8060", "admin", "admin")
client.admin_list_users

Ruby (net/http)

require 'net/http'

uri = URI('http://127.0.0.1:8060/api/v1/admin/list-users')
params = {
    'Username' => 'admin',
    'AuthType' => 'Password',
    'Password' => 'admin'
}

res = Net::HTTP.post_form(uri, params)
if res.is_a?(Net::HTTPSuccess)
    puts res.body
end

Javascript and Typescript

A Javascript and Typescript library is available to simplify using the Comet Server API. Please see CometBackup/comet-js-sdk at GitHub for more information.

Overview​

Compatibility​

Quick Start (examples)​

cURL​

PHP (Composer)​

PHP (cURL)​

Powershell​

Compatibility with Server 2012 R2 and earlier​

Modifying an account​

Find all Comet-type Storage Vault URLs​

Set policies for all user accounts​

VBScript​

Go (golang)​

Python 3​

Ruby (Gem)​

Ruby (net/http)​

Javascript and Typescript​