Release Notes REST API

Empirum REST API Release Notes

+ More

Table of Contents

Empirum REST API v1.0.4 – Release Notes Updating Pre-Release Versions Breaking Changes Removed Endpoints Patch Operations Require a Product Scope Other Behavior Changes New Endpoints Computer Inventory Agent Templates Computer Roles Effective Assignments and Reverse Lookups Software Deployment and Group Management Tags and Depot Topology Depot Servers and Synchronization Package Import Backend Queues and Tasks Custom Field Configuration and Patch Products Changes to Existing Endpoints Administration and Security Documentation Upgrade Notes

Empirum REST API v1.0.4 – Release Notes

This release summarizes all changes since v1.0.6.0. It adds 99 new endpoints covering computer inventory with 46 detail views, effective assignment lookups, Agent Template management, computer roles, group search, depot topology and tags, depot synchronization, package import, backend queue and task monitoring, custom field configuration, and several group management operations. Existing endpoints were extended with new parameters and response fields, and the API description now contains parameter and field descriptions throughout.

Updating Pre-Release Versions

This release also contains breaking changes coming from the pre-release versions. Please review the section "Breaking Changes" before updating existing integrations.

 

Breaking Changes

Removed Endpoints

The following endpoints are no longer available. Five of them were moved to the new inventory path and behave the same way under their new address.

Removed Endpoint Replacement
GET /api/computer/{id}/batteries GET /api/computer/{id}/inventory/batteries
GET /api/computer/{id}/disks GET /api/computer/{id}/inventory/disks
GET /api/computer/{id}/installed-software GET /api/computer/{id}/inventory/installed-software
GET /api/computer/{id}/network-adapters GET /api/computer/{id}/inventory/network-adapters
GET /api/computer/{id}/services GET /api/computer/{id}/inventory/services
POST /api/patches/products/{productId}/approval None. Approve individual patches with POST /api/patches/{patchId}/approval and the productId parameter.
POST /api/pmgroup/{id}/products None. Add patches to a PM group with POST /api/pmgroup/{id}/patches and the productId field.
GET /health No longer part of the published API description.

 

Patch Operations Require a Product Scope

A patch is only unique by the combination of patchId and productId. Operations that previously acted on all product versions of a patch now work on one product version:

  • POST /api/patches/{patchId}/approval requires the new query parameter productId. If it is missing, the API returns 400 with ProductScopeRequired and lists the available product versions.
  • POST /api/pmgroup/{id}/patches requires the new request field productId. A missing value returns the same 400 response.
  • DELETE /api/patches/{patchId}/approval accepts an optional productId. Without it, every link item of the patch is reverted.

Use the new endpoint GET /api/patches/{patchId}/products to list the product versions a patch is linked into. The response field productId was also added to the patch items returned by the missing-patch, patch detail, and patch status endpoints, so the value can be taken directly from those results.

Other Behavior Changes

  • POST /api/auth/token can now respond with 429 Too Many Requests. Client code should wait and retry instead of repeating the request immediately.
  • DELETE /api/admin/principals/{id} and DELETE /api/admin/local-principals/{id} accept a new query parameter force. It is required to delete a principal that has the new property protected set.

New Endpoints

Computer Inventory

Detailed hardware and software inventory from the last Empirum scan, following the structure of the inventory tree in the Empirum Management Console. All endpoints require the role computer.read.

GET /api/computer/{id}/inventory returns the aggregated inventory of one computer in a single call: core record, system info, BIOS, computer system, disks, network adapters, batteries, printers, video controllers, mainboard, memory modules, physical disks, TPM, and more. List sections are not paged and are capped at 500 rows each. Installed software and services are not included.

The following detail endpoints are available below /api/computer/{id}/inventory/:

Area Endpoints
Core hardware bios, computer-system, processors, video-controllers, monitors, printers
Relocated from the previous paths batteries, disks, network-adapters, installed-software, services
Mainboard and memory mainboard, memory-modules, memory-controllers, caches, slots, port-connectors, tpm
DMI/SMBIOS dmi-bios, dmi-processors, dmi-system
Storage and controllers physical-disks, cdrom-drives, floppy-controllers, ide-controllers, scsi-controllers
Peripherals and ports keyboards, pointing-devices, sound-devices, modems, infrared-devices, serial-ports, usb-controllers, usb-hubs, pcmcia-controllers
Users and network user-accounts, user-profiles, user-autostart, user-links, shares, network-connections
Software and custom data files, middleware, custom-wmi, user-defined

