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
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 theauthorize
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
orNone
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
/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 specifyInstall
orRemove
. 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.