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.

This document ¶

This document is available from two locations:

Online at cometbackup.com, where the API documentation refers to the latest released version of Comet Server
In your Comet Server install directory in the docs/ subdirectory, where the API documentation refers to your installed version of Comet Server

Comet's API is backward compatible, so we recommend using the latest available documentation. However, you can use the local copy to access documentation for your specific version of Comet Server if necessary.

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 ¶

<?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))
}

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.