Release Notes REST API

Pre-Release Changes

+ More

Table of Contents

Empirum REST API v1 1.0.2 (RC) – Release Notes Breaking Changes Removed Endpoints Patch Operations Require a Product Scope Other Behavior Changes New Endpoints Computer Inventory 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.6.0 – Release Notes (from 0.5.2) New: Computer Variable Endpoints New: Group Variable Endpoints New: Variable Definitions Catalog Endpoints New Schemas Changed Removed / Deprecated Upgrade Notes

Empirum REST API v1 1.0.2 (RC) – Release Notes

This release summarizes all changes since v1 0.6.0. It adds 57 new endpoints covering computer inventory, effective assignment lookups, 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.

This release also contains breaking changes. Please review the section "Breaking Changes" before updating existing integrations.

Release Candidate This REST API 1.0.2 is defined as a release candidate and is fully integrated into Empirum. Endpoints, payloads, roles, and behavior may change before GA.

 

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 fields productId were 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 inventory from the last Empirum scan. All endpoints require the role computer.read.

Method Path Description
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, and more. List sections are not paged and are capped at 500 rows each. Installed software and services are not included.
GET /api/computer/{id}/inventory/bios BIOS manufacturer, versions, serial number, and UUID.
GET /api/computer/{id}/inventory/computer-system WMI ComputerSystem data such as manufacturer and model.
GET /api/computer/{id}/inventory/monitors Attached monitors with EDID name, serial number, size, and resolution.
GET /api/computer/{id}/inventory/printers Installed printers with name, port, driver, share, and resolution.
GET /api/computer/{id}/inventory/processors Processors with name, manufacturer, core and logical processor counts, and clock speeds.
GET /api/computer/{id}/inventory/video-controllers Video controllers with GPU name, RAM, and video mode.
GET /api/computer/{id}/inventory/batteries Battery status, capacity, and health. Moved from /api/computer/{id}/batteries.
GET /api/computer/{id}/inventory/disks Disk capacity and free space. Moved from /api/computer/{id}/disks.
GET /api/computer/{id}/inventory/network-adapters IP, MAC, DNS, and DHCP configuration. Moved from /api/computer/{id}/network-adapters.
GET /api/computer/{id}/inventory/installed-software Software detected during the last scan. Moved from /api/computer/{id}/installed-software.
GET /api/computer/{id}/inventory/services Windows services, optionally filtered by status or name. Moved from /api/computer/{id}/services.

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
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.
  • 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.
  • Computer update: The computer patch request accepts the new field custom for custom field values.
  • 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.
  • New response fields: inventoryId and isDomain on computers; isDomain, osLogin, and tempDirSizeMb in system info; driveTypeName on disk drives; 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, and CustomFieldConfiguration 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.

Empirum REST API v1 0.6.0 – Release Notes (from 0.5.2)

This release adds full support for Variables — reading, setting, and managing Empirum's computer and group variables (including collection-type variables and inheritance resolution) directly through the REST API, plus a new Variable Definitions catalog endpoint group for looking up variable metadata and where a variable is used. This is a purely additive release — no existing endpoints, request/response schemas, or roles were changed or removed.

Preview / pre-release. This REST API is an early preview and will later be fully integrated into Empirum. Endpoints, payloads, roles, and behavior may change without notice.

 

New: Computer Variable Endpoints

Read, set, and manage variable values directly on a computer, including collection-type variables (bundles of related values).

Method Path Description Requires Role
GET /api/computer/{id}/variables Lists this computer's directly-assigned variable value(s). computer.read
POST /api/computer/{id}/variables/search Resolves a single computer variable's value, with optional inheritance resolution. computer.read
PUT /api/computer/{id}/variables/{varId} Sets this computer's own (direct) value for a scalar (non-collection) variable. A null or omitted value deletes the override, falling back to inheritance/catalog default on later reads. computer.write
GET /api/computer/{id}/variables/{varId}/collection Lists this computer's direct entries (bundles) for a collection variable. computer.read
POST /api/computer/{id}/variables/{varId}/collection Adds one new entry (bundle) to a collection variable on this computer. computer.write
PATCH /api/computer/{id}/variables/{varId}/collection/{collectionId} Partially updates one existing variable collection entry. computer.write
DELETE /api/computer/{id}/variables/{varId}/collection/{collectionId} Deletes an entire variable collection entry (all its child values). computer.write

New: Group Variable Endpoints

The same read/set/manage capability as computer variables, applied to deployment groups.

Group variable resolution only considers ancestor group inheritance — unlike computer variables, a group has no "own computer value" tier.

 
Method Path Description Requires Role
GET /api/group/{id}/variables Lists this group's directly-assigned variable value(s). group.read
POST /api/group/{id}/variables/search Resolves a single group variable's value, with optional ancestor inheritance resolution. group.read
PUT /api/group/{id}/variables/{varId} Sets this group's own (direct) value for a scalar (non-collection) variable. A null or omitted value deletes the override, falling back to ancestor/catalog default on later reads. group.write
GET /api/group/{id}/variables/{varId}/collection Lists this group's direct entries (bundles) for a collection variable. No ancestor inheritance. group.read
POST /api/group/{id}/variables/{varId}/collection Adds one new entry (bundle) to a collection variable on this group. group.write
PATCH /api/group/{id}/variables/{varId}/collection/{collectionId} Partially updates one existing collection entry (bundle) on this group. group.write
DELETE /api/group/{id}/variables/{varId}/collection/{collectionId} Deletes an entire variable collection entry (all its child values). group.write

New: Variable Definitions Catalog Endpoints

Look up variable metadata (type, default value, parent/child relationships) and find every computer, group, or Variable Configuration that has an explicit value set for a given variable.

Method Path Description Requires Role
GET /api/variable-definitions Returns a paged list of all Variable Definitions. package.read
POST /api/variable-definitions/search Searches Variable Definitions by name (matches either the raw Designation or the dotted "{parent}.{child}" form). package.read
GET /api/variable-definitions/{varId} Returns a single Variable Definition by its VarID. package.read
GET /api/variable-definitions/{varId}/children Returns every child variable definition of this VarID. package.read
GET /api/variable-definitions/{varId}/computers Inverse search: returns every computer with an explicit direct value set for this VarID. package.read
GET /api/variable-definitions/{varId}/groups Inverse search: returns every group with an explicit direct value set for this VarID. package.read
GET /api/variable-definitions/{varId}/variable-configurations Inverse search: returns every Variable Configuration with an explicit entry for this VarID (the stored value only takes effect once the configuration is assigned to a group). package.read

New Schemas

The following data types were added to the OpenAPI document to support the endpoints above: VariableDefinition, VariableDefinitionChild, VariableDefinitionComputerAssignment, VariableDefinitionGroupAssignment, VariableDefinitionConfigurationAssignment, VariableValue, VariableCollectionEntry, SetVariableValueRequest, VariableCollectionEntryRequest, VariableCollectionEntryPatchRequest, VariableDefinitionSearchFilter, VariableValueSearchFilter, and their corresponding paged-result wrappers.

Changed

None. No existing endpoint, request/response schema, or role was modified in this release.

Removed / Deprecated

None.

Upgrade Notes

This is a purely additive release — existing integrations built against v1 0.5.2 continue to work unchanged. Re-import the OpenAPI document (/openapi/v1.json) in Scalar or Postman to pick up the new Variables endpoints.

 

Related Articles