memory-modules hides empty memory banks unless includeEmpty=true is set. The result of files can be large, so use paging.

 

Agent Templates

Agent Templates can now be created, changed, and deleted through the API. All three operations require the role package.write.

Method Path Description
POST /api/agent-templates Creates an Agent Template, like File > New in the Agent Configurator. Without copyFromId the template starts with the default settings of the Management Console. With copyFromId the whole configuration of that template is copied. Settings groups in the body such as reboot and polling are applied on top. The first template of a database becomes the default template.
PATCH /api/agent-templates/{id} Changes the name and the reboot and polling settings of a template (JSON merge-patch, omitted members keep their stored value). Settings are validated against the resulting state, and nothing is written when anything is invalid.
DELETE /api/agent-templates/{id} Deletes a template. The template is marked for deletion and removed by the AgentPush service shortly afterwards, together with its group assignments.

Deleting returns 409 for the default template, for a template that is assigned to groups unless force=true is set, and for a template that a boot configuration uses.

 

The Agent Template responses now contain the full configuration: description, isDefault, reboot, polling, bandwidth, cache, localCache, server, serverSelection, protocols, timeframes, installation, agentUi, azure, xenApp, and prebootAuthentication. When a single template is read, warnings lists inconsistencies the Management Console would report. The template search accepts the new filters description and isDefault.

Computer Roles

Method Path Description Requires Role
GET /api/computer/roles Lists the assignable computer roles. computer.read
GET /api/computer/{id}/roles Lists the roles assigned to a computer. The result is an empty array if none are assigned and matches management.computerRoles of GET /api/computer/{id}/system-info. computer.read
POST /api/computer/{id}/roles Adds a role to a computer. Idempotent: an already assigned role returns 200. The roles Empirum Master Server and Computer Template are refused with 400. computer.write
DELETE /api/computer/{id}/roles/{roleId} Removes a role from a computer. Idempotent: an unassigned role returns 204. Removing the role Empirum Depot Server is refused with 409 for the default depot and in other cases described in the OpenAPI document. computer.write

Effective Assignments and Reverse Lookups

These endpoints show which objects a computer or group actually receives, and where a given object is assigned. Effective values are resolved through the computer's own group and its ancestor groups, using the same resolver as the Empirum Management Console, and include the group that provides the winning assignment.

Method Path Description Requires Role
GET /api/computer/{id}/agent-template Effective Agent Template of the computer. computer.read
GET /api/computer/{id}/language-packs Effective OS Language Packs (multi-assign, one winner per pack). computer.read
GET /api/computer/{id}/os-image-sku Effective OS image SKU. computer.read
GET /api/computer/{id}/pxe-bootimage Effective PXE boot image. computer.read
GET /api/computer/{id}/os-deployment-readiness Effective OS image SKU and PXE boot image in one call, including what is missing. ready=true means nothing needs to be assigned before activating the computer with pxe=true for an OS reinstall. computer.read
GET /api/group/{id}/os-image-sku OS image SKU currently assigned to the group (at most one). group.read
GET /api/group/{id}/pxe-bootimage PXE boot image currently assigned to the group (at most one). group.read
GET /api/packages/{id}/groups Every group with a direct assignment of this package. package.read
GET /api/agent-templates/{id}/groups Every group with a direct assignment of this Agent Template. package.read
GET /api/language-pack-imports/{id}/groups Every group with a direct assignment of this OS Language Pack. package.read
GET /api/operating-system-imports/{id}/skus/{skuId}/groups Every group with a direct assignment of this SKU. package.read
GET /api/pxe-bootimages/{id}/groups Every group with a direct assignment of this PXE boot image. package.read

Reverse lookups return direct assignments only. No inheritance resolution applies, and these object types are never assigned to computers directly.

 

Software Deployment and Group Management

