Other APIs
Introduction
The main Comet Server API is described in detail in the API Guide. As well as making API requests to your Comet Server instances as described there, additional APIs are available for different purposes.
Comet Server web interface postMessage API
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:
Parameter name | Value |
---|---|
msg | app_loaded |
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:
Parameter name | Value |
---|---|
msg | session_login |
username | Admin username |
sessionkey | Pre-generated admin session key from the AdminAccountSessionStart or HybridSessionStart server API |
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:
Parameter name | Value |
---|---|
msg | user_session_login |
username | Customer username |
sessionkey | Pre-generated end-user session key from the UserWebSessionStart or AdminAccountSessionStartAsUser or HybridSessionStart server API |
Comet Server live event streaming
Additional Comet Server APIs are available to receive live, realtime notifications from the Comet Server of new jobs, completed jobs, and user profile configuration changes.
Because of the reversed direction of information, these APIs do not entirely fit the general documented pattern and are documented separately here.
There are two ways to configure these live event notifications: either as a webhook or as a websocket.
Webhooks
This feature is available in Comet Server 20.6.1 and later.
You can configure a URL to receive events. The Comet Server will submit events by HTTP POST
and must be able to reach the configured URL from its network position. The webhook's body is an event structure in JSON as described below in the "Message types" section.
An x-Comet-Tracing-Id
header is present in the webhook request. Your webhook endpoint should respond with an HTTP 200 OK
code to all POST events. If your webhook endpoint fails to do so, the failure will be logged in the Comet Server log, along with its corresponding x-Comet-Tracing-Id
header value; and Comet Server will retry the request a finite number of times.
Custom headers to be included in the webhook POST request can be configured using the CustomHeaders
field of WebhookOption
. This field can be set using the API endpoints as described below, or directly in the cometd.cfg
file:
...
"WebhookOptions": {
"ExampleOrganization": {
"URL": "http://example.com/webhooks",
"WhiteListedEventTypes": [],
"CustomHeaders": {
"Authorization": "Bearer f1d2d2f9",
"X-Custom-Header": "Custom header value"
}
}
},
...
Webhook messages are sent in parallel and may be unordered when received. When a webhook experiences an error and retries, the submission is not ordered.
You can use the webhook feature as follows:
Use the
AdminMetaWebhookOptionsGet
API to retrieve the current webhook configurationModify the data structure to add your own additional webhook endpoint in
WebhookOption
format.- If the
WhiteListedEventTypes
array is empty, all event types are sent. Otherwise, only the specified event types are sent.
- If the
Use the
AdminMetaWebhookOptionsSet
API to replace the server's current webhook configuration with the updated configuration.You should immediately receive the initial SEVT_META_HELLO webhook event to your configured endpoint.
- A SEVT_META_HELLO message will be sent every time the webhook queue is flushed. For instance, it will occur if the Comet Server is restarted.
The webhook configuration will be persisted in the cometd.cfg
file. You may also choose to make changes to this file directly.
Websocket
This feature is available in any version of Comet Server.
Instead of using a Webhook, you can make an outbound websocket connection. This method does not require your application to have a public URL. Messages will always be delivered sequentially in-order and will be delivered for as long as the websocket is held open.
If the websocket client is unable to drain messages sufficiently quickly from the TCP stream, event messages will be queued for publication up to an implementation-defined limit. After this limit, the websocket connection would be dropped by the Comet Server; in this case, a client should reconnect and perform a remedial sync using the standard Comet Server APIs to catch up on any missed status changes.
You can use the websocket feature as follows:
Make a GET request to
/api/v1/events/stream
.- Optionally, limit which events are received by adding the query param
allowList
with a comma-delimited list of streamable event numbers to filter on (e.g.?allowList=4100,4101
).
- Optionally, limit which events are received by adding the query param
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
, andTOTP
parameter values respectively. An empty-string text message frame can be used to skip providing a value.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 string200 OK
.The server will then send a text message frame for each event, containing an event structure in JSON as described below in the "Message types" section.
Message types
For both webhook and websocket sources, you will receive a JSON-encoded StreamableEvent structure. The Type
field indicates the type of the event and will be one of the SEVT_ constant values.
The first message you receive will have the SEVT_META_HELLO
type. This indicates that a new live-event-streaming session has been created.
Account.CometBackup.com API
As well as making API requests to your Comet Server instances described above, an API is also available for the account.CometBackup.com web application.
This additional API allows you to control some parts of your account.CometBackup.com account by making HTTP POST requests:
Supported Authentication Methods
You may use a password or API token for authentication with the account.cometbackup.com API. Specify the authentication type using the authType
parameter. If the authType
parameter is not specified, then it will default to the 'password' authentication type.
Authentication Type | Required Parameters |
---|---|
'password' | Provide the email and password parameters in the POST body |
'apiToken' | Provide the apiToken parameter in the POST body |
Example API request using the apiToken method of authentication:
curl -v -d 'apiToken=W2FAKETOKEN7Y&authType=apiToken&format=json' https://account.cometbackup.com/api/v1/downloads/list
You can manage API tokens for your account from the API token management page
LicenseRelax
Relax an existing Comet Server serial number.
- Endpoint:
POST https://account.cometbackup.com/api/v1/license/relax
- Request body in
application/x-www-form-urlencoded
format
Request parameters:
Parameter name | Value |
---|---|
authType | Specify the authentication type ('password' or 'authToken') |
authToken | Specify the authentication token (for 'authToken' method of authentication) |
email | Email address to log in to account.CometBackup.com |
password | Password to log in to account.CometBackup.com |
serial | Target serial number to relax |
Possible responses:
HTTP Code | Content-Type | Response Body |
---|---|---|
200 | text/plain | OK, the serial was relaxed successfully |
400 | text/plain | Invalid or missing parameter |
403 | text/plain | Invalid credentials |
500 | text/plain | Internal error |
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://account.cometbackup.com/api/v1/relax_license
("RelaxLicense")
LicenseCreate
Generate a new Comet Server serial number.
- Endpoint:
POST https://account.cometbackup.com/api/v1/license/create
- Request body in
application/x-www-form-urlencoded
format
Request parameters:
Parameter name | Value |
---|---|
authType | Specify the authentication type ('password' or 'authToken') |
authToken | Specify the authentication token (for 'authToken' method of authentication) |
email | Email address to log in to account.CometBackup.com |
password | Password to log in to account.CometBackup.com |
target_name | Friendly name for the serial number (optional) |
Possible responses:
HTTP Code | Content-Type | Response Body |
---|---|---|
200 | text/plain | Newly generated serial (plain text) |
400 | text/plain | Invalid or missing parameter |
403 | text/plain | Invalid credentials |
500 | text/plain | Internal error |
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://account.cometbackup.com/api/v1/create_license
("CreateLicense")
LicenseArchive
Deactivate and archive an existing Comet Server serial number
- Endpoint:
POST https://account.cometbackup.com/api/v1/license/archive
- Request body in
application/x-www-form-urlencoded
format
Request parameters:
Parameter name | Value |
---|---|
authType | Specify the authentication type ('password' or 'authToken') |
authToken | Specify the authentication token (for 'authToken' method of authentication) |
email | Email address to log in to account.CometBackup.com |
password | Password to log in to account.CometBackup.com |
serial | Target serial number to relax |
Possible responses:
HTTP Code | Content-Type | Response Body |
---|---|---|
200 | text/plain | OK, the serial was archived successfully |
400 | text/plain | Invalid or missing parameter |
403 | text/plain | Invalid credentials |
500 | text/plain | Internal error |
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://account.cometbackup.com/api/v1/archive_license
("ArchiveLicense")
LicenseListAll
List all your current Comet Server serial numbers
- Endpoint:
POST https://account.cometbackup.com/api/v1/license/list_all
- Request body in
application/x-www-form-urlencoded
format
Request parameters:
Parameter name | Value |
---|---|
authType | Specify the authentication type ('password' or 'authToken') |
authToken | Specify the authentication token (for 'authToken' method of authentication) |
email | Email address to log in to account.CometBackup.com |
password | Password to log in to account.CometBackup.com |
Possible responses:
HTTP Code | Content-Type | Response Body |
---|---|---|
200 | application/json | Array of objects, each object describing the Comet Server serial license |
400 | text/plain | Invalid or missing parameter |
403 | text/plain | Invalid credentials |
500 | text/plain | Internal error |
ReportActiveServices
List all currently active services
- Endpoint:
POST https://account.cometbackup.com/api/v1/report/active_services
- Request body in
application/x-www-form-urlencoded
format
Request parameters:
Parameter name | Value |
---|---|
authType | Specify the authentication type ('password' or 'authToken') |
authToken | Specify the authentication token (for 'authToken' method of authentication) |
email | Email address to log in to account.CometBackup.com |
password | Password to log in to account.CometBackup.com |
format | One of csv , json , or xlsx |
Possible responses:
HTTP Code | Content-Type | Response Body |
---|---|---|
200 | text/csv | My Active Services report in CSV format (if format=csv was supplied) |
200 | application/json | My Active Services report in JSON format (if format=json was supplied) |
200 | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet | My Active Services report in XLSX format (if format=xlsx was supplied) |
400 | text/plain | Invalid or missing parameter |
403 | text/plain | Invalid credentials |
500 | text/plain | Internal error |
ReportBillingHistory
List all deductions from your account balance
- Endpoint:
POST https://account.cometbackup.com/api/v1/report/billing_history
- Request body in
application/x-www-form-urlencoded
format
Request parameters:
Parameter name | Value |
---|---|
authType | Specify the authentication type ('password' or 'authToken') |
authToken | Specify the authentication token (for 'authToken' method of authentication) |
email | Email address to log in to account.CometBackup.com |
password | Password to log in to account.CometBackup.com |
format | One of csv , json , or xlsx |
Possible responses:
HTTP Code | Content-Type | Response Body |
---|---|---|
200 | text/csv | Credit Usage report in CSV format (if format=csv was supplied) |
200 | application/json | Credit Usage report in JSON format (if format=json was supplied) |
200 | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet | Credit Usage report in XLSX format (if format=xlsx was supplied) |
400 | text/plain | Invalid or missing parameter |
403 | text/plain | Invalid credentials |
500 | text/plain | Internal error |
LatestVersion
Retrieve information about the latest available version of Comet Server to download.
- Endpoint:
GET https://account.cometbackup.com/latestversion
- No request body
- No authentication required for this endpoint
Request parameters:
- No request parameters
Possible responses:
HTTP Code | Content-Type | Response Body |
---|---|---|
200 | application/json | Comet Server version information in JSON format |
500 | text/plain | Internal error |
Example Response:
{
"latest_stable": "20.8.3",
"latest_prerelease": "20.9.3",
"downloads_url": "https://account.cometbackup.com/downloads",
"updates_info": [
"20.8.3 Jupiter / 20.9.3 Voyager now available - release notes https://changelog.blog.cometbackup.com/ ",
"Disk Image overview - https://youtu.be/rcnMxvjQEfU"
]
}
List Comet server version
Retrive a list of Comet Server versions, including the ids for usage in the
- Endpoint
POST
https://account.cometbackup.com/api/v1/downloads/list - Request body in
application/x-www-form-urlencoded
format
Request Parameters:
Parameter name | Value |
---|---|
Email address to log in to account.cometbackup.com | |
password | Password to log in to account.cometbackup.com |
format | Format of the response; one of json (default), csv or xlsx |
Possible responses:
HTTP Code | Content-Type | Response Body |
---|---|---|
200 | application/json | A json list of server versions, ordered by the most recent release |
500 | text/plain | Internal error |
Example Response:
[
{
"version_key": "20.9.3",
"Name": "Comet Server Release Notes",
"Version": "20.9.3 \"Voyager\"",
"Download": "Download for Windows 107.68 MB Download for Linux (.deb) 98.53 MB Download for Linux (.rpm) 98.54 MB Download for Linux (other) 97.18 MB"
},
{
"version_key": "20.8.3",
"Name": "Comet Server Release Notes",
"Version": "20.8.3 \"Jupiter\"",
"Download": "Download for Windows 105.47 MB Download for Linux (.deb) 98.53 MB Download for Linux (.rpm) 98.54 MB Download for Linux (other) 97.18 MB"
}
]
Download Comet server Version
Download a version of the Comet Server.
- Endpoint
POST
https://account.cometbackup.com/api/v1/downloads/get - Request body in
application/x-www-form-urlencoded
format
Example:
wget --method POST \
--body-data 'email=youremail&password=yourpassword&platform=download_windows&version_key=20.9.3' \
--content-disposition \
https://account.cometbackup.com/api/v1/downloads/get
Request Parameters:
Parameter name | Value |
---|---|
Email address to log in to account.cometbackup.com | |
password | Password to log in to account.cometbackup.com |
version_key | A string key for this version, can be matched with the result of the Download List Api method. Additional values "latest", "latest-quarterly" are also accepted. |
platform | the string for the platform, should be one of ("download_windows", "download_linux_deb", "download_linux_rpm", "download_linux_tar, download_linux_arm64_deb, download_linux_arm64_rpm, download_linux_arm64_tar") |
Possible responses:
HTTP Code | Content-Type | Response Body |
---|---|---|
200 | application/octet-stream | a stream for the download |
500 | text/plain | Internal error |
Create Comet-Hosted Server instance
Create a Comet-Hosted Server instance from the command line. This is an async action, It will return OK if the command is dispatched, but you need to check the server status to ensure it is ready for other operations. To be certain you should healthcheck the dns that will be created for the instance.
- Endpoint:
POST
https://account.cometbackup.com/api/v1/cometgo - Request body in
application/x-www-form-urlencoded
format
Request parameters:
Parameter name | Value |
---|---|
Email address to log in to account.cometbackup.com | |
password | Password to log in to account.cometbackup.com |
region | The region which this instance should be created in I.E 'ap-southeast-2'. |
subdomain | Subdomain for the new Comet-Hosted Server instance. |
server_name | Server Name for display in the accounts dashboard site |
Possible responses:
HTTP Code | Content-Type | Response Body |
---|---|---|
201 | application/json | { "status": "OK" } |
403 | application/json | { "status": "error" } |
500 | application/json | {"status": "error" } |
Get Comet-Hosted Server status
Returns the status, dns and admin crednetials for controlling the server
- Endpoint:
POST
https://account.cometbackup.com/api/v1/cometgo/status - Request body in
application/x-www-form-urlencoded
format
Request parameters:
Parameter name | Value |
---|---|
hosted_server_id | the identifier of the hosted server |
Possible responses:
HTTP Code | Content-Type | Response Body |
---|---|---|
200 | application/json | The API response with status "OK" and attached instance details |
403 | application/json | { "status": "error" } The request is denied for authorization |
500 | application/json | {"status": "error" } There was an error with the request, report to Comet Support. |
Sample instance status response:
{
"status": "OK",
"data": {
"hosted_server_id": "506",
"install_status": "Deleting server...",
"aws_status": "terminated",
"region_name": "ap-southeast-2",
"user_dns": "neat-backup-company-3.offsitenetwork.net",
"created_at": "2020-04-20 15:02:10",
"date_deleted": "2020-04-29 10:50:30",
"admin_password": "<redacted>",
"admin_username": "admin",
"server_name": "hosted-server-3"
}
}
Terminate Comet-Hosted Server instance
Terminates a Comet-Hosted Server instance
- Endpoint:
POST
https://account.cometbackup.com/api/v1/cometgo/terminate - Request body in
application/x-www-form-urlencoded
format
Request parameters:
Parameter name | Value |
---|---|
hosted_server_id | the identifier of the hosted server |
Possible responses:
HTTP Code | Content-Type | Response Body |
---|---|---|
202 | application/json | { "status": "OK"} The command has been dispatched, and the server will be terminated eventually |
403 | application/json | { "status": "error" } The request is denied for authorization |
500 | application/json | {"status": "error" } There was an error with the request, report to Comet Support. |
List Comet-Hosted Server instances
List Comet-Hosted Server instances
- Endpoint:
POST
https://account.cometbackup.com/api/v1/cometgo/list - Request body in
application/x-www-form-urlencoded
format
Request parameters:
Parameter name | Value |
---|---|
offset | the offset to start returning results from, by default this is 0 |
limit | the number of instances to return, by default this is 100 |
Possible responses:
HTTP Code | Content-Type | Response Body |
---|---|---|
200 | application/json | { "status": "OK", "data":[]} contains a data array of the results, a result item matches what is returned for querying a single Comet Go! instance status |
403 | application/json | { "status": "error" } The request is denied for authorization |
500 | application/json | {"status": "error" } There was an error with the request, report to Comet Support. |
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.
Custom Remote Bucket
The "Custom Remote Bucket" is a possible option for the Requestable Storage Vault provider in the Comet Server configuration settings. The Requestable Storage Vault provider system allows administrators and authorized users to easily allocate new Storage Vaults inside a user account that are attached to a real storage location created by the provider.
As well as the built-in provider types for allocating Comet Storage Role, Backblaze B2, and Wasabi buckets, you can use the "Custom Remote Bucket" provider type to implement a custom storage location.
This is of interest for MSPs that want to bring an advanced direct-to-cloud storage option, or storage providers that want to develop an integration that easily plugs into Comet Servers to provide direct-to-cloud storage. The resulting Storage Vault can use any storage protocol supported by Comet, such as S3-compatible, Local Path, or SFTP.
To use this feature, you should provide a URL endpoint.
- Comet Server will make an HTTP POST request to your configured endpoint
- Your endpoint should respond with a HTTP 2xx status code.
- Your endpoint should respond with a
DestinationLocation
structure in JSON format - Comet Server will add the resulting
DestinationLocation
structure into the requesting user's profile as a new Storage Vault.
Sample endpoint implementation
#!/usr/bin/env python3
#
# This is an example script to show how Comet Server can request custom
# buckets from a web server script
#
# Usage:
# 1. python3 ./sample-custom-remote-bucket.py
# 2. Set up a Custom Remote Bucket in Comet Server using the URL: http://127.0.0.1:8000/request-bucket
#
# Configuration:
BIND_IP = "127.0.0.1" # could be any IP; leave blank to bind to all IP addresses
BIND_PORT = 8000
#
import http.server
import socketserver
# CustomRemoteBucketHandler is the HTTP server that is able to respond to
# Comet Server's requests when they happen.
class CustomRemoteBucketHandler(http.server.BaseHTTPRequestHandler):
def __init__(self, request, client_addr, server):
"""Boilerplate for a custom HTTP service"""
super().__init__(request, client_addr, server)
def do_GET(self):
"""Handle GET requests (regular page loads)"""
if self.path == "/":
self.do_homepage()
else:
self.send_error(404)
def do_POST(self):
"""Handle POST requests (form submissions)"""
if self.path == "/request-bucket":
self.do_requestBucket()
else:
self.send_error(404)
def do_homepage(self):
"""Render the home page for users who visit this server directly"""
self.send_response(200)
self.send_header('Content-Type', 'text/html;charset=UTF-8')
self.end_headers()
self.wfile.write("""<!DOCTYPE html>
<p style="color:red;font-weight:bold;">
This is a test server for the custom remote bucket feature! Not to be used directly!
</p>
""".encode())
def do_requestBucket(self):
"""Accept a Custom Remote Bucket request from Comet Server"""
self.send_response(200)
self.send_header('Content-Type', 'application/json')
self.end_headers()
# Talk to your storage platform to allocate new access credentials
# TODO
# Respond with a Comet DestinationLocation object in JSON format
# The DestinationType should be a DESTINATIONTYPE_ number from https://docs.cometbackup.com/latest/api/api-constants#destinationtype
# Use any of the keys from https://docs.cometbackup.com/latest/api/api-data-structures/#api-struct-DestinationLocation
self.wfile.write("""{
"DestinationType": 1000,
"S3Server": "minio.example.com",
"S3UsesTLS": false,
"S3AccessKey": "",
"S3SecretKey": "",
"S3BucketName": "",
"S3Subdir": "",
"S3UsesV2Signing": false
}""".encode())
# Application starts up here if it is run directly
if __name__ == "__main__":
with socketserver.TCPServer((BIND_IP, BIND_PORT), CustomRemoteBucketHandler) as httpd:
print("Serving at %s:%s..." % (BIND_IP, BIND_PORT))
httpd.serve_forever()