About the API Implementation

Learn about the API version, authentication, request format, supported requests, and a sample interaction.

Authentication

Authentication to the Uptrack API server uses a username and an API key that are specified in custom HTTP headers.

All requests must include the following HTTP headers:

  • X-Uptrack-User: the API username of the user who is making the request.
  • X-Uptrack-Key: the API key of the user who is making the request.

API Request Format

API requests or responses include JSON-encoded data in the request body.

Set the following HTTP headers in all requests:

  • Content-Type: application/json
  • Accept:: application/json

These headers aren't required, as the API only uses JSON-encoded data, but future versions of the API might use other data-encoding formats.

API Endpoints

This document describes version 1 of the API. All requests go to paths that begin with https://uptrack.api.ksplice.com/api/1/. The following endpoints are available:

Interaction Sample

The following example, is provided as a reference only and shows how to list the systems managed for a Ksplice account by using the API. 

curl -X GET "https://uptrack.api.ksplice.com/api/1/machines" \
  -H "Accept: application/json" \
  -H "X-Uptrack-User: jo.admin@example.com" \
  -H "X-Uptrack-Key: 3af3c2c1ec407feb0fdc9fc1d8c4460c"

The server authenticates the request and responds with a list of the systems, for example: 

[
  {
    "status": "uptodate",
    "autoinstall": true,
    "uuid": "00086980-47cb-4486-81c0-4fe3299bad90",
    "mmap_min_addr": 65536,
    "ip": "192.168.248.238",
    "hostname": "host1.example.com",
    "uptrack_client_version": "1.2.80",
    "active": true,
    "authorization": "allowed",
    "last_seen": "2025-05-12T11:19:21Z"
  }
]

GET /api/1/machines

The GET /api/1/machines API request returns a list of all the registered systems. This list includes inactive systems that have uninstalled Uptrack or any systems that haven't reported to the Uptrack server recently. The list doesn't include systems that you have hidden by using the web interface. The response shows a list of systems, which are represented as dictionaries, as shown in the following example: 
[
  {
    "status": "uptodate",
    "autoinstall": true,
    "uuid": "00086980-47cb-4486-81c0-4fe3299bad90",
    "mmap_min_addr": 65536,
    "ip": "192.168.248.238",
    "hostname": "host1.example.com",
    "uptrack_client_version": "1.2.80",
    "active": true,
    "authorization": "allowed",
    "last_seen": "2025-05-12T11:19:21Z"
  }
]

The following fields are provided in the response:

status

Contains one of the following values:

  • outofdate - Updates are available for installation on the system.
  • unsupported - The system's kernel isn't supported by Ksplice Uptrack.
  • uptodate - All available updates have been installed on the system.
authorization

Contains one of the following values:

  • allowed - The system is allowed to communicate with the Uptrack servers and to receive updates.
  • denied - The system has been denied access to the Uptrack servers by using the web interface, uptrack-api-authorize, or the authorize API call.
  • pending - This account has the default deny policy set for new systems, and the system hasn't yet been authorized.
autoinstall

Indicates whether autoinstall is set on the system.

mmap_min_addr

Is the value of /proc/sys/vm/mmap_min_addr or None for clients before version 1.0.3.

uptrack_client_version

Is the version of the Uptrack client that the system is running.

GET /api/1/machine/$UUID/describe

The GET /api/1/machine/$UUID/describe API request returns information about the system with the specified UUID. The UUID of a system is stored in /var/lib/uptrack/uuid and can be retrieved by using the machines query. The response is a dictionary of the same form that GET /api/1/machines returns, except that it includes the following fields:
effective_kernel

Ksplice has applied all the important security and reliability updates that are needed to bring the system into line with this kernel version.

group

The group to which the system is assigned. You can also use the web interface to manage system groups.

installed_updates

A list of 2-element dictionaries of the form {'ID': update_id, 'Name': update_name} that represent the updates installed on the system. update_id is the ID code of an update (for example, diptbg4f) and update_name is a short descriptive name for the update (for example, CVE-2010-0415: Information Leak in sys_move_pages).

original_kernel

The kernel version of the system before any Ksplice updates were applied.

steps

A list of two-element lists of the form [action, {'ID': update_id, 'Name': update_name}], representing the updates that need to be installed or removed to update the system. For the action argument, you can specify Install or Remove. Note that an existing update is removed if it superseded by a more recent version.

POST /api/1/machine/$UUID/authorize

The POST /api/1/machine/$UUID/authorize API request authorizes the system with the specified UUID to access the Uptrack service if you have configured the account to deny access to new systems.

The content is a dictionary of the following form: 

{authorized: boolean}

Specify the boolean argument as true to authorize the system or false to revoke authorization.

POST /api/1/machine/$UUID/group

The POST /api/1/machine/$UUID/group API request changes the group of the system with the specified UUID.

The content is a dictionary that uses the following form: 

{group_name: string}

In the previous example, string is the name of the new group. The group is created if it doesn't already exist. Note that if the account doesn't have a system with the specified UUID, the request results in an HTTP 404 error.

To remove a system from a group, you can set the group to a different name, or you can specify an empty string for no group.