Method Path Description Requires Role
POST /api/computer/{id}/software-uninstall Triggers the uninstallation of an installed, assigned package, with the same semantics as the Empirum Management Console. The distribution mode of the package's nearest assignment is set to Uninstall and the computer is activated. The assignment is kept. activation.execute
POST /api/group/package-replacement Replaces a package with another one, typically a newer version, in every group where it is directly assigned (the "Replace Software" action). Distribution options are copied by default. One transaction per group. group.write
PUT /api/group/{id}/distribution-options Sets the distribution options of a group, or with packageId of one package assignment. This is a full replace: omitted optional fields clear the stored values. Changes take effect at the next activation of the members. group.write
POST /api/group/search Searches deployment groups by name and description. The character * is the wildcard, with the same semantics as the computer hostname search. group.read
PATCH /api/group/{id} Updates the name and/or description of a group. Omitted fields keep their stored value, and an empty description clears it. group.write
GET /api/group/{id}/depot-servers Directly assigned depot server failover list of the group, ordered by priority. group.read
PUT /api/group/{id}/depot-servers Replaces the complete ordered depot server list of the group. The first entry is the primary depot server. group.write

Setting the distribution mode Uninstall on a group makes every member computer of the group and its subgroups uninstall the affected package at its next activation. The same applies to software-uninstall, which sets the flag on the whole assignment group.

 

Tags and Depot Topology

Tags connect packages to depot servers. Package tags require Empirum 26.2 or later.

Method Path Description Requires Role
GET /api/tags Paged list of all tags. package.read
POST /api/tags Creates a tag. package.write
GET /api/tags/{id} Returns one tag. package.read
PATCH /api/tags/{id} Renames and/or re-describes a tag. Read-only tags such as "Global" cannot be changed. package.write
DELETE /api/tags/{id} Deletes a tag and removes its package and depot assignments. Read-only tags cannot be deleted. package.write
GET /api/tags/packages Returns the packages assigned to a tag. Identify the tag by exactly one of tagId or tag. package.read
GET /api/packages/{id}/tags Returns the tags assigned to a package. package.read
PUT /api/packages/{id}/tags Replaces the tag assignment of a package. This is a full replace, not an incremental change. package.write
GET /api/depots/{clientId}/tags Returns the tags assigned to a depot. package.read
POST /api/depots/{clientId}/tags Assigns a tag to a depot. Assigning an already assigned tag returns 200 instead of creating a duplicate. package.write
DELETE /api/depots/{clientId}/tags/{tagId} Removes a tag from a depot. package.write
GET /api/system/depot-topology-setting Returns whether the Depot Topology / Tags feature is active. package.read
PUT /api/system/depot-topology-setting Switches the Depot Topology / Tags feature on or off. While inactive, the Management Console hides the Topology and Tags tabs and tag ids are no longer written into the package properties. package.write

Depot Servers and Synchronization

Method Path Description Requires Role
GET /api/system/depot-servers Lists all assignable depot servers (clients with the Empirum Depot Server or Master Server role). Every entry is a valid value for PUT /api/group/{id}/depot-servers. computer.read
GET /api/system/sync-jobs Lists depot sync jobs with last and next run and result, newest first. computer.read
POST /api/system/sync-jobs Triggers an out-of-schedule depot sync job. activation.execute
GET /api/system/sync-jobs/depots Lists all depot servers with the heartbeat of their sync component (online, offline, pending, unknown). computer.read

Package Import

Method Path Description Requires Role
POST /api/packages/import Imports a package from the PackageStore folder and generates its hash. The import runs as a background job. package.write
GET /api/packages/import/{trackingId} Returns the status of an import job: Pending, Running, Success, or Failed. package.read

Backend Queues and Tasks

Monitoring endpoints that make long-running Empirum operations visible to API consumers. All endpoints require the role computer.read.

