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 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 ¶

Comet's 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, 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

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

Special APIs ¶

Single sign-on ¶

You can use Comet's API to integrate single sign-on into Comet Server.

Use the AdminAccountSessionStart API to generate a session key for the administrative user.
Open the Comet Server web interface in a new window.
Submit an HTML postMessage event to the Comet Server window, containing an object in the format {msg:"session_login",username:"",sessionkey:""} providing a valid username and session key.

This approach means it is not necessary to expose the administrator credential to the end user.

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.

Make a GET request to /api/v1/events/stream.
The server will perform an HTTP Upgrade to a WebSocket connection.
The client must emit five text message frames in order, containing Username, AuthType, Password, SessionKey, and TOTP parameter values respectively.
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.
Communication then proceeds in an API-specific manner.