Method Path Description
GET /api/queues Lists pending and running backend tasks from the backend plugin queues, newest first. This is the REST equivalent of the Back-end Task Queue dialog in the Management Console. Entries disappear once the job is completed, so an empty list means nothing is pending.
GET /api/queues/names Lists the queue names available in the installation, which are the valid values for the queue filter of GET /api/queues.
GET /api/tasks Lists external tasks, newest first. A task is created when a deployment operation is started (software install or uninstall, computer or software reinstall, OS install) and is closed once the client reported a result. Finished and failed tasks are purged after a retention period, 30 days by default.
GET /api/tasks/{trackingId} Returns one task including the breakdown per action.

Custom Field Configuration and Patch Products

Method Path Description Requires Role
GET /api/custom-field-configuration Returns all 30 custom field slots, active and inactive, with designation, active flag, and position in the Management Console. The list is not paged. computer.read
PATCH /api/custom-field-configuration/{slot} Renames and/or activates or deactivates one slot. This is a global setting. Deactivating a slot hides it but keeps the stored computer values. The designation is limited to 50 characters and must be unique across all slots (409 on conflict). computer.write
GET /api/patches/{patchId}/products Lists the product versions a patch is linked into, with the number of link items per product. pm.read
GET /admin/logout Signs out of the Permission Management web UI. None

Custom field values of a computer are written with PATCH /api/computer/{id} and the new custom field. Only active slots can be written. Activate and name a slot first with PATCH /api/custom-field-configuration/{slot}.

 

Changes to Existing Endpoints

  • Computer custom fields: PATCH /api/computer/{id} accepts the new optional field custom, a map of slot names (Custom01 to Custom30) to values. Only the slots that are sent change, and a null or empty value clears the slot. Values are limited to 50 characters, and only active slots can be written (otherwise the API returns 400). A later inventory scan may overwrite these values. Use the new endpoints under /api/custom-field-configuration to see which slots are active.
  • Distribution history: GET /api/computer/{id}/distribution-history and the distribution history search accept the new parameter type. The value software is the default, patch returns patch history, and all returns every archived entry including agent status events.
  • Issue thresholds: GET /api/computer/issues/overview accepts the new query parameters minFreePercent, minFreeGb, maxHealthPercent, minHoursStale, maxHoursStale, minHoursPending, and maxDaysPending. They override the thresholds of the low-disk, battery-wear, stale-agent, and stale-deployment checks. Omitting them reproduces the previous behavior.
  • Inherited assignments: The requests to assign an Agent Template, OS image SKU, or PXE boot image to a group accept the new field skipIfInherited (default false). The responses report alreadyEffective and inheritedFromGroupId, so clients can tell when an assignment already applies through a parent group.
  • Computer activation: The activation request accepts the new field wolNow.
  • Package search: The package search filter accepts tag and tagId.
  • Variable schedules: Variable values and the request to set a variable value support the new field schedule.
  • Group details: GET /api/group/{id} returns the new fields fullPath and parentName. They are empty in list results.
  • New response fields: inventoryId and isDomain on computers; isDomain, osLogin, and tempDirSizeMb in system info; driveTypeName and diskType on disk drives; dhcpIpAddress and dhcpSubnetMask on network adapters; caption on batteries; sizeBytes on patch catalog items; productId on patch items; linkItemsTotal, patchCount, and productId in the patch approval result.
  • Input validation: Several string filter parameters now document a maximum length of 255 characters.

Administration and Security

  • Principals and local principals have a new property protected. A protected principal can only be deleted with force=true.
  • The admin features response contains the new fields localAdminEnabled and oidcLoginProviders, which describe the available sign-in methods for the Permission Management web UI.
  • The token endpoint is rate limited and returns 429 Too Many Requests when the limit is exceeded.

Documentation

The OpenAPI document now contains descriptions for most parameters and response fields, for example the allowed range of skip and top. The new Tags, DepotTags, Queues, Tasks, CustomFieldConfiguration, and ComputerRoles groups appear as folders in Scalar, and as folders in Postman when the import setting Folder organization is set to Tags.

Upgrade Notes

Before updating, check whether your integration uses one of the removed endpoints listed under "Breaking Changes", or approves patches and adds patches to PM groups without a productId. These calls fail after the update.

 

Re-import the OpenAPI document (/openapi/v1.json) in Scalar or Postman to pick up the new endpoints. In Postman, re-apply the collection-level authorization and the post-response script as described in the Postman guide.

Related Articles