Empirum Rest-API Reference

+ More

Table of Contents

Overview Common Request Details Operations per Area Authentication POST /api/auth/token Administration GET /api/admin/principals POST /api/admin/principals GET /api/admin/principals/{id} PUT /api/admin/principals/{id} DELETE /api/admin/principals/{id} GET /api/admin/local-principals POST /api/admin/local-principals GET /api/admin/local-principals/{id} PUT /api/admin/local-principals/{id} DELETE /api/admin/local-principals/{id} PATCH /api/admin/local-principals/{id}/revoke GET /api/admin/roles GET /api/admin/features Computers GET /api/computer POST /api/computer GET /api/computer/{id} PATCH /api/computer/{id} DELETE /api/computer/{id} POST /api/computer/search GET /api/computer/patch-status POST /api/computer/software-search POST /api/computer/distribution-history/search GET /api/computer/issues/low-disk GET /api/computer/issues/battery-wear GET /api/computer/issues/bitlocker-off GET /api/computer/issues/pending-reboot GET /api/computer/issues/stale-agent GET /api/computer/issues/stale-inventory GET /api/computer/issues/failed-deployment GET /api/computer/issues/shared-package-failure GET /api/computer/issues/shared-package-failure/devices GET /api/computer/issues/missing-patch GET /api/computer/issues/stale-deployment GET /api/computer/issues/agent-suspended GET /api/computer/issues/overview GET /api/computer/{id}/issues GET /api/computer/{id}/security-posture GET /api/computer/{id}/system-info GET /api/computer/{id}/variables POST /api/computer/{id}/variables/search PUT /api/computer/{id}/variables/{varId} GET /api/computer/{id}/variables/{varId}/collection POST /api/computer/{id}/variables/{varId}/collection PATCH /api/computer/{id}/variables/{varId}/collection/{collectionId} DELETE /api/computer/{id}/variables/{varId}/collection/{collectionId} GET /api/computer/{id}/reboot-status GET /api/computer/{id}/groups GET /api/computer/{id}/packages/{packageId}/groups GET /api/computer/{id}/agent-template GET /api/computer/{id}/os-image-sku GET /api/computer/{id}/pxe-bootimage GET /api/computer/{id}/language-packs GET /api/computer/{id}/uem-agent GET /api/computer/{id}/health GET /api/computer/{id}/software-deployment GET /api/computer/{id}/patch-status POST /api/computer/{id}/patches-search GET /api/computer/{id}/setup-error-log GET /api/computer/{id}/distribution-history GET /api/computer/{id}/inventory/installed-software GET /api/computer/{id}/inventory/services GET /api/computer/{id}/inventory/disks GET /api/computer/{id}/inventory/batteries GET /api/computer/{id}/inventory/network-adapters GET /api/computer/{id}/inventory/printers GET /api/computer/{id}/inventory/bios GET /api/computer/{id}/inventory/computer-system GET /api/computer/{id}/inventory/video-controllers GET /api/computer/{id}/inventory/monitors GET /api/computer/{id}/inventory/processors GET /api/computer/{id}/inventory POST /api/computer/{id}/software-reinstall GET /api/computer/{id}/software-reinstall DELETE /api/computer/{id}/software-reinstall POST /api/computer/{id}/software-uninstall GET /api/computer/{id}/pm-groups POST /api/computer/{id}/rescan POST /api/computer/{id}/reboot POST /api/computer/{id}/activation DELETE /api/computer/{id}/activation Deployment Groups GET /api/group POST /api/group GET /api/group/{id} DELETE /api/group/{id} PATCH /api/group/{id} GET /api/group/{id}/all-assignments GET /api/group/{id}/computers POST /api/group/{id}/computers DELETE /api/group/{id}/computers GET /api/group/{id}/packages POST /api/group/{id}/packages GET /api/group/{id}/distribution-options PUT /api/group/{id}/distribution-options GET /api/group/{id}/depot-servers PUT /api/group/{id}/depot-servers DELETE /api/group/{id}/packages/{packageId} POST /api/group/{id}/pxe-bootimage GET /api/group/{id}/pxe-bootimage DELETE /api/group/{id}/pxe-bootimage/{pxeId} POST /api/group/{id}/os-image-sku GET /api/group/{id}/os-image-sku DELETE /api/group/{id}/os-image-sku/{skuId} GET /api/group/{id}/agent-template POST /api/group/{id}/agent-template DELETE /api/group/{id}/agent-template/{packageId} GET /api/group/{id}/language-pack-imports POST /api/group/{id}/language-pack-imports DELETE /api/group/{id}/language-pack-imports/{packageId} GET /api/group/{id}/variable-configurations POST /api/group/{id}/variable-configurations DELETE /api/group/{id}/variable-configurations/{configId} GET /api/group/{id}/variables POST /api/group/{id}/variables/search PUT /api/group/{id}/variables/{varId} GET /api/group/{id}/variables/{varId}/collection POST /api/group/{id}/variables/{varId}/collection PATCH /api/group/{id}/variables/{varId}/collection/{collectionId} DELETE /api/group/{id}/variables/{varId}/collection/{collectionId} GET /api/group/{id}/software-classes POST /api/group/{id}/software-classes DELETE /api/group/{id}/software-classes/{classId} POST /api/group/{id}/activation DELETE /api/group/{id}/activation Software Packages GET /api/packages GET /api/packages/{id} GET /api/packages/{id}/status PUT /api/packages/{id}/operational POST /api/packages/hash-generation POST /api/packages/import GET /api/packages/import/{trackingId} POST /api/packages/search Patches POST /api/patches/search GET /api/patches/{patchId} GET /api/patches/products/{productId} GET /api/patches/{patchId}/products POST /api/patches/{patchId}/approval DELETE /api/patches/{patchId}/approval POST /api/patches/products/{productId}/approval Patch Management Groups GET /api/pmgroup POST /api/pmgroup GET /api/pmgroup/{id} GET /api/pmgroup/{id}/products POST /api/pmgroup/{id}/products GET /api/pmgroup/{id}/patches POST /api/pmgroup/{id}/patches GET /api/pmgroup/{id}/assignments POST /api/pmgroup/{id}/assignments DELETE /api/pmgroup/{id}/assignments DELETE /api/pmgroup/{id}/patches/{patchId} DELETE /api/pmgroup/{id}/products/{productId} POST /api/pmgroup/{id}/emergency-patching DELETE /api/pmgroup/{id}/emergency-patching Operating System Imports GET /api/operating-system-imports GET /api/operating-system-imports/{id} GET /api/operating-system-imports/{id}/skus/{skuId}/groups POST /api/operating-system-imports/search PXE Boot Images GET /api/pxe-bootimages GET /api/pxe-bootimages/{id} GET /api/pxe-bootimages/{id}/groups POST /api/pxe-bootimages/search Language Pack Imports GET /api/language-pack-imports GET /api/language-pack-imports/{id} GET /api/language-pack-imports/{id}/groups POST /api/language-pack-imports/search Agent Templates GET /api/agent-templates GET /api/agent-templates/{id} GET /api/agent-templates/{id}/groups POST /api/agent-templates/search Software Classes GET /api/softwareclasses GET /api/softwareclasses/{id} POST /api/softwareclasses/search Variable Definitions GET /api/variable-definitions GET /api/variable-definitions/{varId} GET /api/variable-definitions/{varId}/computers GET /api/variable-definitions/{varId}/groups GET /api/variable-definitions/{varId}/variable-configurations GET /api/variable-definitions/{varId}/children POST /api/variable-definitions/search Variable Configurations GET /api/variable-configurations GET /api/variable-configurations/{id} POST /api/variable-configurations/search System GET /api/system GET /api/system/sync-jobs POST /api/system/sync-jobs GET /api/system/sync-jobs/depots GET /api/system/depot-servers Tasks GET /api/tasks GET /api/tasks/{trackingId} Queues GET /api/queues GET /api/queues/names Service Endpoints GET /health POST /admin/logout

Overview

This article is the reference for all 193 operations of the Matrix42 Empirum REST API (OpenAPI specification Matrix42.Empirum.RestApi | v1, version 1.0.0). For each operation it lists the HTTP method and path, the description, the required role, parameters, request body and responses.

For installation, authentication, principal management, conventions and PowerShell examples, see the article Empirum REST API: Integration and Automation Guide.

Common Request Details

Item	Details
Base URL	`https://empirum-api.contoso.local:5443` (host and port depend on your installation)
Authentication	`Authorization: Bearer <access token>` for all operations except `/health` and `/api/auth/token`
API version	Optional header `api-version` on every operation. Current and default value: `1`. The header is not repeated in the parameter tables below.
Content type	`application/json` for request and response bodies unless stated otherwise
Paging	List and search operations accept `skip` and `top` and return `items`, `skip`, `top`, `totalCount` and `hasMore`
Timestamps	ISO 8601, UTC
Errors	`400` invalid request, `401` not authenticated, `403` missing role, `404` not found, `409` conflict with a machine-readable `code`

Operations per Area

Area	Operations
Authentication	1
Administration	13
Computers	67
Deployment Groups	43
Software Packages	8
Patches	7
Patch Management Groups	14
Operating System Imports	4
PXE Boot Images	4
Language Pack Imports	4
Agent Templates	4
Software Classes	3
Variable Definitions	7
Variable Configurations	3
System	5
Tasks	2
Queues	2
Service Endpoints	2

Authentication

Issues access tokens for API principals.

Method	Path	Summary
POST	`/api/auth/token`	Issues a short-lived Bearer JWT.

POST /api/auth/token

Issues a short-lived Bearer JWT.

Required role: none (no authentication required)

Request body (required, application/x-www-form-urlencoded)

Field	Type	Required	Description
`grant_type`	string	No	OAuth 2.0 grant type (`client_credentials`).
`client_id`	string	No	Client ID of the local principal.
`client_secret`	string	No	Client secret of the local principal.

Responses

Status	Description	Schema
`200`	OK	Rfc6749TokenResponse

Response fields (Rfc6749TokenResponse):

Field	Type	Required	Description
`access_token`	string	Yes	Bearer token for the `Authorization` header.
`token_type`	string	Yes	Token type (`Bearer`).
`expires_in`	integer (int32)	Yes	Token lifetime in seconds.

Administration

Manages local and Identity Provider principals, roles and admin features. All operations require the role admin.manage.

Method	Path	Summary
GET	`/api/admin/principals`	Returns all Identity Provider principals (Client and User) with their roles.
POST	`/api/admin/principals`	Creates or updates a principal identified by (SubjectType, SubjectId, Issuer).
GET	`/api/admin/principals/{id}`	Returns a single principal by its database id.
PUT	`/api/admin/principals/{id}`	Updates DisplayName, Issuer and Roles of an existing principal.
DELETE	`/api/admin/principals/{id}`	Deletes a principal and its role assignments.
GET	`/api/admin/local-principals`	Returns all local principals (client credentials) with their roles.
POST	`/api/admin/local-principals`	Creates a new local principal.
GET	`/api/admin/local-principals/{id}`	Returns a single local principal by its database id.
PUT	`/api/admin/local-principals/{id}`	Updates Description, ExpiresAtUtc and Roles of a local principal.
DELETE	`/api/admin/local-principals/{id}`	Permanently deletes a local principal and its role assignments.
PATCH	`/api/admin/local-principals/{id}/revoke`	Revokes or restores a local principal.
GET	`/api/admin/roles`	Returns all roles that can be assigned to principals, with descriptions.
GET	`/api/admin/features`	Returns which optional features are enabled for the admin UI.

GET /api/admin/principals

Returns all Identity Provider principals (Client and User) with their roles.

Required role: admin.manage

Responses

Status	Description	Schema
`200`	OK	array of PrincipalDto

Response fields (PrincipalDto):

Field	Type	Required	Description
`id`	integer (int32)	Yes	ID of the principal.
`subjectType`	string	Yes	Subject type (client or user).
`subjectId`	string	Yes	Subject ID in the identity provider.
`displayName`	string, nullable	Yes	Display name.
`issuer`	string, nullable	Yes	Token issuer of the identity provider.
`roles`	array of string	Yes	Assigned roles.

POST /api/admin/principals

Creates or updates a principal identified by (SubjectType, SubjectId, Issuer).

Required role: admin.manage

Request body (required, application/json, schema UpsertPrincipalRequest)

Field	Type	Required	Description
`isUser`	boolean	Yes	`true` if the subject is a user.
`subjectId`	string	Yes	Subject ID in the identity provider.
`displayName`	string, nullable	Yes	Display name.
`issuer`	string, nullable	Yes	Token issuer of the identity provider.
`roles`	array of string	Yes	Assigned roles.

Example request body (placeholder values):

{
    "isUser": false,
    "subjectId": "string",
    "displayName": "string",
    "issuer": "string",
    "roles": [
        "string"
    ]
}

Responses

Status	Description	Schema
`200`	OK	PrincipalDto

Response fields (PrincipalDto):

Field	Type	Required	Description
`id`	integer (int32)	Yes
`subjectType`	string	Yes	Subject type (client or user).
`subjectId`	string	Yes	Subject ID in the identity provider.
`displayName`	string, nullable	Yes	Display name.
`issuer`	string, nullable	Yes	Token issuer of the identity provider.
`roles`	array of string	Yes	Assigned roles.

GET /api/admin/principals/{id}

Returns a single principal by its database id.

Required role: admin.manage

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Principal ID.

Responses

Status	Description	Schema
`200`	OK	PrincipalDto

Response fields (PrincipalDto):

Field	Type	Required	Description
`id`	integer (int32)	Yes
`subjectType`	string	Yes	Subject type (client or user).
`subjectId`	string	Yes	Subject ID in the identity provider.
`displayName`	string, nullable	Yes	Display name.
`issuer`	string, nullable	Yes	Token issuer of the identity provider.
`roles`	array of string	Yes	Assigned roles.

PUT /api/admin/principals/{id}

Updates DisplayName, Issuer and Roles of an existing principal.

Required role: admin.manage

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Principal ID.

Request body (required, application/json, schema UpdatePrincipalRequest)

Field	Type	Required	Description
`displayName`	string, nullable	Yes	Display name.
`issuer`	string, nullable	Yes	Token issuer of the identity provider.
`roles`	array of string	Yes	Assigned roles.

Example request body (placeholder values):

{
    "displayName": "string",
    "issuer": "string",
    "roles": [
        "string"
    ]
}

Responses

Status	Description	Schema
`200`	OK	PrincipalDto

Response fields (PrincipalDto):

Field	Type	Required	Description
`id`	integer (int32)	Yes
`subjectType`	string	Yes	Subject type (client or user).
`subjectId`	string	Yes	Subject ID in the identity provider.
`displayName`	string, nullable	Yes	Display name.
`issuer`	string, nullable	Yes	Token issuer of the identity provider.
`roles`	array of string	Yes	Assigned roles.

DELETE /api/admin/principals/{id}

Deletes a principal and its role assignments.

Required role: admin.manage

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Principal ID.

Responses

Status	Description	Schema
`200`	OK	–

GET /api/admin/local-principals

Returns all local principals (client credentials) with their roles.

Required role: admin.manage

Responses

Status	Description	Schema
`200`	OK	array of LocalPrincipalDto

Response fields (LocalPrincipalDto):

Field	Type	Required	Description
`id`	integer (int32)	Yes	ID of the principal.
`clientId`	string	Yes	Computer ID (Empirum `client_id`).
`description`	string, nullable	Yes	Description of the principal.
`roles`	array of string	Yes	Assigned roles.
`isRevoked`	boolean	Yes	`true` if the principal is revoked.
`expiresAtUtc`	string (date-time), nullable	Yes	Expiry date (UTC).
`createdAtUtc`	string (date-time)	Yes	Creation time (UTC).

POST /api/admin/local-principals

Creates a new local principal.

Required role: admin.manage

Request body (required, application/json, schema CreateLocalPrincipalRequest)

Field	Type	Required	Description
`description`	string, nullable	Yes	Description of the principal.
`roles`	array of string	Yes	Assigned roles.
`expiresAtUtc`	string (date-time), nullable	Yes	Expiry date (UTC).

Example request body (placeholder values):

{
    "description": "string",
    "roles": [
        "string"
    ],
    "expiresAtUtc": "2026-01-01T00:00:00Z"
}

Responses

Status	Description	Schema
`200`	OK	CreateLocalPrincipalResponse

Response fields (CreateLocalPrincipalResponse):

Field	Type	Required	Description
`id`	integer (int32)	Yes
`clientId`	string	Yes	Computer ID (Empirum `client_id`).
`description`	string, nullable	Yes
`roles`	array of string	Yes	Assigned roles.
`isRevoked`	boolean	Yes	`true` if the principal is revoked.
`expiresAtUtc`	string (date-time), nullable	Yes	Expiry date (UTC).
`createdAtUtc`	string (date-time)	Yes	Creation time (UTC).
`plaintextKey`	string	Yes	Client secret. Shown only once; store it securely.

GET /api/admin/local-principals/{id}

Returns a single local principal by its database id.

Required role: admin.manage

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Local principal ID.

Responses

Status	Description	Schema
`200`	OK	LocalPrincipalDto

Response fields (LocalPrincipalDto):

Field	Type	Required	Description
`id`	integer (int32)	Yes
`clientId`	string	Yes	Computer ID (Empirum `client_id`).
`description`	string, nullable	Yes
`roles`	array of string	Yes	Assigned roles.
`isRevoked`	boolean	Yes	`true` if the principal is revoked.
`expiresAtUtc`	string (date-time), nullable	Yes	Expiry date (UTC).
`createdAtUtc`	string (date-time)	Yes	Creation time (UTC).

PUT /api/admin/local-principals/{id}

Updates Description, ExpiresAtUtc and Roles of a local principal.

Required role: admin.manage

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Local principal ID.

Request body (required, application/json, schema UpdateLocalPrincipalRequest)

Field	Type	Required	Description
`description`	string, nullable	Yes	Description of the principal.
`roles`	array of string	Yes	Assigned roles.
`expiresAtUtc`	string (date-time), nullable	Yes	Expiry date (UTC).

Example request body (placeholder values):

{
    "description": "string",
    "roles": [
        "string"
    ],
    "expiresAtUtc": "2026-01-01T00:00:00Z"
}

Responses

Status	Description	Schema
`200`	OK	LocalPrincipalDto

Response fields (LocalPrincipalDto):

Field	Type	Required	Description
`id`	integer (int32)	Yes
`clientId`	string	Yes	Computer ID (Empirum `client_id`).
`description`	string, nullable	Yes
`roles`	array of string	Yes	Assigned roles.
`isRevoked`	boolean	Yes	`true` if the principal is revoked.
`expiresAtUtc`	string (date-time), nullable	Yes	Expiry date (UTC).
`createdAtUtc`	string (date-time)	Yes	Creation time (UTC).

DELETE /api/admin/local-principals/{id}

Permanently deletes a local principal and its role assignments.

Required role: admin.manage

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Local principal ID.

Responses

Status	Description	Schema
`200`	OK	–

PATCH /api/admin/local-principals/{id}/revoke

Revokes or restores a local principal.

Required role: admin.manage

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Local principal ID.

Request body (required, application/json, schema SetRevokedRequest)

Field	Type	Required	Description
`isRevoked`	boolean	Yes	`true` if the principal is revoked.

Example request body (placeholder values):

{
    "isRevoked": false
}

Responses

Status	Description	Schema
`200`	OK	LocalPrincipalDto

Response fields (LocalPrincipalDto):

Field	Type	Required	Description
`id`	integer (int32)	Yes
`clientId`	string	Yes	Computer ID (Empirum `client_id`).
`description`	string, nullable	Yes
`roles`	array of string	Yes	Assigned roles.
`isRevoked`	boolean	Yes	`true` if the principal is revoked.
`expiresAtUtc`	string (date-time), nullable	Yes	Expiry date (UTC).
`createdAtUtc`	string (date-time)	Yes	Creation time (UTC).

GET /api/admin/roles

Returns all roles that can be assigned to principals, with descriptions.

Required role: admin.manage

Responses

Status	Description	Schema
`200`	OK	array of RoleDto

Response fields (RoleDto):

Field	Type	Required	Description
`role`	string	Yes	Role.
`description`	string	Yes	Description of the role.

GET /api/admin/features

Returns which optional features are enabled for the admin UI.

Required role: admin.manage

Responses

Status	Description	Schema
`200`	OK	AdminFeatures

Response fields (AdminFeatures):

Field	Type	Required	Description
`idpEnabled`	boolean	Yes	`true` if Identity Provider principals are enabled.

Computers

Computer objects, hardware and software inventory, health and security posture, fleet issue sweeps, software deployment, reinstall and uninstall, activation, rescan, reboot, variables and effective OS deployment settings.

Method	Path	Summary
GET	`/api/computer`	Returns a paged list of all managed Empirum endpoints.
POST	`/api/computer`	Creates a computer in Empirum.
GET	`/api/computer/{id}`	Returns a single managed endpoint by its Empirum client_id.
PATCH	`/api/computer/{id}`	Partially updates a computer — only the provided fields change.
DELETE	`/api/computer/{id}`	Deletes a computer.
POST	`/api/computer/search`	Searches managed endpoints using one or more filter criteria.
GET	`/api/computer/patch-status`	Returns the fleet-wide status of a single patch across all computers with scan data for it.
POST	`/api/computer/software-search`	Returns all computers that have every specified product installed (AND across the list).
POST	`/api/computer/distribution-history/search`	Searches distribution events across all computers (ArchiveDistJobs).
GET	`/api/computer/issues/low-disk`	Returns all endpoints with at least one fixed drive below the free-space threshold, with drive details.
GET	`/api/computer/issues/battery-wear`	Returns all endpoints with at least one battery worn below the health threshold (full-charge capacity as a percentage of design capacity), with battery details.
GET	`/api/computer/issues/bitlocker-off`	Returns Windows endpoints whose fixed disks are not BitLocker-encrypted per inventory.
GET	`/api/computer/issues/pending-reboot`	Returns all endpoints with a pending reboot.
GET	`/api/computer/issues/stale-agent`	Returns all endpoints whose UEM agent has stopped reporting on schedule.
GET	`/api/computer/issues/stale-inventory`	Returns all endpoints whose last inventory scan is at least minDaysStale days old.
GET	`/api/computer/issues/failed-deployment`	Returns all endpoints with at least one software deployment that has failed, with the failed package list.
GET	`/api/computer/issues/shared-package-failure`	Returns packages whose installation fails on multiple devices, grouped by package.
GET	`/api/computer/issues/shared-package-failure/devices`	Drill-down for the shared-package-failure issue: all devices (paged) where the given package currently fails.
GET	`/api/computer/issues/missing-patch`	Returns all endpoints currently missing patches.
GET	`/api/computer/issues/stale-deployment`	Returns endpoints where a software installation was assigned but never started, even though the device is online.
GET	`/api/computer/issues/agent-suspended`	Returns all endpoints whose UEM agent is currently paused.
GET	`/api/computer/issues/overview`	Returns all endpoints that have at least one active issue, with each matched issue inline.
GET	`/api/computer/{id}/issues`	Full issue picture for one endpoint: every fleet issue evaluated against this device, with detail inline.
GET	`/api/computer/{id}/security-posture`	Returns antivirus, firewall, Secure Boot, and script-policy state for an endpoint.
GET	`/api/computer/{id}/system-info`	Returns last-inventory system info and customer-defined management properties for an endpoint.
GET	`/api/computer/{id}/variables`	Lists this computer's directly-assigned variable value(s).
POST	`/api/computer/{id}/variables/search`	Resolves a single computer variable's value, with optional inheritance resolution.
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.
GET	`/api/computer/{id}/variables/{varId}/collection`	Lists this computer's direct entries (bundles) for a collection variable.
POST	`/api/computer/{id}/variables/{varId}/collection`	Adds one new entry (bundle) to a collection variable on this computer.
PATCH	`/api/computer/{id}/variables/{varId}/collection/{collectionId}`	Partially updates one existing variable collection entry.
DELETE	`/api/computer/{id}/variables/{varId}/collection/{collectionId}`	Deletes an entire variable collection entry (all its child values).
GET	`/api/computer/{id}/reboot-status`	Returns whether a reboot is pending and what triggered it (e.g. WindowsUpdate, SoftwareInstall).
GET	`/api/computer/{id}/groups`	Returns the Empirum deployment groups the endpoint belongs to, optionally filtered by a group-name substring.
GET	`/api/computer/{id}/packages/{packageId}/groups`	Returns the configuration/assignment groups through which a given package is assigned to this computer.
GET	`/api/computer/{id}/agent-template`	Returns the computer's effective Agent Template — resolved via its own group and ancestor groups by EMC's own resolver (assignment only ever happens at the group level), with the winning group as provenance.
GET	`/api/computer/{id}/os-image-sku`	Returns the computer's effective OS image SKU — resolved via its own group and ancestor groups by EMC's own resolver, with the winning group as provenance.
GET	`/api/computer/{id}/pxe-bootimage`	Returns the computer's effective PXE boot image — resolved via its own group and ancestor groups by EMC's own resolver, with the winning group as provenance.
GET	`/api/computer/{id}/language-packs`	Returns the computer's effective OS Language Packs (multi-assign — one winner per pack) — resolved via its own group and ancestor groups by EMC's own resolver, each with the winning group as provenance.
GET	`/api/computer/{id}/uem-agent`	Returns UEM agent information grouped into three objects: `desiredState`, `inventory`, and `dailyStatus`.
GET	`/api/computer/{id}/health`	Returns the agent reporting status and overall health classification for an endpoint.
GET	`/api/computer/{id}/software-deployment`	Returns the assigned Empirum packages for software deployment.
GET	`/api/computer/{id}/patch-status`	Returns missing-patch counts and the date of the last patch scan.
POST	`/api/computer/{id}/patches-search`	Searches the detailed patch list for a computer with optional filtering and pagination.
GET	`/api/computer/{id}/setup-error-log`	Returns cumulative setup.inf error output from failed software deployments.
GET	`/api/computer/{id}/distribution-history`	Returns the most recent software distribution events for the device from the Empirum agent status-message log (ArchiveDistJobs).
GET	`/api/computer/{id}/inventory/installed-software`	Returns the software inventory detected during the last Empirum scan.
GET	`/api/computer/{id}/inventory/services`	Returns Windows services on an endpoint, optionally filtered by status or name.
GET	`/api/computer/{id}/inventory/disks`	Returns disk drive capacity and free-space data from the last inventory scan.
GET	`/api/computer/{id}/inventory/batteries`	Returns battery details (status, capacity, health/wear) from the last inventory scan.
GET	`/api/computer/{id}/inventory/network-adapters`	Returns network adapter configuration (IP, MAC, DNS, DHCP) from the last inventory scan.
GET	`/api/computer/{id}/inventory/printers`	Returns installed printers (WMI-based: name, port, driver, share, resolution) from the last inventory scan.
GET	`/api/computer/{id}/inventory/bios`	Returns BIOS details (manufacturer, versions, serial number, UUID) from the last inventory scan.
GET	`/api/computer/{id}/inventory/computer-system`	Returns WMI ComputerSystem data (manufacturer, model) from the last inventory scan.
GET	`/api/computer/{id}/inventory/video-controllers`	Returns video controllers (GPU name, RAM, video mode) from the last inventory scan.
GET	`/api/computer/{id}/inventory/monitors`	Returns attached monitors (EDID name, serial, size, resolution) from the last inventory scan.
GET	`/api/computer/{id}/inventory/processors`	Returns processors (name, manufacturer, core/logical-processor counts, clock speeds) from the last inventory scan.
GET	`/api/computer/{id}/inventory`	Returns the aggregated inventory picture of one computer in a single call: core record, system info, BIOS, WMI ComputerSystem, disks, network adapters, batteries, printers, video controllers, monitors, and processors.
POST	`/api/computer/{id}/software-reinstall`	Triggers an enforced reinstall of a package via its existing tree assignment.
GET	`/api/computer/{id}/software-reinstall`	Lists the currently existing reinstall groups for this computer.
DELETE	`/api/computer/{id}/software-reinstall`	Cancels the given pending reinstall for this computer by removing the associated reinstall group.
POST	`/api/computer/{id}/software-uninstall`	Triggers the uninstallation of an installed, assigned package on this computer.
GET	`/api/computer/{id}/pm-groups`	Returns the Patch Management groups that apply to this computer through its group memberships.
POST	`/api/computer/{id}/rescan`	Forces a fresh inventory or patch scan on this computer.
POST	`/api/computer/{id}/reboot`	Flags this computer to reboot at the UEM agent's next polling interval (Empirum SRL — Silent Reboot Logic).
POST	`/api/computer/{id}/activation`	Activates this computer for software deployment or PXE boot.
DELETE	`/api/computer/{id}/activation`	Deactivates this computer.

GET /api/computer

Returns a paged list of all managed Empirum endpoints.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).
`lastSeenAfter`	query	string (date-time)	No	Only computers seen after this UTC timestamp.
`modifiedAfter`	query	string (date-time)	No	Only objects modified after this UTC timestamp (delta synchronization).
`inventoryAfter`	query	string (date-time)	No	Only computers inventoried after this UTC timestamp.
`inventoryBefore`	query	string (date-time)	No	Only computers inventoried before this UTC timestamp.
`neverSeen`	query	boolean	No	Only computers that never contacted the server.
`neverInventoried`	query	boolean	No	Only computers without an inventory.

Responses

Status	Description	Schema
`200`	OK	PagedResultOfComputer

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`id`	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`hostname`	string	Yes	Hostname of the computer.
`domain`	string, nullable	Yes	Domain name.
`macAddress`	string, nullable	Yes	MAC address.
`uuid`	string (uuid)	Yes	Hardware UUID of the computer.
`lastSeenUtc`	string (date-time), nullable	Yes	Last agent contact (UTC).
`serialNumber`	string, nullable	No	Serial number.
`lastModified`	string (date-time), nullable	No	Time of the last modification (UTC).
`inventoryDate`	string (date-time), nullable	No	Date of the last inventory (UTC).
`inventoryId`	string, nullable	No	Inventory ID.
`ou`	string, nullable	No	Organizational unit (OU).
`pxeSupport`	boolean	No	`true` if the computer supports PXE boot.
`isPxeActive`	boolean	No	`true` if PXE boot is activated.

POST /api/computer

Creates a computer in Empirum.

Either macAddress or a non-empty uuid is required; a computer without ipAddress is DHCP. The new computer belongs to no group — assign it afterwards with POST /api/group/{id}/computers. Returns 409 when the name+domain or the MAC already belongs to another computer.

Required role: computer.write

Request body (required, application/json, schema ComputerWriteRequest)

Body for POST /api/computer (create); also the internal merge base/result of PATCH /api/computer/{id}. Mirrors the EmpirumAPI computer property set (TFS EmpirumAPI\EmpirumAPI\Computer.cs GetProperties): Domain and IsDomain are mandatory, and either MacAddress or Uuid must be supplied. Ou sets only this computer's own CompVariables override for the ORGANIZATIONAL_UNIT designation (EMC's "OU for computer accounts" field) — a forced group value still takes precedence when reading the effective OU (see ComputerDbRepository.EffectiveOuSql); this is unaffected by writes here. An empty string on PATCH deletes the override (falls back to any inherited group value or catalog default), not just blanks it — see ComputerPatchRequest. DHCP is derived, not a field: a computer with no IpAddress is DHCP. Custom01–30 are deliberately not writable (read-only on the management block for now). Group membership is never set here — creating a computer and putting it into a group are separate operations; use POST /api/group/{id}/computers afterwards, which applies the full assignment rules (config-group exclusivity, special-group refusal). SerialNumber (optional) seeds/overwrites WMIBios.SerialNumber for the client — EMC itself never lets an admin set this manually (WMIBios is otherwise populated only by inventory/location-sync), so this is a REST-only convenience for pre-provisioning before the first inventory scan; a later scan overwrites it as usual. Writable on PATCH too (an empty string deletes the WMIBios row rather than blanking it — see ComputerPatchRequest), same delete-not-blank convention as Ou. Unknown JSON properties are rejected (400 naming the property) — a typo'd field on a write must not silently no-op. Description is accepted for backward compatibility with clients built against the pre-597219 contract but is a pure no-op: never stored, never validated beyond deserialization. The controller logs a warning when a caller still sends it (see LogWarningDescriptionFieldIgnored).

Field	Type	Required	Description
`name`	string	Yes	Name of the computer.
`domain`	string	Yes	Domain name.
`isDomain`	boolean	Yes	`true` if the computer is domain-joined.
`inventoryId`	string, nullable	No	Inventory ID.
`macAddress`	string, nullable	No	MAC address.
`uuid`	string (uuid), nullable	No	Hardware UUID of the computer.
`pxeSupport`	boolean	No	`true` if the computer supports PXE boot.
`ipAddress`	string, nullable	No	IP address.
`subnetMask`	string, nullable	No	Subnet mask.
`standardGateway`	string, nullable	No	Default gateway.
`ou`	string, nullable	No	Organizational unit (OU).
`serialNumber`	string, nullable	No	Serial number.
`description`	string, nullable	No	Description of the computer.

Example request body (placeholder values):

{
    "name": "string",
    "domain": "string",
    "isDomain": false,
    "inventoryId": "string",
    "macAddress": "string",
    "uuid": "00000000-0000-0000-0000-000000000000",
    "pxeSupport": false,
    "ipAddress": "string",
    "subnetMask": "string",
    "standardGateway": "string",
    "ou": "string",
    "serialNumber": "string",
    "description": "string"
}

Responses

Status	Description	Schema
`200`	OK	Not described in the specification
`409`	Conflict	ComputerWriteConflict

GET /api/computer/{id}

Returns a single managed endpoint by its Empirum client_id.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).

Responses

Status	Description	Schema
`200`	OK	Computer

Response fields (Computer):

Field	Type	Required	Description
`id`	integer (int32)	Yes
`hostname`	string	Yes	Hostname of the computer.
`domain`	string, nullable	Yes	Domain name.
`macAddress`	string, nullable	Yes	MAC address.
`uuid`	string (uuid)	Yes	Hardware UUID of the computer.
`lastSeenUtc`	string (date-time), nullable	Yes	Last agent contact (UTC).
`serialNumber`	string, nullable	No	Serial number.
`lastModified`	string (date-time), nullable	No	Time of the last modification (UTC).
`inventoryDate`	string (date-time), nullable	No	Date of the last inventory (UTC).
`inventoryId`	string, nullable	No	Inventory ID.
`ou`	string, nullable	No	Organizational unit (OU).
`pxeSupport`	boolean	No	`true` if the computer supports PXE boot.
`isPxeActive`	boolean	No	`true` if PXE boot is activated.

PATCH /api/computer/{id}

Partially updates a computer; only the provided fields change.

The patch is merged onto the current writable field set: an omitted/null field keeps the stored value, an empty string clears it, the empty GUID clears uuid. The merged result must still satisfy the write rules (MAC-or-UUID, static-IP block, …). Returns 409 when the new name+domain or MAC belongs to another computer.

Required role: computer.write

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).

Request body (required, application/json, schema ComputerPatchRequest)

Body for PATCH /api/computer/{id} — a partial update merged onto the computer's current writable field set: an omitted/null field keeps the stored value, an empty string clears it. Uuid: pass the empty GUID to clear. There is no groupId — group membership is a group operation (POST/DELETE /api/group/{id}/computers), never a computer write. The merged result runs through string? ComputerWriteRules.Validate(ComputerWriteRequest request, out ComputerWriteRequest normalized), so invariants (MAC-or-UUID, static-IP block, …) hold after the merge. Unknown JSON properties are rejected (400 naming the property) — on a PATCH a typo'd field would otherwise return 200 while silently not updating anything. Description is accepted for backward compatibility but is a pure no-op — see ComputerWriteRequest's doc comment. SerialNumber follows the same delete-not-blank convention as Ou: an empty string deletes the WMIBios row (not just clears the column) so a later inventory scan can seed it cleanly again.

Field	Type	Required	Description
`name`	string, nullable	No	Name of the computer.
`domain`	string, nullable	No	Domain name.
`isDomain`	boolean, nullable	No	`true` if the computer is domain-joined.
`inventoryId`	string, nullable	No	Inventory ID.
`macAddress`	string, nullable	No	MAC address.
`uuid`	string (uuid), nullable	No	Hardware UUID of the computer.
`pxeSupport`	boolean, nullable	No	`true` if the computer supports PXE boot.
`ipAddress`	string, nullable	No	IP address.
`subnetMask`	string, nullable	No	Subnet mask.
`standardGateway`	string, nullable	No	Default gateway.
`ou`	string, nullable	No	Organizational unit (OU).
`serialNumber`	string, nullable	No	Serial number.
`description`	string, nullable	No	Description of the computer.

Example request body (placeholder values):

{
    "name": "string",
    "domain": "string",
    "isDomain": false,
    "inventoryId": "string",
    "macAddress": "string",
    "uuid": "00000000-0000-0000-0000-000000000000",
    "pxeSupport": false,
    "ipAddress": "string",
    "subnetMask": "string",
    "standardGateway": "string",
    "ou": "string",
    "serialNumber": "string",
    "description": "string"
}

Responses

Status	Description	Schema
`200`	OK	Not described in the specification
`409`	Conflict	ComputerWriteConflict

DELETE /api/computer/{id}

Deletes a computer.

Required role: computer.write

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Client id of the computer to delete.
`force`	query	boolean	No	Required `true` to delete a computer that is still assigned to a group.

Responses

Status	Description	Schema
`204`	Deleted.	–
`404`	Typed body: `ComputerNotFound`.	ComputerDeleteConflict
`409`	Typed body: `MasterServer` (never deletable) or `Assigned` (retry with `force=true`).	ComputerDeleteConflict

POST /api/computer/search

Searches managed endpoints using one or more filter criteria.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Request body (required, application/json, schema ComputerSearchFilter)

Field	Type	Required	Description
`clientId`	integer (int32), nullable	No	Computer ID (Empirum `client_id`).
`hostname`	string, nullable	No	Hostname of the computer.
`uuid`	string (uuid), nullable	No	Hardware UUID of the computer.
`macAddress`	string, nullable	No	MAC address.
`serialNumber`	string, nullable	No	Serial number.
`domain`	string, nullable	No	Domain name.
`manufacturer`	string, nullable	No	Manufacturer.
`minRamGb`	integer (int32), nullable	No	Minimum RAM in GB.
`lastSeenAfter`	string (date-time), nullable	No	Only computers seen after this UTC timestamp.
`modifiedAfter`	string (date-time), nullable	No	Only computers modified after this UTC timestamp.
`inventoryAfter`	string (date-time), nullable	No	Only computers inventoried after this UTC timestamp.
`inventoryBefore`	string (date-time), nullable	No	Only computers inventoried before this UTC timestamp.
`neverSeen`	boolean, nullable	No	Only computers that never contacted the server.
`neverInventoried`	boolean, nullable	No	Only computers without an inventory.
`osName`	string, nullable	No	Operating system name.
`osEdition`	string, nullable	No	Operating system edition.
`osVersion`	string, nullable	No	Operating system version.
`osBuild`	string, nullable	No	Operating system build number.
`platform`	string, nullable	No	Platform.
`language`	string, nullable	No	Language.
`architecture`	string, nullable	No	Architecture.
`ipAddress`	string, nullable	No	IP address.
`ou`	string, nullable	No	Organizational unit (OU).
`pxeSupport`	boolean, nullable	No	`true` if the computer supports PXE boot.
`isPxeActive`	boolean, nullable	No	`true` if PXE boot is activated.

Example request body (placeholder values):

{
    "clientId": 0,
    "hostname": "string",
    "uuid": "00000000-0000-0000-0000-000000000000",
    "macAddress": "string",
    "serialNumber": "string",
    "domain": "string",
    "manufacturer": "string",
    "minRamGb": 0,
    "lastSeenAfter": "2026-01-01T00:00:00Z",
    "modifiedAfter": "2026-01-01T00:00:00Z",
    "inventoryAfter": "2026-01-01T00:00:00Z",
    "inventoryBefore": "2026-01-01T00:00:00Z",
    "neverSeen": false,
    "neverInventoried": false,
    "osName": "string",
    "osEdition": "string",
    "osVersion": "string",
    "osBuild": "string",
    "platform": "string",
    "language": "string",
    "architecture": "string",
    "ipAddress": "string",
    "ou": "string",
    "pxeSupport": false,
    "isPxeActive": false
}

Responses

Status	Description	Schema
`200`	OK	PagedResultOfComputer

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`id`	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`hostname`	string	Yes	Hostname of the computer.
`domain`	string, nullable	Yes	Domain name.
`macAddress`	string, nullable	Yes	MAC address.
`uuid`	string (uuid)	Yes	Hardware UUID of the computer.
`lastSeenUtc`	string (date-time), nullable	Yes	Last agent contact (UTC).
`serialNumber`	string, nullable	No	Serial number.
`lastModified`	string (date-time), nullable	No	Time of the last modification (UTC).
`inventoryDate`	string (date-time), nullable	No	Date of the last inventory (UTC).
`inventoryId`	string, nullable	No	Inventory ID.
`ou`	string, nullable	No	Organizational unit (OU).
`pxeSupport`	boolean	No	`true` if the computer supports PXE boot.
`isPxeActive`	boolean	No	`true` if PXE boot is activated.

GET /api/computer/patch-status

Returns the fleet-wide status of a single patch across all computers with scan data for it.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).
`lastSeenWithinDays`	query	integer (int32)	No	Only computers that contacted the server within the last N days.
`domain`	query	string	No	Filter by domain name.
`hostnameContains`	query	string	No	Filter by a substring of the hostname.
`groupId`	query	string (uuid)	No	Restrict results to computers in this deployment group (GUID).
`IsEmpty`	query	boolean	No	Filter for empty (`true`) or non-empty (`false`) results.
`patchId`	query	integer (int32)	No	Patch ID.
`qNumber`	query	string	No	Filter by patch Q-number (KB article).
`patchName`	query	string	No	Filter by patch name (substring).
`scanStatus`	query	string	No	Filter by patch scan status.

Responses

Status	Description	Schema
`200`	OK	PagedResultOfPatchStatusDevice

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

One computer's scan state for a single patch (fleet-wide patch pivot).

Field	Type	Required	Description
`id`	integer (int32)	Yes	ID of the patch.
`hostname`	string	Yes	Hostname of the computer.
`domain`	string, nullable	Yes	Domain name.
`lastScanDate`	string (date-time), nullable	Yes	Date of the last patch scan.
`scanStatus`	string, nullable	Yes	Patch scan status.
`patchStatus`	string, nullable	Yes	Patch status.
`isAssigned`	boolean	Yes	`true` if assigned.
`installedDate`	string (date-time), nullable	Yes	Installation date.
`qNumber`	string, nullable	Yes	Patch Q-number (KB article).
`patchName`	string, nullable	Yes	Patch name.
`productName`	string, nullable	Yes	Product name.
`patchId`	integer (int32)	Yes	Patch ID.
`patchUid`	string (uuid)	Yes	Unique patch identifier.
`productId`	integer (int32)	No	Patch catalog product ID.

POST /api/computer/software-search

Returns all computers that have every specified product installed (AND across the list).

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Request body (required, application/json, schema InstalledSoftwareSearchRequest)

Field	Type	Required	Description
`products`	array of InstalledSoftwareFilter	Yes	Products.

Example request body (placeholder values):

{
    "products": [
        {
            "productName": "string",
            "version": "string"
        }
    ]
}

Responses

Status	Description	Schema
`200`	Paged list of matching computers.	PagedResultOfComputer

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`id`	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`hostname`	string	Yes	Hostname of the computer.
`domain`	string, nullable	Yes	Domain name.
`macAddress`	string, nullable	Yes	MAC address.
`uuid`	string (uuid)	Yes	Hardware UUID of the computer.
`lastSeenUtc`	string (date-time), nullable	Yes	Last agent contact (UTC).
`serialNumber`	string, nullable	No	Serial number.
`lastModified`	string (date-time), nullable	No	Time of the last modification (UTC).
`inventoryDate`	string (date-time), nullable	No	Date of the last inventory (UTC).
`inventoryId`	string, nullable	No	Inventory ID.
`ou`	string, nullable	No	Organizational unit (OU).
`pxeSupport`	boolean	No	`true` if the computer supports PXE boot.
`isPxeActive`	boolean	No	`true` if PXE boot is activated.

POST /api/computer/distribution-history/search

Searches distribution events across all computers (ArchiveDistJobs).

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Request body (required, application/json, schema DistributionHistorySearchFilter)

Field	Type	Required	Description
`packageName`	string, nullable	No	Substring match on the package name.
`version`	string, nullable	No	Prefix match on the package version, e.g. "11.0" matches 11.0, 11.0.4, ...
`after`	string (date-time), nullable	No	Only events at or after this UTC timestamp.
`before`	string (date-time), nullable	No	Only events at or before this UTC timestamp.
`result`	string, nullable	No	Substring (case-insensitive) match on the result, e.g. "Success".
`installMode`	string, nullable	No	Substring (case-insensitive) match on the install mode.
`info`	string, nullable	No	Substring (case-insensitive) match on the info field (the installer command line the agent reported).

Example request body (placeholder values):

{
    "packageName": "string",
    "version": "string",
    "after": "2026-01-01T00:00:00Z",
    "before": "2026-01-01T00:00:00Z",
    "result": "string",
    "installMode": "string",
    "info": "string"
}

Responses

Status	Description	Schema
`200`	OK	PagedResultOfComputerDistributionEvent

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`computerId`	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`hostname`	string	Yes	Hostname of the computer.
`domain`	string, nullable	Yes	Domain name.
`packageName`	string, nullable	Yes	Package name.
`version`	string, nullable	Yes	Version.
`result`	string, nullable	Yes	Result.
`classification`	string, nullable	Yes	Patch classification.
`logDateUtc`	string (date-time), nullable	Yes	Log entry time (UTC).
`kbNumber`	string, nullable	Yes	KB article number.
`installMode`	string, nullable	Yes	Installation mode.
`info`	string, nullable	Yes

GET /api/computer/issues/low-disk

Returns all endpoints with at least one fixed drive below the free-space threshold, with drive details.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).
`lastSeenWithinDays`	query	integer (int32)	No	Only computers that contacted the server within the last N days.
`domain`	query	string	No	Filter by domain name.
`hostnameContains`	query	string	No	Filter by a substring of the hostname.
`groupId`	query	string (uuid)	No	Restrict results to computers in this deployment group (GUID).
`IsEmpty`	query	boolean	No	Filter for empty (`true`) or non-empty (`false`) results.
`minFreePercent`	query	integer (int32)	No	Report drives with less free space than this percentage.
`minFreeGb`	query	integer (int32)	No	Report drives with less free space than this value in GB.

Responses

Status	Description	Schema
`200`	OK	PagedResultOfLowDiskComputer

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`id`	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`hostname`	string	Yes	Hostname of the computer.
`domain`	string, nullable	Yes	Domain name.
`macAddress`	string, nullable	Yes	MAC address.
`uuid`	string (uuid)	Yes	Hardware UUID of the computer.
`lastSeenUtc`	string (date-time), nullable	Yes	Last agent contact (UTC).
`serialNumber`	string, nullable	Yes	Serial number.
`lowDiskDrives`	array of LowDiskDrive	Yes	Drives below the free space threshold.

GET /api/computer/issues/battery-wear

Returns all endpoints with at least one battery worn below the health threshold (full-charge capacity as a percentage of design capacity), with battery details.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).
`lastSeenWithinDays`	query	integer (int32)	No	Only computers that contacted the server within the last N days.
`domain`	query	string	No	Filter by domain name.
`hostnameContains`	query	string	No	Filter by a substring of the hostname.
`groupId`	query	string (uuid)	No	Restrict results to computers in this deployment group (GUID).
`IsEmpty`	query	boolean	No	Filter for empty (`true`) or non-empty (`false`) results.
`maxHealthPercent`	query	integer (int32)	No	Report batteries with a health (full charge vs. design capacity) at or below this percentage.

Responses

Status	Description	Schema
`200`	OK	PagedResultOfBatteryWearComputer

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`id`	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`hostname`	string	Yes	Hostname of the computer.
`domain`	string, nullable	Yes	Domain name.
`macAddress`	string, nullable	Yes	MAC address.
`uuid`	string (uuid)	Yes	Hardware UUID of the computer.
`lastSeenUtc`	string (date-time), nullable	Yes	Last agent contact (UTC).
`serialNumber`	string, nullable	Yes	Serial number.
`wornBatteries`	array of WornBattery	Yes	Batteries below the health threshold.

GET /api/computer/issues/bitlocker-off

Returns Windows endpoints whose fixed disks are not BitLocker-encrypted per inventory.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).
`lastSeenWithinDays`	query	integer (int32)	No	Only computers that contacted the server within the last N days.
`domain`	query	string	No	Filter by domain name.
`hostnameContains`	query	string	No	Filter by a substring of the hostname.
`groupId`	query	string (uuid)	No	Restrict results to computers in this deployment group (GUID).
`IsEmpty`	query	boolean	No	Filter for empty (`true`) or non-empty (`false`) results.

Responses

Status	Description	Schema
`200`	OK	PagedResultOfBitlockerOffComputer

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`id`	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`hostname`	string	Yes	Hostname of the computer.
`domain`	string, nullable	Yes	Domain name.
`macAddress`	string, nullable	Yes	MAC address.
`uuid`	string (uuid)	Yes	Hardware UUID of the computer.
`lastSeenUtc`	string (date-time), nullable	Yes	Last agent contact (UTC).
`serialNumber`	string, nullable	Yes	Serial number.
`unencryptedDisks`	array of BitlockerOffDisk	Yes	Fixed drives without BitLocker encryption.

GET /api/computer/issues/pending-reboot

Returns all endpoints with a pending reboot.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).
`lastSeenWithinDays`	query	integer (int32)	No	Only computers that contacted the server within the last N days.
`domain`	query	string	No	Filter by domain name.
`hostnameContains`	query	string	No	Filter by a substring of the hostname.
`groupId`	query	string (uuid)	No	Restrict results to computers in this deployment group (GUID).
`IsEmpty`	query	boolean	No	Filter for empty (`true`) or non-empty (`false`) results.
`minDaysSinceLastReboot`	query	integer (int32)	No	Minimum number of days since the last reboot.

Responses

Status	Description	Schema
`200`	OK	PagedResultOfComputer

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`id`	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`hostname`	string	Yes	Hostname of the computer.
`domain`	string, nullable	Yes	Domain name.
`macAddress`	string, nullable	Yes	MAC address.
`uuid`	string (uuid)	Yes	Hardware UUID of the computer.
`lastSeenUtc`	string (date-time), nullable	Yes	Last agent contact (UTC).
`serialNumber`	string, nullable	No	Serial number.
`lastModified`	string (date-time), nullable	No	Time of the last modification (UTC).
`inventoryDate`	string (date-time), nullable	No	Date of the last inventory (UTC).
`inventoryId`	string, nullable	No	Inventory ID.
`ou`	string, nullable	No	Organizational unit (OU).
`pxeSupport`	boolean	No	`true` if the computer supports PXE boot.
`isPxeActive`	boolean	No	`true` if PXE boot is activated.

GET /api/computer/issues/stale-agent

Returns all endpoints whose UEM agent has stopped reporting on schedule.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).
`lastSeenWithinDays`	query	integer (int32)	No	Only computers that contacted the server within the last N days.
`domain`	query	string	No	Filter by domain name.
`hostnameContains`	query	string	No	Filter by a substring of the hostname.
`groupId`	query	string (uuid)	No	Restrict results to computers in this deployment group (GUID).
`IsEmpty`	query	boolean	No	Filter for empty (`true`) or non-empty (`false`) results.
`minHoursStale`	query	integer (int32)	No	Minimum number of hours since the last agent contact.
`maxHoursStale`	query	integer (int32)	No	Maximum number of hours since the last agent contact.

Responses

Status	Description	Schema
`200`	OK	PagedResultOfStaleAgentComputer

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`id`	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`hostname`	string	Yes	Hostname of the computer.
`domain`	string, nullable	Yes	Domain name.
`macAddress`	string, nullable	Yes	MAC address.
`uuid`	string (uuid)	Yes	Hardware UUID of the computer.
`lastSeenUtc`	string (date-time), nullable	Yes	Last agent contact (UTC).
`serialNumber`	string, nullable	Yes	Serial number.
`hoursStale`	number (double), nullable	Yes	Hours since the last agent contact.

GET /api/computer/issues/stale-inventory

Returns all endpoints whose last inventory scan is at least minDaysStale days old.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).
`lastSeenWithinDays`	query	integer (int32)	No	Only computers that contacted the server within the last N days.
`domain`	query	string	No	Filter by domain name.
`hostnameContains`	query	string	No	Filter by a substring of the hostname.
`groupId`	query	string (uuid)	No	Restrict results to computers in this deployment group (GUID).
`IsEmpty`	query	boolean	No	Filter for empty (`true`) or non-empty (`false`) results.
`minDaysStale`	query	integer (int32)	No	Minimum age of the last inventory in days.
`includeNeverInventoried`	query	boolean	No	Include computers that were never inventoried.

Responses

Status	Description	Schema
`200`	OK	PagedResultOfStaleInventoryComputer

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

LastInventoryUtc/DaysStale are null for never-inventoried devices (only included when the sweep asks for them).

Field	Type	Required	Description
`id`	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`hostname`	string	Yes	Hostname of the computer.
`domain`	string, nullable	Yes	Domain name.
`macAddress`	string, nullable	Yes	MAC address.
`uuid`	string (uuid)	Yes	Hardware UUID of the computer.
`lastSeenUtc`	string (date-time), nullable	Yes	Last agent contact (UTC).
`serialNumber`	string, nullable	Yes	Serial number.
`lastInventoryUtc`	string (date-time), nullable	Yes	Time of the last inventory (UTC).
`daysStale`	number (double), nullable	Yes	Age of the last inventory in days.

GET /api/computer/issues/failed-deployment

Returns all endpoints with at least one software deployment that has failed, with the failed package list.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).
`lastSeenWithinDays`	query	integer (int32)	No	Only computers that contacted the server within the last N days.
`domain`	query	string	No	Filter by domain name.
`hostnameContains`	query	string	No	Filter by a substring of the hostname.
`groupId`	query	string (uuid)	No	Restrict results to computers in this deployment group (GUID).
`IsEmpty`	query	boolean	No	Filter for empty (`true`) or non-empty (`false`) results.
`minFailedCount`	query	integer (int32)	No	Minimum number of failed installations.
`softwareId`	query	string (uuid)	No	Software package ID (GUID).
`packageName`	query	string	No	Filter by package name (substring).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfFailedDeploymentComputer

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`id`	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`hostname`	string	Yes	Hostname of the computer.
`domain`	string, nullable	Yes	Domain name.
`macAddress`	string, nullable	Yes	MAC address.
`uuid`	string (uuid)	Yes	Hardware UUID of the computer.
`lastSeenUtc`	string (date-time), nullable	Yes	Last agent contact (UTC).
`serialNumber`	string, nullable	Yes	Serial number.
`failedPackages`	array of FailedDeploymentItem	Yes	Packages with failed installations.

GET /api/computer/issues/shared-package-failure

Returns packages whose installation fails on multiple devices, grouped by package.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).
`lastSeenWithinDays`	query	integer (int32)	No	Only computers that contacted the server within the last N days.
`domain`	query	string	No	Filter by domain name.
`hostnameContains`	query	string	No	Filter by a substring of the hostname.
`groupId`	query	string (uuid)	No	Restrict results to computers in this deployment group (GUID).
`IsEmpty`	query	boolean	No	Filter for empty (`true`) or non-empty (`false`) results.
`minAffectedCount`	query	integer (int32)	No	Minimum number of affected devices per package.
`softwareId`	query	string (uuid)	No	Software package ID (GUID).
`includeDevices`	query	boolean	No	Include the list of affected devices in the result.

Responses

Status	Description	Schema
`200`	OK	PagedResultOfSharedPackageFailure

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`softwareId`	string (uuid), nullable	Yes	Software package ID (GUID).
`packageName`	string, nullable	Yes	Package name.
`affectedDeviceCount`	integer (int32)	Yes	Number of affected devices.
`affectedDevices`	array of SharedFailureDevice	Yes	Affected devices.

GET /api/computer/issues/shared-package-failure/devices

Drill-down for the shared-package-failure issue: all devices (paged) where the given package currently fails.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).
`lastSeenWithinDays`	query	integer (int32)	No	Only computers that contacted the server within the last N days.
`domain`	query	string	No	Filter by domain name.
`hostnameContains`	query	string	No	Filter by a substring of the hostname.
`groupId`	query	string (uuid)	No	Restrict results to computers in this deployment group (GUID).
`IsEmpty`	query	boolean	No	Filter for empty (`true`) or non-empty (`false`) results.
`softwareId`	query	string (uuid)	No	Software package ID (GUID).
`packageName`	query	string	No	Filter by package name (substring).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfSharedFailureDevice

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`id`	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`hostname`	string	Yes	Hostname of the computer.
`domain`	string, nullable	Yes	Domain name.
`lastFailedUtc`	string (date-time), nullable	Yes	Time of the last failed installation (UTC).
`errorText`	string, nullable	Yes	Error text.

GET /api/computer/issues/missing-patch

Returns all endpoints currently missing patches.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).
`lastSeenWithinDays`	query	integer (int32)	No	Only computers that contacted the server within the last N days.
`domain`	query	string	No	Filter by domain name.
`hostnameContains`	query	string	No	Filter by a substring of the hostname.
`groupId`	query	string (uuid)	No	Restrict results to computers in this deployment group (GUID).
`IsEmpty`	query	boolean	No	Filter for empty (`true`) or non-empty (`false`) results.
`qNumber`	query	string	No	Filter by patch Q-number (KB article).
`bulletinId`	query	string	No	Filter by security bulletin ID.
`bulletinTitle`	query	string	No	Filter by security bulletin title (substring).
`productName`	query	string	No	Filter by product name (substring).
`patchType`	query	string	No	Filter by patch type.
`minSeverity`	query	string	No	Minimum vendor severity.
`minCvss`	query	number (double)	No	Minimum CVSS score.
`minVrr`	query	number (double)	No	Minimum Vulnerability Risk Rating (VRR) score.
`assigned`	query	boolean	No	Filter for assigned (`true`) or unassigned (`false`) items.
`minCount`	query	integer (int32)	No	Minimum number of missing patches per computer.

Responses

Status	Description	Schema
`200`	OK	PagedResultOfMissingPatchComputer

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`id`	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`hostname`	string	Yes	Hostname of the computer.
`domain`	string, nullable	Yes	Domain name.
`macAddress`	string, nullable	Yes	MAC address.
`uuid`	string (uuid)	Yes	Hardware UUID of the computer.
`lastSeenUtc`	string (date-time), nullable	Yes	Last agent contact (UTC).
`serialNumber`	string, nullable	Yes	Serial number.
`missingPatches`	array of MissingPatchItem	Yes	Missing patches.
`pmClientGaps`	array of string	Yes

GET /api/computer/issues/stale-deployment

Returns endpoints where a software installation was assigned but never started, even though the device is online.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).
`lastSeenWithinDays`	query	integer (int32)	No	Only computers that contacted the server within the last N days.
`domain`	query	string	No	Filter by domain name.
`hostnameContains`	query	string	No	Filter by a substring of the hostname.
`groupId`	query	string (uuid)	No	Restrict results to computers in this deployment group (GUID).
`IsEmpty`	query	boolean	No	Filter for empty (`true`) or non-empty (`false`) results.
`minHoursPending`	query	integer (int32)	No	Minimum number of hours a reboot has been pending.
`softwareId`	query	string (uuid)	No	Software package ID (GUID).
`packageName`	query	string	No	Filter by package name (substring).
`maxDaysPending`	query	integer (int32)	No	Maximum number of days a deployment has been pending.

Responses

Status	Description	Schema
`200`	OK	PagedResultOfStaleDeploymentComputer

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`id`	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`hostname`	string	Yes	Hostname of the computer.
`domain`	string, nullable	Yes	Domain name.
`macAddress`	string, nullable	Yes	MAC address.
`uuid`	string (uuid)	Yes	Hardware UUID of the computer.
`lastSeenUtc`	string (date-time), nullable	Yes	Last agent contact (UTC).
`serialNumber`	string, nullable	Yes	Serial number.
`stalePendingPackages`	array of StaleDeploymentItem	Yes	Packages pending longer than the threshold.

GET /api/computer/issues/agent-suspended

Returns all endpoints whose UEM agent is currently paused.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).
`lastSeenWithinDays`	query	integer (int32)	No	Only computers that contacted the server within the last N days.
`domain`	query	string	No	Filter by domain name.
`hostnameContains`	query	string	No	Filter by a substring of the hostname.
`groupId`	query	string (uuid)	No	Restrict results to computers in this deployment group (GUID).
`IsEmpty`	query	boolean	No	Filter for empty (`true`) or non-empty (`false`) results.

Responses

Status	Description	Schema
`200`	OK	PagedResultOfSuspendedComputer

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`id`	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`hostname`	string	Yes	Hostname of the computer.
`domain`	string, nullable	Yes	Domain name.
`macAddress`	string, nullable	Yes	MAC address.
`uuid`	string (uuid)	Yes	Hardware UUID of the computer.
`lastSeenUtc`	string (date-time), nullable	Yes	Last agent contact (UTC).
`serialNumber`	string, nullable	Yes	Serial number.
`suspensionMode`	SuspensionMode (enum: Suspended, PresentationMode, MaintenanceMode)	Yes	Agent suspension mode.
`suspendedUntil`	string (date-time), nullable	Yes	End of the agent suspension (UTC).

GET /api/computer/issues/overview

Returns all endpoints that have at least one active issue, with each matched issue inline.

lastSeenDays=0 disables the recency filter. issues restricts to a comma-separated subset of issue names (e.g. "low-disk,failed-deployment"); omitted = all issues. minFreePercent/minFreeGb, maxHealthPercent, minHoursStale/maxHoursStale, and minHoursPending/maxDaysPending override the low-disk, battery-wear, stale-agent, and stale-deployment thresholds respectively — omitting them reproduces that endpoint's default behavior exactly.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).
`lastSeenWithinDays`	query	integer (int32)	No	Only computers that contacted the server within the last N days.
`domain`	query	string	No	Filter by domain name.
`hostnameContains`	query	string	No	Filter by a substring of the hostname.
`groupId`	query	string (uuid)	No	Restrict results to computers in this deployment group (GUID).
`IsEmpty`	query	boolean	No	Filter for empty (`true`) or non-empty (`false`) results.
`lastSeenDays`	query	integer (int32)	No	Only computers that contacted the server within the last N days.
`issues`	query	string	No	Restrict the overview to these issue types.
`minFreePercent`	query	integer (int32)	No	Report drives with less free space than this percentage.
`minFreeGb`	query	integer (int32)	No	Report drives with less free space than this value in GB.
`maxHealthPercent`	query	integer (int32)	No	Report batteries with a health (full charge vs. design capacity) at or below this percentage.
`minHoursStale`	query	integer (int32)	No	Minimum number of hours since the last agent contact.
`maxHoursStale`	query	integer (int32)	No	Maximum number of hours since the last agent contact.
`minHoursPending`	query	integer (int32)	No	Minimum number of hours a reboot has been pending.
`maxDaysPending`	query	integer (int32)	No	Maximum number of days a deployment has been pending.

Responses

Status	Description	Schema
`200`	OK	PagedResultOfIssueOverviewComputer

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`id`	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`hostname`	string	Yes	Hostname of the computer.
`domain`	string, nullable	Yes	Domain name.
`macAddress`	string, nullable	Yes	MAC address.
`uuid`	string (uuid)	Yes	Hardware UUID of the computer.
`lastSeenUtc`	string (date-time), nullable	Yes	Last agent contact (UTC).
`serialNumber`	string, nullable	Yes	Serial number.
`issues`	array of IssueHit	Yes	Issues.

GET /api/computer/{id}/issues

Full issue picture for one endpoint: every fleet issue evaluated against this device, with detail inline.

Same verdict logic as the fleet issues endpoints (each sweep scoped to this client). Null sections mean the issue is not present. Missing patches use the SecurityPatch default and are capped at 25 entries — use the per-device patches-search for the full list.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).

Responses

Status	Description	Schema
`200`	OK	ComputerIssues

Response fields (ComputerIssues):

Full issue picture for one device: every fleet issue evaluated against this client, with the same detail payload the per-issue sweep would embed. A null section (or false/null scalar) means the issue is not present; ActiveIssues lists the names of all sections that hit, in IssueNames.Overview order.

Field	Type	Required	Description
`id`	integer (int32)	Yes
`hostname`	string	Yes	Hostname of the computer.
`domain`	string, nullable	Yes	Domain name.
`macAddress`	string, nullable	Yes	MAC address.
`uuid`	string (uuid)	Yes	Hardware UUID of the computer.
`lastSeenUtc`	string (date-time), nullable	Yes	Last agent contact (UTC).
`serialNumber`	string, nullable	Yes	Serial number.
`activeIssues`	array of string	Yes	Active issues.
`failedPackages`	array of FailedDeploymentItem, nullable	Yes	Packages with failed installations.
`missingPatches`	array of MissingPatchItem, nullable	Yes	Missing patches.
`pmClientGaps`	array of string, nullable	Yes
`unencryptedDisks`	array of BitlockerOffDisk, nullable	Yes	Fixed drives without BitLocker encryption.
`lowDiskDrives`	array of LowDiskDrive, nullable	Yes	Drives below the free space threshold.
`wornBatteries`	array of WornBattery, nullable	Yes	Batteries below the health threshold.
`pendingReboot`	boolean	Yes	`true` if a reboot is pending.
`staleAgentHours`	number (double), nullable	Yes	Threshold in hours for a stale agent.
`staleInventoryDays`	number (double), nullable	Yes	Threshold in days for a stale inventory.
`stalePendingPackages`	array of StaleDeploymentItem, nullable	Yes	Packages pending longer than the threshold.
`suspensionMode`	SuspensionMode (enum: Suspended, PresentationMode, MaintenanceMode)	Yes	Agent suspension mode.
`suspendedUntil`	string (date-time), nullable	Yes	End of the agent suspension (UTC).

GET /api/computer/{id}/security-posture

Returns antivirus, firewall, Secure Boot, and script-policy state for an endpoint.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`staleAfterDays`	query	integer (int32)	No	Number of days after which an inventory is considered stale.

Responses

Status	Description	Schema
`200`	OK	SecurityPosture

Response fields (SecurityPosture):

Per-component security status with inventory-scan staleness context. Component data comes from the last inventory scan; when that scan is older than StaleAfterDays (query parameter, default 3), IsStale is true and component statuses (e.g. an "up to date" antivirus signature) may not reflect the current device state. A never-inventoried device is always stale (null date/age).

Field	Type	Required	Description
`clientId`	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`inventoryDateUtc`	string (date-time), nullable	Yes	Date of the last inventory (UTC).
`inventoryAgeDays`	integer (int32), nullable	Yes	Age of the last inventory in days.
`isStale`	boolean	Yes	`true` if the inventory is older than the threshold.
`staleAfterDays`	integer (int32)	Yes	Threshold in days for a stale inventory.
`antivirus`	AntivirusInfo	Yes	Antivirus status.
`firewall`	FirewallStatus	Yes	Firewall status.
`secureBoot`	SecureBootStatus	Yes	Secure Boot status.
`scriptPolicy`	ScriptPolicyStatus	Yes	Script execution policy.
`bitlocker`	BitlockerInfo	Yes	BitLocker status.

GET /api/computer/{id}/system-info

Returns last-inventory system info and customer-defined management properties for an endpoint.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).

Responses

Status	Description	Schema
`200`	OK	SystemInfo

Response fields (SystemInfo):

Field	Type	Required	Description
`clientId`	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`name`	string, nullable	Yes
`domain`	string, nullable	Yes	Domain name.
`fqdn`	string, nullable	Yes	Fully qualified domain name.
`inventoryId`	string, nullable	Yes	Inventory ID.
`lastSeenUtc`	string (date-time), nullable	Yes	Last agent contact (UTC).
`operatingSystem`	string, nullable	Yes	Operating system.
`osName`	string, nullable	Yes	Operating system name.
`osEdition`	string, nullable	Yes	Operating system edition.
`osVersion`	string, nullable	Yes	Operating system version.
`osBuild`	string, nullable	Yes	Operating system build number.
`platform`	string, nullable	Yes	Platform.
`language`	string, nullable	Yes	Language.
`architecture`	string, nullable	Yes	Architecture.
`processorName`	string, nullable	Yes	Processor name.
`processorCount`	integer (int32), nullable	Yes	Number of processors.
`processorMhz`	integer (int32), nullable	Yes	Processor clock speed in MHz.
`memoryMb`	integer (int32), nullable	Yes	Memory in MB.
`manufacturer`	string, nullable	Yes	Manufacturer.
`model`	string, nullable	Yes	Model.
`biosVersion`	string, nullable	Yes	BIOS version.
`biosDate`	string, nullable	Yes	BIOS date.
`userIsAdmin`	boolean, nullable	Yes	`true` if the logged-on user has administrative rights.
`loggedOnUser`	string, nullable	Yes	Logged-on user.
`timeZone`	string, nullable	Yes	Time zone.
`inventoryDate`	string (date-time), nullable	Yes	Date of the last inventory (UTC).
`displayAdapter`	string, nullable	No	Display adapter.
`screenResolution`	string, nullable	No	Screen resolution.
`bitVersion`	integer (int32), nullable	No	Operating system bitness (32 or 64 bit).
`vmType`	string, nullable	No	Virtual machine type, if virtualized.
`ipAddress`	string, nullable	No	IP address.
`management`	ComputerManagement	No	Management information.
`tempDirSizeMb`	integer (int32), nullable	No	Size of the user temp directory in MB (InvComputer.TempDirSize). Null when the scan did not report it — the temp-dir scan is optional, and a stored 0 is treated as not reported.

GET /api/computer/{id}/variables

Lists this computer's directly-assigned variable value(s).

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Empirum client_id.
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfVariableValue

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

A resolved variable value for one computer or group. string VariableValue.Designation/ string VariableValue.DottedName mirror VariableDefinition. string? VariableValue.Value is null when the variable has no value at the requested scope — a direct-only ("own value only") read with no override returns null rather than falling back to an inherited or catalog-default value; an include-inherited read returns null only when nothing in the whole precedence chain (forced group, own value, inherited group/package, catalog default) has a value either.

Field	Type	Required	Description
`varId`	integer (int32)	Yes	Variable definition ID.
`designation`	string	Yes	Designation.
`dottedName`	string	Yes	Fully qualified (dotted) variable name.
`value`	string, nullable	Yes

POST /api/computer/{id}/variables/search

Resolves a single computer variable's value, with optional inheritance resolution.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Empirum client_id.
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Request body (required, application/json, schema VariableValueSearchFilter)

Filter body for POST .../variables/search — single-variable lookup with optional inheritance resolution, the computer/group-scoped counterpart to VariableDefinitionSearchFilter.

Field	Type	Required	Description
`name`	string, nullable	No	Raw designation or dotted "parent.child" name; mutually exclusive with varId.
`varId`	integer (int32), nullable	No	Variable's VarID; mutually exclusive with name.
`includeInherited`	boolean	No	False (default) returns only the direct override/value, with no fallback; true resolves the full inheritance precedence.

Example request body (placeholder values):

{
    "name": "string",
    "varId": 0,
    "includeInherited": false
}

Responses

Status	Description	Schema
`200`	OK	PagedResultOfVariableValue

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`varId`	integer (int32)	Yes	Variable definition ID.
`designation`	string	Yes	Designation.
`dottedName`	string	Yes	Fully qualified (dotted) variable name.
`value`	string, nullable	Yes

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.

Required role: computer.write

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Empirum client_id.
`varId`	path	integer (int32)	Yes	Variable's VarID (must not be a collection or UserDefined variable).

Request body (required, application/json, schema SetVariableValueRequest)

Body for PUT .../variables/{varId} — sets this computer's/group's own (direct, non-inherited) value for a scalar (non-collection) variable. string? SetVariableValueRequest.Value = null (or an omitted field) deletes the underlying CompVariables/GroupVariables row entirely — a subsequent read falls back to inheritance/catalog default, mirroring the existing delete-not-blank convention for ORGANIZATIONAL_UNIT. An empty string "" is a real, stored value, not a deletion. Not valid for collection variables (DefCompPkgVar.Collection = 1) — use the .../collection endpoints instead.

Field	Type	Required	Description
`value`	string, nullable	Yes

Example request body (placeholder values):

{
    "value": "string"
}

Responses

Status	Description	Schema
`200`	OK	VariableValue

Response fields (VariableValue):

Field	Type	Required	Description
`varId`	integer (int32)	Yes	Variable definition ID.
`designation`	string	Yes	Designation.
`dottedName`	string	Yes	Fully qualified (dotted) variable name.
`value`	string, nullable	Yes

GET /api/computer/{id}/variables/{varId}/collection

Lists this computer's direct entries (bundles) for a collection variable.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Empirum client_id.
`varId`	path	integer (int32)	Yes	Collection variable's VarID (DefCompPkgVar.Collection = 1).
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfVariableCollectionEntry

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

One bundle/array-entry of a collection variable (DefCompPkgVar.Collection = 1) — one CompVariables/GroupVariables row per child variable, all sharing the same CollectionID. int VariableCollectionEntry.CollectionId is the raw CollectionID column value — verified live NOT to be contiguous from 1 (existing bundles can be numbered e.g. 2 and 3 with no row using 1); this is the identifier callers use to reference a specific entry (e.g. for PATCH), not a display position. IReadOnlyList<VariableValue> VariableCollectionEntry.Values has exactly one entry per child variable (DefCompPkgVar rows with ParentID = the collection variable's VarID), ordered by VarID ascending (their catalog definition order — no reliable SEQUENCE value was found live).

Field	Type	Required	Description
`collectionId`	integer (int32)	Yes	Collection ID.
`values`	array of VariableValue	Yes

POST /api/computer/{id}/variables/{varId}/collection

Adds one new entry (bundle) to a collection variable on this computer.

Required role: computer.write

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Empirum client_id.
`varId`	path	integer (int32)	Yes	Collection variable's VarID.

Request body (required, application/json, schema VariableCollectionEntryRequest)

Body for POST .../variables/{varId}/collection — creates one new collection entry (bundle). IReadOnlyDictionary<string, string> VariableCollectionEntryRequest.Values is keyed by child Designation (not VarID) for readability; unknown keys (a Designation that isn't a child of this collection variable) are rejected with 400. A child may be omitted only if its DefCompPkgVar.DefaultValue is non-null — the created row then uses that default; omitting a child with no default is a 400. All child rows for the new entry are inserted together in one transaction — a partial bundle is never created.

Field	Type	Required	Description
`values`	map of string to string	Yes

Example request body (placeholder values):

{
    "values": {}
}

Responses

Status	Description	Schema
`200`	OK	VariableCollectionEntry

Response fields (VariableCollectionEntry):

Field	Type	Required	Description
`collectionId`	integer (int32)	Yes	Collection ID.
`values`	array of VariableValue	Yes

PATCH /api/computer/{id}/variables/{varId}/collection/{collectionId}

Partially updates one existing variable collection entry.

Required role: computer.write

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Empirum client_id.
`varId`	path	integer (int32)	Yes	Collection variable's VarID.
`collectionId`	path	integer (int32)	Yes	Entry's CollectionId (from GET .../collection — the raw DB value, not necessarily contiguous).

Request body (required, application/json, schema VariableCollectionEntryPatchRequest)

Body for PATCH .../variables/{varId}/collection/{collectionId} — partially updates an existing collection entry (bundle), identified directly by its int VariableCollectionEntry.CollectionId (the raw DB value, not necessarily contiguous). Unlike VariableCollectionEntryRequest, this is a genuine partial update: only the supplied child Designations change, every other child value in the bundle is left untouched — an omitted child never falls back to DefaultValue (the bundle already has a real value for every child from when it was created). An unrecognized key is a 400, same as the create request.

Field	Type	Required	Description
`values`	map of string to string	Yes

Example request body (placeholder values):

{
    "values": {}
}

Responses

Status	Description	Schema
`200`	OK	VariableCollectionEntry

Response fields (VariableCollectionEntry):

Field	Type	Required	Description
`collectionId`	integer (int32)	Yes	Collection ID.
`values`	array of VariableValue	Yes

DELETE /api/computer/{id}/variables/{varId}/collection/{collectionId}

Deletes an entire variable collection entry (all its child values).

Required role: computer.write

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Empirum client_id.
`varId`	path	integer (int32)	Yes	Collection variable's VarID.
`collectionId`	path	integer (int32)	Yes	Entry's CollectionId (from GET .../collection — the raw DB value, not necessarily contiguous).

Responses

Status	Description	Schema
`204`	No Content	–

GET /api/computer/{id}/reboot-status

Returns whether a reboot is pending and what triggered it (e.g. WindowsUpdate, SoftwareInstall).

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).

Responses

Status	Description	Schema
`200`	OK	RebootStatus

Response fields (RebootStatus):

Field	Type	Required	Description
`clientId`	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`lastReboot`	string (date-time), nullable	Yes	Time of the last reboot (UTC).
`uptime`	string, nullable	Yes	Time since the last reboot.
`rebootRequired`	boolean	Yes	`true` if a reboot is required.
`rebootRequiredSource`	string, nullable	Yes	Source that requires the reboot.
`lastUpdated`	string (date-time), nullable	Yes	Time of the last update (UTC).

GET /api/computer/{id}/groups

Returns the Empirum deployment groups the endpoint belongs to, optionally filtered by a group-name substring.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).
`nameContains`	query	string	No	Filter by a substring of the name.

Responses

Status	Description	Schema
`200`	OK	PagedResultOfDeviceGroup

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`groupId`	string (uuid)	Yes	Deployment group ID (GUID).
`name`	string	Yes	Name of the group.
`assignedToTree`	string, nullable	Yes	Tree the group is assigned to.
`description`	string, nullable	Yes	Description of the group.

GET /api/computer/{id}/packages/{packageId}/groups

Returns the configuration/assignment groups through which a given package is assigned to this computer.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`packageId`	path	string (uuid)	Yes	Software package ID (GUID).
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfDeviceGroup

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`groupId`	string (uuid)	Yes	Deployment group ID (GUID).
`name`	string	Yes	Name of the group.
`assignedToTree`	string, nullable	Yes	Tree the group is assigned to.
`description`	string, nullable	Yes	Description of the group.

GET /api/computer/{id}/agent-template

Returns the computer's effective Agent Template — resolved via its own group and ancestor groups by EMC's own resolver (assignment only ever happens at the group level), with the winning group as provenance.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).

Responses

Status	Description	Schema
`200`	The effective Agent Template.	ComputerAgentTemplate

Response fields (ComputerAgentTemplate):

The computer's effective Agent Template (single winner across the ancestor chain), with the group whose assignment won.

Field	Type	Required	Description
`template`	AgentTemplate	Yes	Template.
`assignedGroupId`	string (uuid)	Yes	ID of the group that holds the assignment.
`assignedGroupPath`	string	Yes	Path of the group that holds the assignment.

GET /api/computer/{id}/os-image-sku

Returns the computer's effective OS image SKU — resolved via its own group and ancestor groups by EMC's own resolver, with the winning group as provenance.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).

Responses

Status	Description	Schema
`200`	The effective OS image SKU.	ComputerOsImageSku

Response fields (ComputerOsImageSku):

The computer's effective OS image SKU (single winner), with image-package context and the group whose assignment won.

Field	Type	Required	Description
`skuId`	integer (int32)	Yes	OS image SKU (edition) ID.
`skuIndex`	integer (int32)	Yes	Index of the SKU in the image.
`edition`	string	Yes	Edition.
`imageName`	string	Yes	Image name.
`imagePath`	string, nullable	Yes	Path of the image.
`osLanguage`	string, nullable	Yes	Operating system language.
`os`	string, nullable	Yes	Operating system.
`osType`	string, nullable	Yes	Operating system type.
`osArchitecture`	string, nullable	Yes	Operating system architecture.
`assignedGroupId`	string (uuid)	Yes	ID of the group that holds the assignment.
`assignedGroupPath`	string	Yes	Path of the group that holds the assignment.

GET /api/computer/{id}/pxe-bootimage

Returns the computer's effective PXE boot image — resolved via its own group and ancestor groups by EMC's own resolver, with the winning group as provenance.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).

Responses

Status	Description	Schema
`200`	The effective PXE boot image.	ComputerPxeBootImage

Response fields (ComputerPxeBootImage):

The computer's effective PXE boot image (single winner), with the group whose assignment won.

Field	Type	Required	Description
`imageId`	integer (int32)	Yes	Image ID.
`imageName`	string	Yes	Image name.
`assignedGroupId`	string (uuid)	Yes	ID of the group that holds the assignment.
`assignedGroupPath`	string	Yes	Path of the group that holds the assignment.

GET /api/computer/{id}/language-packs

Returns the computer's effective OS Language Packs (multi-assign — one winner per pack) — resolved via its own group and ancestor groups by EMC's own resolver, each with the winning group as provenance.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	Paged list; empty when the computer resolves to none.	PagedResultOfComputerLanguagePack

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

One of the computer's effective OS Language Packs (multi-assign — one winner per pack), with the group whose assignment won.

Field	Type	Required	Description
`packageId`	string (uuid)	Yes	Software package ID (GUID).
`imageName`	string	Yes	Image name.
`osLanguage`	string, nullable	Yes	Operating system language.
`imagePath`	string, nullable	Yes	Path of the image.
`os`	string, nullable	Yes	Operating system.
`osType`	string, nullable	Yes	Operating system type.
`osArchitecture`	string, nullable	Yes	Operating system architecture.
`assignedGroupId`	string (uuid)	Yes	ID of the group that holds the assignment.
`assignedGroupPath`	string	Yes	Path of the group that holds the assignment.

GET /api/computer/{id}/uem-agent

Returns UEM agent information grouped into three objects: desiredState, inventory, and dailyStatus.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).

Responses

Status	Description	Schema
`200`	UEM agent info; `inventory` and `dailyStatus` are `null` if no data has been collected yet.	UemAgentInfo

Response fields (UemAgentInfo):

Field	Type	Required	Description
`clientId`	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`outOfSync`	boolean, nullable	Yes	`true` if the agent configuration differs from the assigned template.
`desiredState`	UemAgentDesiredState	Yes	Desired state.
`inventory`	UemAgentInventory	Yes	Inventory.
`dailyStatus`	UemAgentDailyStatus	Yes	Daily status reporting.
`pollingWindows`	UemAgentPollingWindows	Yes	Polling time windows.

GET /api/computer/{id}/health

Returns the agent reporting status and overall health classification for an endpoint.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).

Responses

Status	Description	Schema
`200`	OK	EndpointHealth

Response fields (EndpointHealth):

Field	Type	Required	Description
`clientId`	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`hostname`	string	Yes	Hostname of the computer.
`domain`	string, nullable	Yes	Domain name.
`macAddress`	string, nullable	Yes	MAC address.
`uuid`	string (uuid)	Yes	Hardware UUID of the computer.
`lastSeenUtc`	string (date-time), nullable	Yes	Last agent contact (UTC).
`agentStatus`	AgentStatus (enum: Reporting, Stale, Silent, Unknown)	Yes	Agent status.
`healthStatus`	HealthStatus (enum: Healthy, Warning, Unreachable)	Yes	Health status.
`operatingSystem`	string, nullable	Yes	Operating system.
`ipAddress`	string, nullable	Yes	IP address.
`manufacturer`	string, nullable	Yes	Manufacturer.
`model`	string, nullable	Yes	Model.
`architecture`	string, nullable	Yes	Architecture.
`inventoryDate`	string (date-time), nullable	Yes	Date of the last inventory (UTC).
`agentInstalled`	boolean, nullable	Yes	`true` if the agent is installed.

GET /api/computer/{id}/software-deployment

Returns the assigned Empirum packages for software deployment.

Registry-gated packages (notably the Patch-Management Fix package, which waits for a patch scan to flag missing patches approved for the device's assigned PM groups) legitimately stay Pending until their gate condition is met on the device — for those, Pending is by design, not a stuck deployment.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Empirum client_id of the target computer.
`packageId`	query	string (uuid)	No	Optional: narrow the list to this one package's assignment.
`includePreOsPackages`	query	boolean	No	Include Pre-OS (WinPE) package assignments. Default false mirrors EMC's deployment view, which hides them.

Responses

Status	Description	Schema
`200`	OK	array of SoftwareDeployment

Response fields (SoftwareDeployment):

Field	Type	Required	Description
`softwareId`	string (uuid)	Yes	<inheritdoc />
`name`	string, nullable	Yes	<inheritdoc />
`version`	string, nullable	Yes	<inheritdoc />
`revision`	string, nullable	Yes	<inheritdoc />
`status`	DeploymentStatus (enum: Pending, Success, Failed)	Yes	Deployment state. Registry-gated packages (notably the Patch-Management Fix package) legitimately stay Pending until a patch scan detects a missing patch approved for the device's assigned PM groups — Pending is by design there, not stuck.
`installationState`	InstallationState (enum: Installed, Uninstalled, NotInstalled, None)	Yes	Installation state on the computer.
`desiredMode`	DistributionCommands	Yes	Desired distribution mode.
`currentMode`	DistributionCommands	Yes	Current distribution mode.
`installTime`	string (date-time), nullable	Yes	<inheritdoc />
`errorText`	string, nullable	Yes	<inheritdoc />
`setupErrorLogEntries`	array of SetupErrorLogEntry, nullable	No	The most recent entries from the client's SetupError log (client_id/errorlog columns in SetupErrorLog), for failed deployments only. These are NOT matched to this specific package — the log is an accumulated, client-wide string covering all packages, and no reliable per-package correlation is currently possible (see PBI #585668). Treat as general diagnostic context, not a package-specific root cause. Null for successful deployments.

GET /api/computer/{id}/patch-status

Returns missing-patch counts and the date of the last patch scan.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).

Responses

Status	Description	Schema
`200`	Patch status; all-null counts/dates when no patch scan has been collected yet.	PatchStatus

Response fields (PatchStatus):

Field	Type	Required	Description
`clientId`	integer (int32)	Yes	The Empirum client ID.
`patchScanDate`	string (date-time), nullable	Yes	UTC timestamp of the last patch scan.
`patchDefinitionDate`	string (date-time), nullable	Yes	Date of the patch definition file used for the scan.
`definitionVersion`	string, nullable	Yes	Version string of the patch definition file.
`missingSecurityPatches`	integer (int32), nullable	Yes	Number of missing patches of type SecurityPatch (patchType = 1).
`missingNonSecurityPatches`	integer (int32), nullable	Yes	Number of missing patches of type SecurityTool (patchType = 4) and NonSecurityPatch (patchType = 8) combined.
`missingServicePacks`	integer (int32), nullable	Yes	Number of missing service packs.
`hasSecurityRisks`	boolean, nullable	Yes	True if any security risk was detected during the last scan.

POST /api/computer/{id}/patches-search

Searches the detailed patch list for a computer with optional filtering and pagination.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Empirum client_id of the target computer.
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Request body (optional, application/json, schema PatchDetailFilter)

Field	Type	Required	Description
`scanStatus`	string, nullable	No	Patch scan status.
`vendorSeverity`	string, nullable	No	Severity as rated by the vendor.
`patchType`	PatchType (enum: SecurityPatch, SoftwareDistribution, SecurityTool, NonSecurityPatch, CustomAction)	No	Patch type.
`productName`	string, nullable	No	Product name.
`servicePack`	string, nullable	No	Service pack.
`isAssigned`	boolean, nullable	No	`true` if assigned.
`qNumber`	string, nullable	No	Patch Q-number (KB article).
`bulletinId`	string, nullable	No	Security bulletin ID.
`releasedAfter`	string (date), nullable	No	Only patches released after this date.
`updatedAfter`	string (date), nullable	No	Only patches updated after this date.
`minCvssScore`	number (double), nullable	No	Minimum CVSS score.
`minVrrScore`	number (double), nullable	No	Minimum VRR score.

Example request body (placeholder values):

{
    "scanStatus": "string",
    "vendorSeverity": "string",
    "patchType": "SecurityPatch",
    "productName": "string",
    "servicePack": "string",
    "isAssigned": false,
    "qNumber": "string",
    "bulletinId": "string",
    "releasedAfter": "2026-01-01",
    "updatedAfter": "2026-01-01",
    "minCvssScore": 0.0,
    "minVrrScore": 0.0
}

Responses

Status	Description	Schema
`200`	Paged list of patch details (empty when no patch scan has been collected yet).	PagedResultOfPatchDetail

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`scanStatus`	string, nullable	Yes	Patch scan status.
`qNumber`	string, nullable	Yes	Patch Q-number (KB article).
`bulletinId`	string, nullable	Yes	Security bulletin ID.
`bulletinTitle`	string, nullable	Yes	Security bulletin title.
`vendorInformationPage`	string, nullable	Yes	URL of the vendor information page.
`patchName`	string, nullable	Yes	Patch name.
`vendorSeverity`	string, nullable	Yes	Severity as rated by the vendor.
`patchType`	PatchType (enum: SecurityPatch, SoftwareDistribution, SecurityTool, NonSecurityPatch, CustomAction)	Yes	Patch type.
`patchTypeName`	string, nullable	Yes	Name of the patch type.
`releaseDate`	string (date), nullable	Yes	Release date.
`updateDate`	string (date), nullable	Yes	Update date.
`bulletinReviseDate`	string (date), nullable	Yes	Revision date of the bulletin.
`cvssScore`	number (double), nullable	Yes	CVSS score.
`vrrScore`	number (double), nullable	Yes	Vulnerability Risk Rating (VRR) score.
`uninstallable`	boolean, nullable	Yes	`true` if the patch can be uninstalled.
`language`	string, nullable	Yes	Language.
`productName`	string, nullable	Yes	Product name.
`servicePack`	string, nullable	Yes	Service pack.
`patchStatus`	string, nullable	Yes	Patch status.
`supersededBy`	string, nullable	Yes	Patch that supersedes this patch.
`isAssigned`	boolean, nullable	Yes	`true` if assigned.
`installedDate`	string (date-time), nullable	Yes	Installation date.
`installedBy`	string, nullable	Yes	Installed by.
`reason`	string, nullable	Yes	Reason.
`patchId`	integer (int32)	Yes	Patch ID.
`patchUid`	string (uuid)	Yes	Unique patch identifier.

GET /api/computer/{id}/setup-error-log

Returns cumulative setup.inf error output from failed software deployments.

Source: SetupErrorLog.errorlog — a single, accumulated, client-wide text log of setup.inf error output. Can contain additional detail not present in distribution-history (raw setup script error text vs. result codes). Entries are NOT scoped to a specific package (see software-deployment's setupErrorLogEntries for the same caveat). Ordered newest first.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	Paged list of parsed setup error log entries (empty when no SetupError log exists).	PagedResultOfSetupErrorLogEntry

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`timestamp`	string (date-time), nullable	Yes	Timestamp of the log entry, parsed from the SetupError log.
`productName`	string, nullable	Yes	Product name as recorded by the setup, e.g. "Empirum Subdepot".
`version`	string, nullable	Yes	Product version as recorded by the setup.
`revision`	string, nullable	Yes	Product revision as recorded by the setup.
`section`	string, nullable	Yes	Setup script section in which the error occurred.
`line`	integer (int32), nullable	Yes	Line number within the section.
`errorMessage`	string, nullable	Yes	Human-readable error message.

GET /api/computer/{id}/distribution-history

Returns the most recent software distribution events for the device from the Empirum agent status-message log (ArchiveDistJobs).

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfDistributionEvent

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`packageName`	string, nullable	Yes	Package name.
`version`	string, nullable	Yes	Version.
`result`	string, nullable	Yes	Result.
`classification`	string, nullable	Yes	Patch classification.
`logDateUtc`	string (date-time), nullable	Yes	Log entry time (UTC).
`kbNumber`	string, nullable	Yes	KB article number.
`installMode`	string, nullable	Yes	Installation mode.
`info`	string, nullable	Yes

GET /api/computer/{id}/inventory/installed-software

Returns the software inventory detected during the last Empirum scan.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	Paged list of installed software (empty when no inventory scan has been collected yet).	PagedResultOfInstalledSoftware

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`productName`	string	Yes	Product name.
`version`	string, nullable	Yes	Version.
`revision`	string, nullable	Yes	Package revision.
`developer`	string, nullable	Yes	Developer or vendor.
`installDate`	string (date-time), nullable	Yes	Installation date.
`msiGuid`	string, nullable	Yes	MSI product code.

GET /api/computer/{id}/inventory/services

Returns Windows services on an endpoint, optionally filtered by status or name.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).
`status`	query	string	No	Filter by status.
`nameContains`	query	string	No	Filter by a substring of the name.

Responses

Status	Description	Schema
`200`	OK	PagedResultOfWindowsService

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`shortName`	string, nullable	Yes	Short name.
`displayName`	string, nullable	Yes	Display name.
`status`	string, nullable	Yes	Status.
`startMode`	string, nullable	Yes	Start mode of the service.
`runAsUser`	string, nullable	Yes	Account the service runs as.

GET /api/computer/{id}/inventory/disks

Returns disk drive capacity and free-space data from the last inventory scan.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfDiskDrive

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`volume`	string	Yes	Drive or volume.
`driveTypeCode`	integer (int32)	Yes	Drive type code.
`totalSpaceGb`	number (double), nullable	Yes	Total size in GB.
`freeSpaceGb`	number (double), nullable	Yes	Free space in GB.
`usedPercent`	number (double), nullable	Yes	Used space in percent.
`label`	string, nullable	Yes	Label.
`bitlockerStatus`	BitlockerState (enum: Encrypted, Unencrypted, NotAvailable)	Yes	BitLocker status.
`bitlockerKeyProtectors`	string, nullable	Yes	BitLocker key protectors.

GET /api/computer/{id}/inventory/batteries

Returns battery details (status, capacity, health/wear) from the last inventory scan.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).

Responses

Status	Description	Schema
`200`	OK	array of Battery

Response fields (Battery):

Field	Type	Required	Description
`name`	string, nullable	Yes	Battery name/model as reported by WMI.
`chemistry`	string, nullable	Yes	Battery chemistry (e.g. "Lithium Ion").
`deviceId`	string, nullable	Yes	WMI device identifier.
`batteryStatus`	string, nullable	Yes	Current battery status as reported by WMI.
`designedCapacityMwh`	integer (int32), nullable	Yes	Designed capacity in mWh.
`fullChargedCapacityMwh`	integer (int32), nullable	Yes	Capacity in mWh when fully charged (degrades with wear).
`remainingCapacityPercent`	integer (int32), nullable	Yes	Wear level as computed by the inventory agent: full-charge capacity as a percentage of design capacity — NOT the current charge level (the agent stores FullChargedCapacity*100/DesignedCapacity in this column, ScanWinFunction.cpp). Same measure as double? Battery.HealthPercent, which is computed server-side with one decimal and should be preferred.
`healthPercent`	number (double), nullable	Yes	Battery health: full-charge capacity as a percentage of designed capacity (100 = no wear). Null when either capacity is missing or zero.

GET /api/computer/{id}/inventory/network-adapters

Returns network adapter configuration (IP, MAC, DNS, DHCP) from the last inventory scan.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfNetworkAdapter

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`serviceName`	string, nullable	Yes	Service name.
`description`	string, nullable	Yes	Description of the network adapter.
`ipAddress`	string, nullable	Yes	IP address.
`macAddress`	string, nullable	Yes	MAC address.
`subnetMask`	string, nullable	Yes	Subnet mask.
`defaultGateway`	string, nullable	Yes	Default gateway.
`dnsServer`	string, nullable	Yes	DNS server.
`isDhcp`	boolean	Yes	`true` if the address is assigned by DHCP.
`connectionType`	string, nullable	Yes	Connection type.

GET /api/computer/{id}/inventory/printers

Returns installed printers (WMI-based: name, port, driver, share, resolution) from the last inventory scan.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfPrinter

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`name`	string, nullable	Yes	Printer name as reported by WMI.
`port`	string, nullable	Yes	Port the printer is attached to (e.g. "USB001", "IP_192.168.1.10").
`shareName`	string, nullable	Yes	Network share name, if the printer is shared.
`driverName`	string, nullable	Yes	Installed printer driver name.
`driverVersion`	string, nullable	Yes	Installed printer driver version.
`comment`	string, nullable	Yes	Printer comment/description as configured on the device.
`isNetworkPrinter`	boolean	Yes	True if the printer is a network printer (WMIPrinter.NetworkPrinter = 1).
`isDefault`	boolean	Yes	True if this is the default printer (WMIPrinter.DefaultPrinter = 1).
`caption`	string, nullable	Yes	Printer caption as reported by WMI.
`capabilityDescriptions`	string, nullable	Yes	Printer capability descriptions as reported by WMI.
`horizontalResolution`	integer (int32), nullable	Yes	Horizontal print resolution in DPI.
`verticalResolution`	integer (int32), nullable	Yes	Vertical print resolution in DPI.

GET /api/computer/{id}/inventory/bios

Returns BIOS details (manufacturer, versions, serial number, UUID) from the last inventory scan.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).

Responses

Status	Description	Schema
`200`	OK	Bios

Response fields (Bios):

Field	Type	Required	Description
`caption`	string, nullable	Yes	BIOS caption as reported by WMI (Win32_BIOS.Caption).
`manufacturer`	string, nullable	Yes	BIOS manufacturer (e.g. "LENOVO", "Dell Inc.").
`smBiosVersion`	string, nullable	Yes	SMBIOS BIOS version string (Win32_BIOS.SMBIOSBIOSVersion).
`serialNumber`	string, nullable	Yes	Device serial number as reported by the BIOS.
`version`	string, nullable	Yes	BIOS version string (Win32_BIOS.Version).
`uuid`	string, nullable	Yes	Hardware UUID as reported by the BIOS/SMBIOS.

GET /api/computer/{id}/inventory/computer-system

Returns WMI ComputerSystem data (manufacturer, model) from the last inventory scan.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).

Responses

Status	Description	Schema
`200`	OK	ComputerSystem

Response fields (ComputerSystem):

Field	Type	Required	Description
`manufacturer`	string, nullable	Yes	System manufacturer (Win32_ComputerSystem.Manufacturer). Same source data as system-info's manufacturer (InvComputer.DeviceDeveloper).
`model`	string, nullable	Yes	System model (Win32_ComputerSystem.Model). Same source data as system-info's model (InvComputer.DeviceModel).

GET /api/computer/{id}/inventory/video-controllers

Returns video controllers (GPU name, RAM, video mode) from the last inventory scan.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfVideoController

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`name`	string, nullable	Yes	Video controller name (e.g. "NVIDIA GeForce RTX 3060").
`adapterCompatibility`	string, nullable	Yes	Adapter vendor/compatibility string.
`adapterRam`	string, nullable	Yes	Adapter RAM as reported by the inventory scan (raw string, typically bytes).
`videoProcessor`	string, nullable	Yes	Video processor/chip description.
`videoModeDescription`	string, nullable	Yes	Current video mode (resolution and color depth).
`currentRefreshRate`	string, nullable	Yes	Current refresh rate as reported by the inventory scan (raw string, Hz).

GET /api/computer/{id}/inventory/monitors

Returns attached monitors (EDID name, serial, size, resolution) from the last inventory scan.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfDesktopMonitor

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`caption`	string, nullable	Yes	Monitor caption as reported by WMI.
`manufacturer`	string, nullable	Yes	Monitor manufacturer as reported by WMI.
`monitorType`	string, nullable	Yes	Monitor type/model description.
`monitorName`	string, nullable	Yes	Monitor name from the EDID data.
`serialNumber`	string, nullable	Yes	Monitor serial number from the EDID data.
`vendorId`	string, nullable	Yes	Three-letter EDID vendor id (e.g. "LEN", "DEL").
`monitorSize`	string, nullable	Yes	Diagonal size from the EDID data (e.g. "27").
`screenWidth`	integer (int32), nullable	Yes	Horizontal resolution in pixels.
`screenHeight`	integer (int32), nullable	Yes	Vertical resolution in pixels.
`pixelsPerXLogicalInch`	integer (int32), nullable	Yes	Horizontal pixel density.
`pixelsPerYLogicalInch`	integer (int32), nullable	Yes	Vertical pixel density.
`manufacturingYear`	integer (int32), nullable	Yes	Manufacturing year from the EDID data; null when not reported (stored 0).
`manufacturingWeek`	integer (int32), nullable	Yes	Manufacturing week from the EDID data; null when not reported (stored 0).

GET /api/computer/{id}/inventory/processors

Returns processors (name, manufacturer, core/logical-processor counts, clock speeds) from the last inventory scan.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfProcessor

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`name`	string, nullable	Yes	Processor name (e.g. "Intel(R) Core(TM) i7-1185G7").
`manufacturer`	string, nullable	Yes	Processor manufacturer (e.g. "GenuineIntel").
`processorId`	string, nullable	Yes	Processor identifier string (Win32_Processor.ProcessorId).
`numberOfCores`	integer (int32), nullable	Yes	Physical core count; null on inventories older than the column.
`numberOfLogicalProcessors`	integer (int32), nullable	Yes	Logical processor count; null on inventories older than the column.
`maxClockSpeedMhz`	integer (int32), nullable	Yes	Maximum clock speed in MHz.
`currentClockSpeedMhz`	integer (int32), nullable	Yes	Clock speed in MHz at scan time.

GET /api/computer/{id}/inventory

Returns the aggregated inventory picture of one computer in a single call: core record, system info, BIOS, WMI ComputerSystem, disks, network adapters, batteries, printers, video controllers, monitors, and processors.

Inventory only — health, security posture, and patch status stay on their dedicated endpoints. List sections are unpaged (capped at 500 rows each). Installed software and services are not included — use their dedicated endpoints.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).

Responses

Status	Description	Schema
`200`	OK	ComputerInventory

Response fields (ComputerInventory):

Aggregated one-call inventory picture of a computer (PBI 593632): core record, system info, and the WMI/inventory hardware sections. Shared by GET /api/computer/{id}/inventory and the get_empirum_computer_inventory MCP tool. Deliberately inventory-only — health, security posture, and patch status live on their own endpoints (and the get_empirum_computer_status MCP tool). List sections are unpaged (capped at int PagingParameters.MaxTop rows each); installed software and services stay on their own endpoints (large payloads).

Field	Type	Required	Description
`computer`	Computer	Yes	Core computer record (Clients row).
`systemInfo`	SystemInfo	Yes	System information.
`bios`	Bios	Yes	BIOS information.
`computerSystem`	ComputerSystem	Yes	Computer system information.
`disks`	array of DiskDrive	Yes	Fixed-disk capacity and BitLocker status.
`networkAdapters`	array of NetworkAdapter	Yes	Network adapter configuration.
`batteries`	array of Battery	Yes	Battery status and health.
`printers`	array of Printer	Yes	Installed printers (WMI).
`videoControllers`	array of VideoController	Yes	Video controllers (GPU).
`monitors`	array of DesktopMonitor	Yes	Attached monitors (EDID data).
`processors`	array of Processor	Yes	Processors incl. core/logical-processor counts.

POST /api/computer/{id}/software-reinstall

Triggers an enforced reinstall of a package via its existing tree assignment.

Finds the existing (direct or inherited) tree assignment of the package for this computer, creates a reinstall group under that assignment point, and triggers an enforced reinstall. Fails if the package is not currently assigned to the computer anywhere in the tree, or if a reinstall is already pending for this computer+package.

Required role: reinstall.execute

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).

Request body (required, application/json, schema ReinstallRequest)

Field	Type	Required	Description
`packageId`	string (uuid)	Yes	Software package ID (GUID).

Example request body (placeholder values):

{
    "packageId": "00000000-0000-0000-0000-000000000000"
}

Responses

Status	Description	Schema
`200`	OK	ReinstallTriggered

Response fields (ReinstallTriggered):

Field	Type	Required	Description
`reinstallGroupId`	string (uuid)	Yes	ID of the reinstall group.
`parentGroupId`	string (uuid)	Yes	Parent group ID (GUID).
`parentGroupName`	string	Yes	Parent group name.
`softwareId`	string (uuid)	Yes	Software package ID (GUID).
`softwareName`	string, nullable	Yes	Software name.
`requestedAtUtc`	string (date-time), nullable	Yes	Time of the request (UTC).

GET /api/computer/{id}/software-reinstall

Lists the currently existing reinstall groups for this computer.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`packageId`	query	string (uuid)	No	Software package ID (GUID).
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfReinstallGroup

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`reinstallGroupId`	string (uuid)	Yes	ID of the reinstall group.
`parentGroupId`	string (uuid)	Yes	Parent group ID (GUID).
`parentGroupName`	string	Yes	Parent group name.
`softwareId`	string (uuid)	Yes	Software package ID (GUID).
`softwareName`	string, nullable	Yes	Software name.
`requestedAtUtc`	string (date-time), nullable	Yes	Time of the request (UTC).

DELETE /api/computer/{id}/software-reinstall

Cancels the given pending reinstall for this computer by removing the associated reinstall group.

Required role: reinstall.execute

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`reinstallGroupId`	query	string (uuid)	No	ID of the pending reinstall group.

Responses

Status	Description	Schema
`200`	OK	CancelledReinstallGroup

Response fields (CancelledReinstallGroup):

Field	Type	Required	Description
`reinstallGroupId`	string (uuid)	Yes	ID of the reinstall group.
`parentGroupId`	string (uuid)	Yes	Parent group ID (GUID).
`parentGroupName`	string	Yes	Parent group name.

POST /api/computer/{id}/software-uninstall

Triggers the uninstallation of an installed, assigned package on this computer.

EMC-console-equivalent semantics: sets the distribution mode of the package's nearest (direct or inherited) tree assignment to Uninstall and activates the computer — the agent removes the software at its next contact. The assignment itself is KEPT (this is what distinguishes uninstall from removing the assignment, which only stops managing the package and uninstalls nothing). The uninstall flag is set on the WHOLE assignment group: every computer in that group uninstalls the package (deliberate EMC semantics). Progress is observable via GET .../software-deployment (desiredMode Uninstall, installationState transitions to Uninstalled). Returns machine-readable 409 codes: PackageNotAssigned, PackageNotInstalled, UninstallAlreadyPending.

Required role: activation.execute

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).

Request body (required, application/json, schema UninstallRequest)

Field	Type	Required	Description
`packageId`	string (uuid)	Yes	Software package ID (GUID).

Example request body (placeholder values):

{
    "packageId": "00000000-0000-0000-0000-000000000000"
}

Responses

Status	Description	Schema
`200`	OK	Not described in the specification
`409`	Conflict	SoftwareUninstallConflict

GET /api/computer/{id}/pm-groups

Returns the Patch Management groups that apply to this computer through its group memberships.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfComputerPmGroup

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

A PM group that applies to a computer via its group memberships, resolved by EMC's own dbo.PM_getPMGroupsForComputer.

Field	Type	Required	Description
`treeId`	string (uuid)	Yes	Group tree node ID.
`pmGroupId`	integer (int32)	Yes	PM group ID.
`pmGroupName`	string	Yes	PM group name.
`category`	PmGroupCategory (enum: Patch, ServicePack)	Yes	Category.
`isTestAssignment`	boolean	Yes	`true` if this is a test assignment.
`tier`	integer (int32)	Yes	Tier.

POST /api/computer/{id}/rescan

Forces a fresh inventory or patch scan on this computer.

Triggers an enforced reinstall of the assigned Empirum scan package; the agent runs the scan at its next contact. Idempotent: if a reinstall of the scan package is already pending, the existing group is returned with alreadyPending=true. Returns 409 with code ScanPackageNotAssigned when no scan package of the requested type is assigned to the computer anywhere in its tree. A Patch rescan is also the trigger for patch remediation: when the scan finds missing patches approved for the device's PM groups, it flags the device (PatchesMissing registry value) and the assigned Patch-Management Fix package installs them automatically at the next agent contact — no separate deployment call is needed.

Required role: scan.execute

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).

Request body (required, application/json, schema ScanRequest)

Field	Type	Required	Description
`scanType`	ScanType (enum: Inventory, Patch)	Yes	Scan type.

Example request body (placeholder values):

{
    "scanType": "Inventory"
}

Responses

Status	Description	Schema
`200`	OK	Not described in the specification
`409`	Conflict	ScanPackageNotAssigned

POST /api/computer/{id}/reboot

Flags this computer to reboot at the UEM agent's next polling interval (Empirum SRL — Silent Reboot Logic).

Required role: reboot.execute

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).

Request body (optional, application/json, schema RebootRequest)

Optional grace-period settings for a requested reboot. Defaults: force at the next agent poll (timeoutMinutes = -1), remind a logged-on user every 10 minutes.

Field	Type	Required	Description
`timeoutMinutes`	integer (int32), nullable	Yes	Minutes the agent gives a logged-on user before forcing the reboot; -1 forces it immediately at the next poll.
`reminderMinutes`	integer (int32), nullable	Yes	Minutes between reminder prompts while the timeout runs.

Example request body (placeholder values):

{
    "timeoutMinutes": 0,
    "reminderMinutes": 0
}

Responses

Status	Description	Schema
`200`	OK	Not described in the specification
`409`	Conflict	ComputerNotGroupAssigned

POST /api/computer/{id}/activation

Activates this computer for software deployment or PXE boot.

Required role: activation.execute

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).

Request body (required, application/json, schema ComputerActivationRequest)

Request body for POST /api/computer/{id}/activation. At least one of software/pxe/pull must be true. wol schedules a Wake-on-LAN at the given time (UTC); wolNow: true sends it at request time (the EMC console's "Wake now" checkbox) — the two are mutually exclusive. A WOL always rides an activation (EMC rule), so "wake this computer" = { "software": true, "wolNow": true }. When srl is present without a WOL, the WOL time defaults to "now" (execute at the next agent poll) — the legacy SOAP API silently drops SRL without WOL, this API does not. global (default true, the EMC console's Global checkbox) applies the activation to ALL of the computer's assignment groups; false targets only its resolved membership node.

Field	Type	Required	Description
`software`	boolean, nullable	Yes	Software deployment activation flag.
`pxe`	boolean, nullable	Yes	PXE boot activation flag.
`pull`	boolean, nullable	Yes	Pull distribution activation flag.
`wol`	string (date-time), nullable	Yes	Scheduled Wake-on-LAN time (UTC).
`srl`	SrlSettings	Yes	Silent Reboot Logic (SRL) setting.
`global`	boolean, nullable	Yes	Global activation flag.
`wolNow`	boolean, nullable	No	Send Wake-on-LAN immediately.

Example request body (placeholder values):

{
    "software": false,
    "pxe": false,
    "pull": false,
    "wol": "2026-01-01T00:00:00Z",
    "srl": {
        "action": "Shutdown",
        "timeoutMinutes": 0,
        "reminderMinutes": 0
    },
    "global": false,
    "wolNow": false
}

Responses

Status	Description	Schema
`200`	OK	Not described in the specification
`409`	Conflict	NoPxeBootImageAssigned

DELETE /api/computer/{id}/activation

Deactivates this computer.

Required role: activation.execute

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`software`	query	boolean	No	Activate or filter software deployment.
`pxe`	query	boolean	No	Activate or filter PXE boot.
`pull`	query	boolean	No	Activate or filter pull distribution.
`global`	query	boolean	No	Global activation flag.
`uninstall`	query	boolean	No	Uninstall distribution option.

Responses

Status	Description	Schema
`200`	OK	Not described in the specification
`409`	Conflict	ComputerNotGroupAssigned

Deployment Groups

Deployment groups and their membership, assignments (packages, PXE boot images, OS image SKUs, Agent Templates, Language Packs, Variable Configurations, Software Classes), distribution options, depot servers, variables and activation.

Method	Path	Summary
GET	`/api/group`	Returns a paged list of Empirum deployment groups, optionally filtered by type and name.
POST	`/api/group`	Creates a deployment group.
GET	`/api/group/{id}`	Returns a single Empirum deployment group by its GUID.
DELETE	`/api/group/{id}`	Deletes a deployment group.
PATCH	`/api/group/{id}`	Partially updates the group's own properties — name and/or description.
GET	`/api/group/{id}/all-assignments`	Returns a flat summary of everything on the group — packages, agent template, OS Language Packs, Variable Configurations, OS Image SKU, PXE boot image, and computer members. No nested details (no variables, no SKU list); each item carries enough id fields to look the object up via its own dedicated endpoint (Computer's intId is the client id, for GET /api/computer/{id}). Direct assignments only, same scope as GET .../computers without includeDescendants — computer membership always stays direct-only regardless of includeInherited.
GET	`/api/group/{id}/computers`	Returns a paged list of computers that are members of the group.
POST	`/api/group/{id}/computers`	Assigns one or more computers to the group.
DELETE	`/api/group/{id}/computers`	Removes one or more computers from the group.
GET	`/api/group/{id}/packages`	Returns a paged list of packages assigned to the group.
POST	`/api/group/{id}/packages`	Assigns a software package to the group.
GET	`/api/group/{id}/distribution-options`	Returns the effective distribution options for the group, or for one package's assignment to it.
PUT	`/api/group/{id}/distribution-options`	Sets the distribution options for the group, or — with `packageId` — for one package's assignment to it (full replace — absent optional fields clear the stored values). Mirrors EMC's distribution-options dialog at group / assignment level; changes take effect for members on their next activation (no auto-activation — use the activation endpoint). Setting `Uninstall` makes every member computer of the group (and its subgroups) uninstall the package — or, at group level, every package assigned to the group — at its next activation.
GET	`/api/group/{id}/depot-servers`	Returns the group's directly-assigned depot-server failover list, ordered by priority.
PUT	`/api/group/{id}/depot-servers`	Replaces the group's entire ordered depot-server list (EMC group properties, Empirum-server tab).
DELETE	`/api/group/{id}/packages/{packageId}`	Removes a software package assignment from the group.
POST	`/api/group/{id}/pxe-bootimage`	Assigns a PXE boot image to the group. Always single-assign: a group has at most one active PXE image.
GET	`/api/group/{id}/pxe-bootimage`	Returns the PXE boot image currently assigned to the group, if any. Always single-assign per group: a group has at most one active PXE boot image.
DELETE	`/api/group/{id}/pxe-bootimage/{pxeId}`	Removes the PXE boot image assignment from the group.
POST	`/api/group/{id}/os-image-sku`	Assigns an OS installation image SKU to the group. Always single-assign: a group has at most one active SKU. The package itself (Software.Type = OSInstallationImage) is never directly assignable — find the skuId via GET /api/operating-system-imports (SKUs nested per package).
GET	`/api/group/{id}/os-image-sku`	Returns the OS image SKU currently assigned to the group, if any. Always single-assign per group: a group has at most one active SKU.
DELETE	`/api/group/{id}/os-image-sku/{skuId}`	Removes the OS installation image SKU assignment from the group.
GET	`/api/group/{id}/agent-template`	Returns the Agent Template currently assigned to the group, if any. Always single-assign per group: a group has at most one active Agent Template.
POST	`/api/group/{id}/agent-template`	Assigns an Agent Template to the group. Always single-assign: a group has at most one active Agent Template.
DELETE	`/api/group/{id}/agent-template/{packageId}`	Removes the Agent Template assignment from the group.
GET	`/api/group/{id}/language-pack-imports`	Returns the OS Language Packs currently assigned to the group. Multi-assign, unlike Agent Template — a group can have several.
POST	`/api/group/{id}/language-pack-imports`	Assigns an OS Language Pack to the group. Multi-assign, unlike Agent Template.
DELETE	`/api/group/{id}/language-pack-imports/{packageId}`	Removes an OS Language Pack assignment from the group.
GET	`/api/group/{id}/variable-configurations`	Returns the Variable Configurations currently assigned to the group. Multi-assign, like OS Language Pack.
POST	`/api/group/{id}/variable-configurations`	Assigns a Variable Configuration to the group. Multi-assign, like OS Language Pack.
DELETE	`/api/group/{id}/variable-configurations/{configId}`	Removes a Variable Configuration assignment from the group.
GET	`/api/group/{id}/variables`	Lists this group's directly-assigned variable value(s).
POST	`/api/group/{id}/variables/search`	Resolves a single group variable's value, with optional ancestor inheritance resolution. Unlike computer variables, a group has no "own computer value" tier.
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.
GET	`/api/group/{id}/variables/{varId}/collection`	Lists this group's direct entries (bundles) for a collection variable. No ancestor inheritance.
POST	`/api/group/{id}/variables/{varId}/collection`	Adds one new entry (bundle) to a collection variable on this group.
PATCH	`/api/group/{id}/variables/{varId}/collection/{collectionId}`	Partially updates one existing collection entry (bundle) on this group.
DELETE	`/api/group/{id}/variables/{varId}/collection/{collectionId}`	Deletes an entire variable collection entry (all its child values).
GET	`/api/group/{id}/software-classes`	Returns the Software Classes currently assigned to the group. Multi-assign, like OS Language Pack.
POST	`/api/group/{id}/software-classes`	Assigns a Software Class to the group. Multi-assign, like OS Language Pack.
DELETE	`/api/group/{id}/software-classes/{classId}`	Removes a Software Class assignment from the group.
POST	`/api/group/{id}/activation`	Activates this group, cascading over its subtree's computers, users, and subgroups.
DELETE	`/api/group/{id}/activation`	Deactivates this group, clearing the requested activation bits across the subtree.

GET /api/group

Returns a paged list of Empirum deployment groups, optionally filtered by type and name.

Required role: group.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).
`type`	query	GroupType	No	Filter by group type: ConfigurationGroups or AssignmentGroups (legacy Configuration/Assignment also accepted). Omit for all.
`nameContains`	query	string	No	Only groups whose name contains this substring.

Responses

Status	Description	Schema
`200`	OK	PagedResultOfGroup

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`id`	string (uuid)	Yes	ID of the group.
`name`	string	Yes	Name of the group.
`assignedToTree`	string	Yes	Tree the group is assigned to.
`parentId`	string (uuid), nullable	Yes	Parent group ID (GUID).
`description`	string, nullable	No	Description of the group.

POST /api/group

Creates a deployment group.

Required role: group.write

Request body (required, application/json, schema CreateGroupRequest)

Request body for creating a deployment group. ParentId is mandatory — root-level creates are not supported (mirrors the legacy SOAP API).

Field	Type	Required	Description
`name`	string	Yes	Name of the group.
`type`	GroupType	Yes	Type of the group.
`parentId`	string (uuid)	Yes	Parent group ID (GUID).
`description`	string, nullable	No	Description of the group.

Example request body (placeholder values):

{
    "name": "string",
    "type": {},
    "parentId": "00000000-0000-0000-0000-000000000000",
    "description": "string"
}

Responses

Status	Description	Schema
`201`	The created group.	Group
`400`	Invalid name or unknown group type.	ProblemDetails
`404`	Typed body: `ParentNotFound` — no group with that id in the target tree.	GroupMembershipNotFound
`409`	Typed body: `DuplicateName` (same name under the same parent) or `ParentSpecialGroup` (parent is a Reinstall/EOL/Restore group).	GroupCreateConflict

Response fields (Group):

Field	Type	Required	Description
`id`	string (uuid)	Yes
`name`	string	Yes
`assignedToTree`	string	Yes	Tree the group is assigned to.
`parentId`	string (uuid), nullable	Yes	Parent group ID (GUID).
`description`	string, nullable	No

GET /api/group/{id}

Returns a single Empirum deployment group by its GUID.

Required role: group.read

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Deployment group ID (GUID).

Responses

Status	Description	Schema
`200`	OK	Group

Response fields (Group):

Field	Type	Required	Description
`id`	string (uuid)	Yes
`name`	string	Yes
`assignedToTree`	string	Yes	Tree the group is assigned to.
`parentId`	string (uuid), nullable	Yes	Parent group ID (GUID).
`description`	string, nullable	No

DELETE /api/group/{id}

Deletes a deployment group.

Required role: group.write

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.
`force`	query	boolean	No	Required `true` to delete a group whose subtree still contains computers or users.

Responses

Status	Description	Schema
`204`	Deleted (including the whole subtree).	–
`404`	Typed body: `GroupNotFound`.	GroupMembershipNotFound
`409`	Typed body: `SystemGroup`, `NotDeletableTree` (not a computer/assignment tree group), `SpecialGroup` (Reinstall/EOL/Restore), or `NotEmpty` (retry with `force=true`).	GroupDeleteConflict

PATCH /api/group/{id}

Partially updates the group's own properties — name and/or description.

An omitted/null field keeps the stored value; an empty-string description clears it. The name cannot be cleared. Parent, tree and type are not updatable.

Required role: group.write

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.

Request body (required, application/json, schema GroupPatchRequest)

Body for PATCH /api/group/{id} — a partial update of the group's own properties (TreeDefinition.Name / GroupDescription): an omitted/null field keeps the stored value, an empty-string description clears it (SQL NULL). Name cannot be cleared — an empty name fails bool GroupWriteRules.ValidateName(string? name, out string error). Parent, tree and object type are deliberately not updatable (the legacy SOAP Group.Update ignores them too). Unknown JSON properties are rejected (400 naming the property) — on a PATCH a typo'd field would otherwise return 200 while silently not updating anything.

Field	Type	Required	Description
`name`	string, nullable	No	Name of the group.
`description`	string, nullable	No	Description of the group.

Example request body (placeholder values):

{
    "name": "string",
    "description": "string"
}

Responses

Status	Description	Schema
`200`	The updated group.	Group
`400`	Invalid name/description, or an empty patch body.	ProblemDetails
`404`	Typed body: `GroupNotFound`.	GroupMembershipNotFound
`409`	Typed body: `DuplicateName` (same name under the same parent), `SystemGroup`, `NotEditableTree`, or `SpecialGroup` (Reinstall/EOL/Restore).	GroupUpdateConflict

Response fields (Group):

Field	Type	Required	Description
`id`	string (uuid)	Yes
`name`	string	Yes
`assignedToTree`	string	Yes	Tree the group is assigned to.
`parentId`	string (uuid), nullable	Yes	Parent group ID (GUID).
`description`	string, nullable	No

GET /api/group/{id}/all-assignments

Returns a flat summary of everything on the group — packages, agent template, OS Language Packs, Variable Configurations, OS Image SKU, PXE boot image, and computer members. No nested details (no variables, no SKU list); each item carries enough id fields to look the object up via its own dedicated endpoint (Computer's intId is the client id, for GET /api/computer/{id}). Direct assignments only, same scope as GET .../computers without includeDescendants — computer membership always stays direct-only regardless of includeInherited.

Required role: group.read

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.
`includeInherited`	query	boolean	No	Also include the six assignable-object types inherited from ancestor groups (an assignment on a parent group reaches this group's computers too). Computer membership is unaffected by this flag.

Responses

Status	Description	Schema
`200`	Flat list of assignment summary items (may be empty).	array of GroupAssignmentSummaryItem

Response fields (GroupAssignmentSummaryItem):

One row in the GET {id}/all-assignments summary — no nested details (no variables, no SKU list), just enough to identify the object and look it up directly via its own dedicated catalog endpoint. Id/IntId/PackageId/SkuId are mutually exclusive per Type: Package/AgentTemplate/LanguagePackImport use Id (Software.SoftwareId); VariableConfiguration, PxeBootImage, and Computer use IntId (Computer: Clients.ClientId); OsImageSku uses PackageId (its parent OperatingSystemImport, the only directly queryable catalog endpoint for it) plus SkuId for clarity.

Field	Type	Required	Description
`type`	GroupAssignmentType	Yes	Type of the group.
`id`	string (uuid), nullable	Yes	ID of the group.
`intId`	integer (int32), nullable	Yes	Integer ID.
`packageId`	string (uuid), nullable	Yes	Software package ID (GUID).
`skuId`	integer (int32), nullable	Yes	OS image SKU (edition) ID.
`name`	string	Yes	Name of the group.

GET /api/group/{id}/computers

Returns a paged list of computers that are members of the group.

Required role: group.read

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).
`includeDescendants`	query	boolean	No	Also include computers that are members of child groups anywhere below this group.

Responses

Status	Description	Schema
`200`	OK	PagedResultOfComputer

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`id`	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`hostname`	string	Yes	Hostname of the computer.
`domain`	string, nullable	Yes	Domain name.
`macAddress`	string, nullable	Yes	MAC address.
`uuid`	string (uuid)	Yes	Hardware UUID of the computer.
`lastSeenUtc`	string (date-time), nullable	Yes	Last agent contact (UTC).
`serialNumber`	string, nullable	No	Serial number.
`lastModified`	string (date-time), nullable	No	Time of the last modification (UTC).
`inventoryDate`	string (date-time), nullable	No	Date of the last inventory (UTC).
`inventoryId`	string, nullable	No	Inventory ID.
`ou`	string, nullable	No	Organizational unit (OU).
`pxeSupport`	boolean	No	`true` if the computer supports PXE boot.
`isPxeActive`	boolean	No	`true` if PXE boot is activated.

POST /api/group/{id}/computers

Assigns one or more computers to the group.

Each computer is processed independently with the single-computer rules (config-group exclusivity, special-group refusal); one failing computer does not stop the rest. AlreadyMember counts as success.

Required role: group.write

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.

Request body (required, application/json, schema BulkGroupComputersRequest)

Bulk membership request: client ids of the computers to assign to / remove from the group.

Field	Type	Required	Description
`computerIds`	array of integer (int32)	Yes	Computer IDs (Empirum `client_id`).

Example request body (placeholder values):

{
    "computerIds": [
        0
    ]
}

Responses

Status	Description	Schema
`200`	Per-computer outcomes; `succeeded`/`failed` counts.	BulkGroupComputersResult
`400`	Empty list or more than 500 ids.	ProblemDetails
`404`	Typed body: `GroupNotFound`.	GroupMembershipNotFound

Response fields (BulkGroupComputersResult):

Result of a bulk membership operation. Succeeded counts computers whose desired state now holds (including no-ops like AlreadyMember/NotMember).

Field	Type	Required	Description
`groupId`	string (uuid)	Yes	Deployment group ID (GUID).
`succeeded`	integer (int32)	Yes	Number of successful items.
`failed`	integer (int32)	Yes	Number of failed items.
`results`	array of BulkGroupComputerResult	Yes	Per-item results.

DELETE /api/group/{id}/computers

Removes one or more computers from the group.

Idempotent per computer — not-a-member counts as success.

Required role: group.write

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.
`computerIds`	query	array of integer (int32)	No	Client ids of the computers to remove, e.g. `?computerIds=4711&computerIds=4712`.

Responses

Status	Description	Schema
`200`	Per-computer outcomes; `succeeded`/`failed` counts.	BulkGroupComputersResult
`400`	Empty list or more than 500 ids.	ProblemDetails
`404`	Typed body: `GroupNotFound`.	GroupMembershipNotFound

Response fields (BulkGroupComputersResult):

Result of a bulk membership operation. Succeeded counts computers whose desired state now holds (including no-ops like AlreadyMember/NotMember).

Field	Type	Required	Description
`groupId`	string (uuid)	Yes	Deployment group ID (GUID).
`succeeded`	integer (int32)	Yes	Number of successful items.
`failed`	integer (int32)	Yes	Number of failed items.
`results`	array of BulkGroupComputerResult	Yes	Per-item results.

GET /api/group/{id}/packages

Returns a paged list of packages assigned to the group.

Required role: group.read

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).
`includeInherited`	query	boolean	No	Also include packages assigned to any ancestor group — an assignment on a parent group reaches this group's computers too.

Responses

Status	Description	Schema
`200`	OK	PagedResultOfPackage

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`id`	string (uuid)	Yes	ID of the package.
`name`	string	Yes	Name of the package.
`packageName`	string, nullable	Yes	Package name.
`type`	string, nullable	Yes	Type of the package.
`subType`	string, nullable	Yes	Subtype.
`version`	string, nullable	Yes	Version.
`author`	string, nullable	Yes	Author.
`revision`	string, nullable	Yes	Package revision.
`operational`	boolean	Yes	"Ready to Install" flag of the package.
`os`	array of string	Yes	Operating system.

POST /api/group/{id}/packages

Assigns a software package to the group.

Required role: group.write

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.

Request body (required, application/json, schema AssignGroupPackageRequest)

Field	Type	Required	Description
`packageId`	string (uuid)	Yes	Software package ID (GUID).

Example request body (placeholder values):

{
    "packageId": "00000000-0000-0000-0000-000000000000"
}

Responses

Status	Description	Schema
`200`	Already assigned — no-op success, `alreadyAssigned=true`.	GroupPackageAssignment
`201`	Assigned; body echoes the assignment.	GroupPackageAssignment
`404`	Typed body: `GroupNotFound` or `PackageNotFound`.	GroupMembershipNotFound
`409`	Typed body: `SpecialGroup`, `CoveredBySoftwareClass`, or `WrongEndpointForType` (OS Installation Image packages are not directly assignable — use POST /api/group/{id}/os-image-sku with a specific SKU id from GET /api/operating-system-imports instead; Agent Template packages use POST /api/group/{id}/agent-template instead; OS Language Pack packages use POST /api/group/{id}/language-pack-imports instead).	GroupPackageConflict

Response fields (GroupPackageAssignment):

Result of a package→group assignment. AlreadyAssigned marks the no-op case (the package was already assigned; the ChangeFlag nudge still ran, like legacy SOAP).

Field	Type	Required	Description
`groupId`	string (uuid)	Yes	Deployment group ID (GUID).
`packageId`	string (uuid)	Yes	Software package ID (GUID).
`alreadyAssigned`	boolean	Yes	`true` if the assignment already existed (no change).

GET /api/group/{id}/distribution-options

Returns the effective distribution options for the group, or for one package's assignment to it.

Required role: group.read

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.
`packageId`	query	string (uuid)	No	Scope to this package's assignment; omit for group-level options.

Responses

Status	Description	Schema
`200`	The resolved distribution options.	DistributionOptions
`404`	Group unknown (empty body), or — with a typed body — `packageId` does not exist (`PackageNotFound`) or is not assigned to the group (`PackageNotAssigned`), mirroring the legacy NOT_FOUND fault.	DistributionOptionsNotFound

Response fields (DistributionOptions):

Distribution options effective for a group (inherited from the nearest configured ancestor) or for one package's assignment to the group, as resolved by dbo.EMPfncGetSwDistCommand — the same TVF the legacy SOAP GetDistributionOptions reads.

Field	Type	Required	Description
`groupId`	string (uuid)	Yes	The group the options were resolved for.
`packageId`	string (uuid), nullable	Yes	The package whose assignment was queried; null for group-level options.
`distCommands`	integer (int32)	Yes	Raw Empirum distribution-command bitmask (see DistributionCommands).
`commands`	array of string	Yes	The bitmask decoded into flag names, e.g. ["Install", "Update"].
`scheduleString`	string	Yes	Raw Empirum schedule string (semicolon-separated, agent-interpreted); empty when no schedule is set.
`schedule`	DistributionSchedule	Yes	Schedule.
`revokeCount`	integer (int32)	Yes	How often the user may postpone the installation (0 = not postponable).
`wol`	boolean	Yes	Whether Wake-on-LAN is requested for the distribution.
`revokeDate`	string (date-time), nullable	Yes	Date until which the user may postpone; null when not set.
`optionalDate`	string (date-time), nullable	Yes	Date until which an optional package is offered; null when not set.

PUT /api/group/{id}/distribution-options

Sets the distribution options for the group, or — with packageId — for one package's assignment to it (full replace — absent optional fields clear the stored values). Mirrors EMC's distribution-options dialog at group / assignment level; changes take effect for members on their next activation (no auto-activation — use the activation endpoint). Setting Uninstall makes every member computer of the group (and its subgroups) uninstall the package — or, at group level, every package assigned to the group — at its next activation.

Required role: group.write

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.
`packageId`	query	string (uuid)	No	Scope to this package's assignment (CompGrSwProp); omit for group-level options (CompConfGrProp). Same addressing as GET.

Request body (required, application/json, schema SetDistributionOptionsRequest)

Body of PUT /api/group/{id}/distribution-options — the complete desired group-level state (full replace: absent optional fields clear the stored values, deliberately fixing the legacy SOAP writer's can't-clear behavior).

Field	Type	Required	Description
`commands`	array of string	Yes	Command flag names, e.g. ["Install","Update","Hide"]. Must contain Install/Update or Uninstall — never both families. Accepted vocabulary mirrors the legacy .NET converter: Install, Update, AlwaysEnforce, Uninstall, UserCanRevoke, Hide, Offline, IgnoreMtf, Optional.
`scheduleString`	string, nullable	No	Raw Empirum schedule string (agent-interpreted, max 129 chars); null, empty or "now" = no schedule (install immediately).
`revokeCount`	integer (int32), nullable	No	How often the user may postpone (0–999); implies UserCanRevoke.
`revokeDate`	string (date-time), nullable	No	Date until which the user may postpone (must be in the future); implies UserCanRevoke.
`optionalDate`	string (date-time), nullable	No	Date until which an optional package is offered.
`wol`	boolean	No	Request Wake-on-LAN for the distribution.

Example request body (placeholder values):

{
    "commands": [
        "string"
    ],
    "scheduleString": "string",
    "revokeCount": 0,
    "revokeDate": "2026-01-01T00:00:00Z",
    "optionalDate": "2026-01-01T00:00:00Z",
    "wol": false
}

Responses

Status	Description	Schema
`200`	The stored options, resolved via the same read as GET.	DistributionOptions
`400`	Invalid commands (must contain Install/Update or Uninstall, never both families), RevokeCount out of 0–999, RevokeDate not in the future, or ScheduleString longer than 129 characters.	ProblemDetails
`404`	Group unknown (empty body), or — with a typed body — `packageId` does not exist (`PackageNotFound`) or is not assigned to the group (`PackageNotAssigned`), mirroring GET.	DistributionOptionsNotFound

Response fields (DistributionOptions):

Field	Type	Required	Description
`groupId`	string (uuid)	Yes	The group the options were resolved for.
`packageId`	string (uuid), nullable	Yes	The package whose assignment was queried; null for group-level options.
`distCommands`	integer (int32)	Yes	Raw Empirum distribution-command bitmask (see DistributionCommands).
`commands`	array of string	Yes	The bitmask decoded into flag names, e.g. ["Install", "Update"].
`scheduleString`	string	Yes	Raw Empirum schedule string (semicolon-separated, agent-interpreted); empty when no schedule is set.
`schedule`	DistributionSchedule	Yes	Schedule.
`revokeCount`	integer (int32)	Yes	How often the user may postpone the installation (0 = not postponable).
`wol`	boolean	Yes	Whether Wake-on-LAN is requested for the distribution.
`revokeDate`	string (date-time), nullable	Yes	Date until which the user may postpone; null when not set.
`optionalDate`	string (date-time), nullable	Yes	Date until which an optional package is offered; null when not set.

GET /api/group/{id}/depot-servers

Returns the group's directly-assigned depot-server failover list, ordered by priority.

Direct assignment only — depot servers inherited from ancestor groups are not resolved. The first entry is the group's primary depot server.

Required role: group.read

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.

Responses

Status	Description	Schema
`200`	The ordered list (may be empty).	array of GroupDepotServer
`404`	Typed body: `GroupNotFound`.	GroupMembershipNotFound

Response fields (GroupDepotServer):

One depot server directly assigned to a group (GroupEmpServer row). SortOrder is the 1-based failover priority — "the group's depot server" is the SortOrder=1 entry, later entries are fallbacks. Direct assignment only; servers inherited from ancestor groups (EMC shows them greyed-out on the group's Empirum-server tab) are not resolved here.

Field	Type	Required	Description
`serverId`	integer (int32)	Yes	Depot server ID.
`name`	string	Yes	Name of the group.
`sortOrder`	integer (int32)	Yes	Position in the ordered list.

PUT /api/group/{id}/depot-servers

Replaces the group's entire ordered depot-server list (EMC group properties, Empirum-server tab).

Order is meaningful — the first entry is the primary depot server, later entries are failovers. An empty array clears the assignment. Enumerate assignable servers via GET /api/system/depot-servers. A change reactivates the group's members (new activation queue entries), exactly like saving the EMC dialog.

Required role: group.write

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.

Request body (required, application/json, schema SetGroupDepotServersRequest)

Body for PUT /api/group/{id}/depot-servers — replaces the group's entire ordered depot-server list (EMC failover chain). Order is meaningful (first entry = primary depot); an empty array clears the assignment. Every id must be a depot server (dbo.fnc_IsDepotServer = 1, i.e. a client carrying the 'Empirum Depot Server' or 'Empirum Master Server' computer role — enumerate via GET /api/system/depot-servers).

Field	Type	Required	Description
`serverIds`	array of integer (int32)	Yes	Depot server IDs in failover order.

Example request body (placeholder values):

{
    "serverIds": [
        0
    ]
}

Responses

Status	Description	Schema
`200`	The new ordered list (also returned when it was already identical).	array of GroupDepotServer
`400`	Typed body: `DuplicateServerIds`, `ServerNotFound`, or `NotDepotServer` — `serverIds` carries the offending ids.	GroupDepotServersInvalid
`404`	Typed body: `GroupNotFound`.	GroupMembershipNotFound
`409`	Typed body: `SpecialGroup` (Reinstall/EOL/Restore).	GroupDeleteConflict

Response fields (GroupDepotServer):

Field	Type	Required	Description
`serverId`	integer (int32)	Yes	Depot server ID.
`name`	string	Yes	Name of the group.
`sortOrder`	integer (int32)	Yes	Position in the ordered list.

DELETE /api/group/{id}/packages/{packageId}

Removes a software package assignment from the group.

Required role: group.write

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.
`packageId`	path	string (uuid)	Yes	Software GUID of the package to unassign.

Responses

Status	Description	Schema
`204`	Removed, or was not assigned (idempotent).	–
`404`	Typed body: `GroupNotFound`.	GroupMembershipNotFound

POST /api/group/{id}/pxe-bootimage

Assigns a PXE boot image to the group. Always single-assign: a group has at most one active PXE image.

Required role: group.write

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.

Request body (required, application/json, schema AssignGroupPxeBootImageRequest)

Field	Type	Required	Description
`pxeId`	integer (int32)	Yes	PXE boot image ID.

Example request body (placeholder values):

{
    "pxeId": 0
}

Responses

Status	Description	Schema
`200`	Already assigned — no-op success, `alreadyAssigned=true`.	GroupPxeBootImageAssignment
`201`	Assigned; body echoes the assignment.	GroupPxeBootImageAssignment
`404`	Typed body: `GroupNotFound` or `PxeBootImageNotFound`.	GroupPxeBootImageNotFound
`409`	Typed body: `SpecialGroup` or `AlreadyAssignedSingleAssign` (a different PXE image is already assigned to this group — remove it first).	GroupPxeBootImageConflict

Response fields (GroupPxeBootImageAssignment):

Result of a PXE boot image→group assignment. Always single-assign: a group has at most one active PXE image. AlreadyAssigned marks the no-op case (the same image was already assigned).

Field	Type	Required	Description
`groupId`	string (uuid)	Yes	Deployment group ID (GUID).
`pxeId`	integer (int32)	Yes	PXE boot image ID.
`alreadyAssigned`	boolean	Yes	`true` if the assignment already existed (no change).

GET /api/group/{id}/pxe-bootimage

Returns the PXE boot image currently assigned to the group, if any. Always single-assign per group: a group has at most one active PXE boot image.

Required role: group.read

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.
`includeInherited`	query	boolean	No	Also consider ancestor groups if this group has none assigned directly — the nearest ancestor's image wins.

Responses

Status	Description	Schema
`200`	The assigned PXE boot image.	PxeBootImage
`404`	Typed body: `GroupNotFound` or `NoPxeBootImageAssigned` (the group exists but has no PXE boot image assigned).	GroupPxeBootImageNotFound

Response fields (PxeBootImage):

A PXE boot image (e.g. "StdWinPE") — the assignable object for POST /api/group/{id}/pxe-bootimage. Not a Software row; catalogued in dhcp_boot_info.

Field	Type	Required	Description
`id`	integer (int32)	Yes
`name`	string	Yes
`bootFile`	string	Yes	Boot file.
`sysInfo`	integer (int32)	Yes	System information.
`archInfo`	integer (int32)	Yes	Architecture information.

DELETE /api/group/{id}/pxe-bootimage/{pxeId}

Removes the PXE boot image assignment from the group.

Required role: group.write

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.
`pxeId`	path	integer (int32)	Yes	Id of the PXE boot image to unassign.

Responses

Status	Description	Schema
`204`	Removed, or was not assigned (idempotent).	–
`404`	Typed body: `GroupNotFound`.	GroupPxeBootImageNotFound

POST /api/group/{id}/os-image-sku

Assigns an OS installation image SKU to the group. Always single-assign: a group has at most one active SKU. The package itself (Software.Type = OSInstallationImage) is never directly assignable — find the skuId via GET /api/operating-system-imports (SKUs nested per package).

Required role: group.write

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.

Request body (required, application/json, schema AssignGroupOsImageSkuRequest)

Field	Type	Required	Description
`skuId`	integer (int32)	Yes	OS image SKU (edition) ID.

Example request body (placeholder values):

{
    "skuId": 0
}

Responses

Status	Description	Schema
`200`	Already assigned — no-op success, `alreadyAssigned=true`.	GroupOsImageSkuAssignment
`201`	Assigned; body echoes the assignment.	GroupOsImageSkuAssignment
`404`	Typed body: `GroupNotFound` or `SkuNotFound`.	GroupOsImageSkuNotFound
`409`	Typed body: `SpecialGroup` or `AlreadyAssignedSingleAssign` (a different SKU is already assigned to this group — remove it first).	GroupOsImageSkuConflict

Response fields (GroupOsImageSkuAssignment):

Result of an OS-image-SKU→group assignment. Always single-assign: a group has at most one active SKU. AlreadyAssigned marks the no-op case (the same SKU was already assigned).

Field	Type	Required	Description
`groupId`	string (uuid)	Yes	Deployment group ID (GUID).
`skuId`	integer (int32)	Yes	OS image SKU (edition) ID.
`alreadyAssigned`	boolean	Yes	`true` if the assignment already existed (no change).

GET /api/group/{id}/os-image-sku

Returns the OS image SKU currently assigned to the group, if any. Always single-assign per group: a group has at most one active SKU.

Required role: group.read

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.
`includeInherited`	query	boolean	No	Also consider ancestor groups if this group has none assigned directly — the nearest ancestor's SKU wins.

Responses

Status	Description	Schema
`200`	The assigned OS image SKU with its parent image package.	GroupOsImageSku
`404`	Typed body: `GroupNotFound` or `NoOsImageSkuAssigned` (the group exists but has no OS image SKU assigned).	GroupOsImageSkuNotFound

Response fields (GroupOsImageSku):

The OS image SKU assigned to a group (GET .../os-image-sku), with its parent image package as context.

Field	Type	Required	Description
`packageId`	string (uuid)	Yes	Software package ID (GUID).
`packageName`	string	Yes	Package name.
`skuId`	integer (int32)	Yes	OS image SKU (edition) ID.
`index`	integer (int32)	Yes
`name`	string	Yes
`description`	string, nullable	Yes

DELETE /api/group/{id}/os-image-sku/{skuId}

Removes the OS installation image SKU assignment from the group.

Required role: group.write

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.
`skuId`	path	integer (int32)	Yes	Id of the SKU to unassign.

Responses

Status	Description	Schema
`204`	Removed, or was not assigned (idempotent).	–
`404`	Typed body: `GroupNotFound`.	GroupOsImageSkuNotFound

GET /api/group/{id}/agent-template

Returns the Agent Template currently assigned to the group, if any. Always single-assign per group: a group has at most one active Agent Template.

Required role: group.read

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.
`includeInherited`	query	boolean	No	Also consider ancestor groups if this group has none assigned directly — the nearest ancestor's Agent Template wins.

Responses

Status	Description	Schema
`200`	The assigned Agent Template.	AgentTemplate
`404`	Typed body: `GroupNotFound` or `NoAgentTemplateAssigned` (the group exists but has no Agent Template assigned).	GroupAgentTemplateNotFound

Response fields (AgentTemplate):

An Agent Template (Software.Type = "AgentTemplate") — the assignable object for POST /api/group/{id}/agent-template. A genuine Software row, but single-assign per group (unlike ordinary multi-assign packages) and kept off the general /packages surface. PackageName/Version/Author/Revision are deliberately omitted — live-DB verification showed they are always empty for this Software.Type, unlike ordinary packages. PollingIntervalSeconds/SuppressReboot/RemindUserOnReboot* are read from the template's AdtTemplateDetails SoftwareDepot node tree (same nodes UemAgentInfoResolver resolves per-computer); null when the template has no InventoryId or the node is missing.

Field	Type	Required	Description
`id`	string (uuid)	Yes
`name`	string	Yes
`pollingIntervalSeconds`	integer (int32), nullable	Yes	Agent polling interval in seconds.
`suppressReboot`	boolean, nullable	Yes	`true` if reboots are suppressed.
`remindUserOnReboot`	boolean, nullable	Yes	`true` if the user is reminded before a reboot.
`remindUserOnRebootIntervalMinutes`	integer (int32), nullable	Yes	Reminder interval in minutes.
`forceRebootAfterMinutes`	integer (int32), nullable	Yes	Minutes after which a reboot is forced.

POST /api/group/{id}/agent-template

Assigns an Agent Template to the group. Always single-assign: a group has at most one active Agent Template.

Required role: group.write

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.

Request body (required, application/json, schema AssignGroupAgentTemplateRequest)

Field	Type	Required	Description
`packageId`	string (uuid)	Yes	Software package ID (GUID).

Example request body (placeholder values):

{
    "packageId": "00000000-0000-0000-0000-000000000000"
}

Responses

Status	Description	Schema
`200`	Already assigned — no-op success, `alreadyAssigned=true`.	GroupAgentTemplateAssignment
`201`	Assigned; body echoes the assignment.	GroupAgentTemplateAssignment
`404`	Typed body: `GroupNotFound` or `AgentTemplateNotFound`.	GroupAgentTemplateNotFound
`409`	Typed body: `SpecialGroup`, `CoveredBySoftwareClass`, or `AlreadyAssignedSingleAssign` (a different Agent Template is already assigned to this group — remove it first).	GroupAgentTemplateConflict

Response fields (GroupAgentTemplateAssignment):

Result of an Agent Template→group assignment. Always single-assign: a group has at most one active Agent Template. AlreadyAssigned marks the no-op case (the same template was already assigned).

Field	Type	Required	Description
`groupId`	string (uuid)	Yes	Deployment group ID (GUID).
`packageId`	string (uuid)	Yes	Software package ID (GUID).
`alreadyAssigned`	boolean	Yes	`true` if the assignment already existed (no change).

DELETE /api/group/{id}/agent-template/{packageId}

Removes the Agent Template assignment from the group.

Required role: group.write

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.
`packageId`	path	string (uuid)	Yes	Software GUID of the Agent Template to unassign.

Responses

Status	Description	Schema
`204`	Removed, or was not assigned (idempotent).	–
`404`	Typed body: `GroupNotFound`.	GroupAgentTemplateNotFound

GET /api/group/{id}/language-pack-imports

Returns the OS Language Packs currently assigned to the group. Multi-assign, unlike Agent Template — a group can have several.

Required role: group.read

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).
`includeInherited`	query	boolean	No	Also include OS Language Packs assigned to any ancestor group.

Responses

Status	Description	Schema
`200`	Paged list of assigned OS Language Packs.	PagedResultOfLanguagePackImport

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

An OS Language Pack (Software.Type = "OSLanguagePack") — the assignable object for POST /api/group/{id}/language-pack-imports. A genuine Software row, multi-assign like ordinary packages, but written to the separate CompConfGrLanguagePack table (not CompConfGrSoft) and kept off the general /packages surface. PackageName/Version/Author/Revision are deliberately omitted — live-DB verification showed PackageName always duplicates Name and the others are always NULL for this Software.Type.

Field	Type	Required	Description
`id`	string (uuid)	Yes	ID of the Language Pack.
`name`	string	Yes	Name of the Language Pack.

POST /api/group/{id}/language-pack-imports

Assigns an OS Language Pack to the group. Multi-assign, unlike Agent Template.

Required role: group.write

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.

Request body (required, application/json, schema AssignGroupLanguagePackRequest)

Field	Type	Required	Description
`packageId`	string (uuid)	Yes	Software package ID (GUID).

Example request body (placeholder values):

{
    "packageId": "00000000-0000-0000-0000-000000000000"
}

Responses

Status	Description	Schema
`200`	Already assigned — no-op success, `alreadyAssigned=true`.	GroupLanguagePackAssignment
`201`	Assigned; body echoes the assignment.	GroupLanguagePackAssignment
`404`	Typed body: `GroupNotFound` or `LanguagePackNotFound`.	GroupLanguagePackNotFound
`409`	Typed body: `SpecialGroup`.	GroupLanguagePackConflict

Response fields (GroupLanguagePackAssignment):

Result of an OS Language Pack→group assignment. Multi-assign, unlike Agent Template. AlreadyAssigned marks the no-op case (the same language pack was already assigned).

Field	Type	Required	Description
`groupId`	string (uuid)	Yes	Deployment group ID (GUID).
`packageId`	string (uuid)	Yes	Software package ID (GUID).
`alreadyAssigned`	boolean	Yes	`true` if the assignment already existed (no change).

DELETE /api/group/{id}/language-pack-imports/{packageId}

Removes an OS Language Pack assignment from the group.

Required role: group.write

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.
`packageId`	path	string (uuid)	Yes	Software GUID of the OS Language Pack to unassign.

Responses

Status	Description	Schema
`204`	Removed, or was not assigned (idempotent).	–
`404`	Typed body: `GroupNotFound`.	GroupLanguagePackNotFound

GET /api/group/{id}/variable-configurations

Returns the Variable Configurations currently assigned to the group. Multi-assign, like OS Language Pack.

Required role: group.read

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).
`includeInherited`	query	boolean	No	Also include Variable Configurations assigned to any ancestor group.

Responses

Status	Description	Schema
`200`	Paged list of assigned Variable Configurations.	PagedResultOfVariableConfiguration

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

A Variable Configuration (VaPaConfigurations) — a named collection of variables that can be assigned to a group via POST /api/group/{id}/variable-configurations. Feeds into computer variable resolution (dbo.EMPfncGetVariableValueIncludingVariableConfigurations) alongside ordinary group variables. Multi-assign, like OS Language Pack.

Field	Type	Required	Description
`id`	integer (int32)	Yes	ID of the Variable Configuration.
`configGuid`	string (uuid)	Yes	Variable Configuration GUID.
`name`	string	Yes	Name of the Variable Configuration.
`description`	string, nullable	Yes	Description of the Variable Configuration.
`createdDate`	string (date-time)	Yes	Creation date.
`lastUpdated`	string (date-time)	Yes	Time of the last update (UTC).
`variables`	array of VariableConfigurationVariable	Yes	Variables.

POST /api/group/{id}/variable-configurations

Assigns a Variable Configuration to the group. Multi-assign, like OS Language Pack.

Required role: group.write

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.

Request body (required, application/json, schema AssignGroupVariableConfigurationRequest)

Field	Type	Required	Description
`configId`	integer (int32)	Yes	Variable Configuration ID.

Example request body (placeholder values):

{
    "configId": 0
}

Responses

Status	Description	Schema
`200`	Already assigned — no-op success, `alreadyAssigned=true`.	GroupVariableConfigurationAssignment
`201`	Assigned; body echoes the assignment.	GroupVariableConfigurationAssignment
`404`	Typed body: `GroupNotFound` or `VariableConfigurationNotFound`.	GroupVariableConfigurationNotFound
`409`	Typed body: `SpecialGroup`.	GroupVariableConfigurationConflict

Response fields (GroupVariableConfigurationAssignment):

Result of a Variable Configuration→group assignment. Multi-assign, like OS Language Pack. AlreadyAssigned marks the no-op case (the same configuration was already assigned).

Field	Type	Required	Description
`groupId`	string (uuid)	Yes	Deployment group ID (GUID).
`configId`	integer (int32)	Yes	Variable Configuration ID.
`alreadyAssigned`	boolean	Yes	`true` if the assignment already existed (no change).

DELETE /api/group/{id}/variable-configurations/{configId}

Removes a Variable Configuration assignment from the group.

Required role: group.write

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.
`configId`	path	integer (int32)	Yes	Id of the Variable Configuration to unassign.

Responses

Status	Description	Schema
`204`	Removed, or was not assigned (idempotent).	–
`404`	Typed body: `GroupNotFound`.	GroupVariableConfigurationNotFound

GET /api/group/{id}/variables

Lists this group's directly-assigned variable value(s).

Required role: group.read

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfVariableValue

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`varId`	integer (int32)	Yes	Variable definition ID.
`designation`	string	Yes	Designation.
`dottedName`	string	Yes	Fully qualified (dotted) variable name.
`value`	string, nullable	Yes

POST /api/group/{id}/variables/search

Resolves a single group variable's value, with optional ancestor inheritance resolution. Unlike computer variables, a group has no "own computer value" tier.

Required role: group.read

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Request body (required, application/json, schema VariableValueSearchFilter)

Filter body for POST .../variables/search — single-variable lookup with optional inheritance resolution, the computer/group-scoped counterpart to VariableDefinitionSearchFilter.

Field	Type	Required	Description
`name`	string, nullable	No	Raw designation or dotted "parent.child" name; mutually exclusive with varId.
`varId`	integer (int32), nullable	No	Variable's VarID; mutually exclusive with name.
`includeInherited`	boolean	No	False (default) returns only the direct override/value, with no fallback; true resolves the full inheritance precedence.

Example request body (placeholder values):

{
    "name": "string",
    "varId": 0,
    "includeInherited": false
}

Responses

Status	Description	Schema
`200`	OK	PagedResultOfVariableValue

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`varId`	integer (int32)	Yes	Variable definition ID.
`designation`	string	Yes	Designation.
`dottedName`	string	Yes	Fully qualified (dotted) variable name.
`value`	string, nullable	Yes

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.

Required role: group.write

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.
`varId`	path	integer (int32)	Yes	Variable's VarID (must not be a collection or UserDefined variable).

Request body (required, application/json, schema SetVariableValueRequest)

Field	Type	Required	Description
`value`	string, nullable	Yes

Example request body (placeholder values):

{
    "value": "string"
}

Responses

Status	Description	Schema
`200`	OK	VariableValue

Response fields (VariableValue):

Field	Type	Required	Description
`varId`	integer (int32)	Yes	Variable definition ID.
`designation`	string	Yes	Designation.
`dottedName`	string	Yes	Fully qualified (dotted) variable name.
`value`	string, nullable	Yes

GET /api/group/{id}/variables/{varId}/collection

Lists this group's direct entries (bundles) for a collection variable. No ancestor inheritance.

Required role: group.read

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.
`varId`	path	integer (int32)	Yes	Collection variable's VarID (DefCompPkgVar.Collection = 1).
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfVariableCollectionEntry

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`collectionId`	integer (int32)	Yes	Collection ID.
`values`	array of VariableValue	Yes

POST /api/group/{id}/variables/{varId}/collection

Adds one new entry (bundle) to a collection variable on this group.

Required role: group.write

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.
`varId`	path	integer (int32)	Yes	Collection variable's VarID.

Request body (required, application/json, schema VariableCollectionEntryRequest)

Field	Type	Required	Description
`values`	map of string to string	Yes

Example request body (placeholder values):

{
    "values": {}
}

Responses

Status	Description	Schema
`200`	OK	VariableCollectionEntry

Response fields (VariableCollectionEntry):

Field	Type	Required	Description
`collectionId`	integer (int32)	Yes	Collection ID.
`values`	array of VariableValue	Yes

PATCH /api/group/{id}/variables/{varId}/collection/{collectionId}

Partially updates one existing collection entry (bundle) on this group.

Required role: group.write

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.
`varId`	path	integer (int32)	Yes	Collection variable's VarID.
`collectionId`	path	integer (int32)	Yes	Entry's CollectionId (from GET .../collection — the raw DB value, not necessarily contiguous).

Request body (required, application/json, schema VariableCollectionEntryPatchRequest)

Field	Type	Required	Description
`values`	map of string to string	Yes

Example request body (placeholder values):

{
    "values": {}
}

Responses

Status	Description	Schema
`200`	OK	VariableCollectionEntry

Response fields (VariableCollectionEntry):

Field	Type	Required	Description
`collectionId`	integer (int32)	Yes	Collection ID.
`values`	array of VariableValue	Yes

DELETE /api/group/{id}/variables/{varId}/collection/{collectionId}

Deletes an entire variable collection entry (all its child values).

Required role: group.write

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.
`varId`	path	integer (int32)	Yes	Collection variable's VarID.
`collectionId`	path	integer (int32)	Yes	Entry's CollectionId (from GET .../collection — the raw DB value, not necessarily contiguous).

Responses

Status	Description	Schema
`204`	No Content	–

GET /api/group/{id}/software-classes

Returns the Software Classes currently assigned to the group. Multi-assign, like OS Language Pack.

Required role: group.read

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).
`includeInherited`	query	boolean	No	Also include Software Classes assigned to any ancestor group.

Responses

Status	Description	Schema
`200`	Paged list of assigned Software Classes.	PagedResultOfSoftwareClass

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

A Software Class (EMC "Software Classes") — bundles multiple software packages under one assignable id, assigned to groups via CompConfGrSwClasses (ClassID → TreeID), not to be confused with an individual package assignment. A package already covered by a Software Class assigned to a group cannot also be assigned directly (see GroupWriteDbRepository.AssignPackage/AssignAgentTemplate — AssignPackageOutcome/ AssignAgentTemplateOutcome.CoveredBySoftwareClass).

Field	Type	Required	Description
`id`	string (uuid)	Yes	ID of the Software Class.
`name`	string	Yes	Name of the Software Class.
`matchMode`	SoftwareClassMatchMode (enum: Or, And)	Yes	Match mode.
`packageIds`	array of string (uuid)	Yes	Software package IDs (GUIDs).

POST /api/group/{id}/software-classes

Assigns a Software Class to the group. Multi-assign, like OS Language Pack.

Required role: group.write

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.

Request body (required, application/json, schema AssignGroupSoftwareClassRequest)

Field	Type	Required	Description
`classId`	string (uuid)	Yes	Software Class ID.

Example request body (placeholder values):

{
    "classId": "00000000-0000-0000-0000-000000000000"
}

Responses

Status	Description	Schema
`200`	Already assigned — no-op success, `alreadyAssigned=true`.	GroupSoftwareClassAssignment
`201`	Assigned; body echoes the assignment.	GroupSoftwareClassAssignment
`404`	Typed body: `GroupNotFound` or `SoftwareClassNotFound`.	GroupSoftwareClassNotFound
`409`	Typed body: `SpecialGroup`.	GroupSoftwareClassConflict

Response fields (GroupSoftwareClassAssignment):

Result of a Software Class→group assignment. Multi-assign, like OS Language Pack. AlreadyAssigned marks the no-op case (the same class was already assigned).

Field	Type	Required	Description
`groupId`	string (uuid)	Yes	Deployment group ID (GUID).
`classId`	string (uuid)	Yes	Software Class ID.
`alreadyAssigned`	boolean	Yes	`true` if the assignment already existed (no change).

DELETE /api/group/{id}/software-classes/{classId}

Removes a Software Class assignment from the group.

Required role: group.write

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Group GUID.
`classId`	path	string (uuid)	Yes	Id of the Software Class to unassign.

Responses

Status	Description	Schema
`204`	Removed, or was not assigned (idempotent).	–
`404`	Typed body: `GroupNotFound`.	GroupSoftwareClassNotFound

POST /api/group/{id}/activation

Activates this group, cascading over its subtree's computers, users, and subgroups.

Required role: activation.execute

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Deployment group ID (GUID).

Request body (required, application/json, schema GroupActivationRequest)

Request body for POST /api/group/{id}/activation. At least one of software/pxe/pull must be true. The activation cascades over the group's subtree (member computers, users, and subgroups) inside dbo.ActivateConfigGroup. global (default true) additionally rewrites each member's flags across ALL of its group memberships, not just this subtree's rows; false keeps it subtree-only. (Deactivation is the opposite: its global is opt-in.) No WOL/SRL options at group level.

Field	Type	Required	Description
`software`	boolean, nullable	Yes	Software deployment activation flag.
`pxe`	boolean, nullable	Yes	PXE boot activation flag.
`pull`	boolean, nullable	Yes	Pull distribution activation flag.
`global`	boolean, nullable	Yes	Global activation flag.

Example request body (placeholder values):

{
    "software": false,
    "pxe": false,
    "pull": false,
    "global": false
}

Responses

Status	Description	Schema
`200`	OK	Not described in the specification
`409`	Conflict	GroupComputersMissingPxeBootImage

DELETE /api/group/{id}/activation

Deactivates this group, clearing the requested activation bits across the subtree.

Required role: activation.execute

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Deployment group ID (GUID).
`software`	query	boolean	No	Activate or filter software deployment.
`pxe`	query	boolean	No	Activate or filter PXE boot.
`pull`	query	boolean	No	Activate or filter pull distribution.
`global`	query	boolean	No	Global activation flag.
`uninstall`	query	boolean	No	Uninstall distribution option.

Responses

Status	Description	Schema
`200`	OK	GroupDeactivated

Response fields (GroupDeactivated):

Confirmation that the group deactivation (dbo.ActivateConfigGroup Activity=2) was queued. When Global, the proc additionally cancels member computers' reinstall groups (legacy "Cancel Reinstall at Deaktivation" branch). Uninstall = DDC rewritten with UNINSTALL entries instead of the packages being removed from it.

Field	Type	Required	Description
`groupId`	string (uuid)	Yes	Deployment group ID (GUID).
`software`	boolean	Yes	Software deployment activation flag.
`pxe`	boolean	Yes	PXE boot activation flag.
`pull`	boolean	Yes	Pull distribution activation flag.
`requestedAtUtc`	string (date-time)	Yes	Time of the request (UTC).
`global`	boolean	Yes	Global activation flag.
`uninstall`	boolean	Yes	Uninstall distribution option.

Software Packages

Software package catalog, fleet deployment status, "Ready to Install" flag, package import from the PackageStore and hash generation.

Method	Path	Summary
GET	`/api/packages`	Returns a paged list of all Empirum software packages.
GET	`/api/packages/{id}`	Returns a single Empirum software package by its GUID.
GET	`/api/packages/{id}/status`	Returns the fleet-wide deployment status of one package across every computer it is assigned to.
PUT	`/api/packages/{id}/operational`	Enables or disables the package for installation (the EMC "Ready to Install" checkbox).
POST	`/api/packages/hash-generation`	Enqueues package hash generation for one package, or for all packages when none is specified.
POST	`/api/packages/import`	Imports a package from the PackageStore folder and hashes it directly (enqueues an ImportPackage job; hash generation is chained by the backend).
GET	`/api/packages/import/{trackingId}`	Returns the current status of a package import job (Pending, Running, Success or Failed).
POST	`/api/packages/search`	Searches packages using one or more filter criteria.

GET /api/packages

Returns a paged list of all Empirum software packages.

Required role: package.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfPackage

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`id`	string (uuid)	Yes	ID of the package.
`name`	string	Yes	Name of the package.
`packageName`	string, nullable	Yes	Package name.
`type`	string, nullable	Yes	Type of the package.
`subType`	string, nullable	Yes	Subtype.
`version`	string, nullable	Yes	Version.
`author`	string, nullable	Yes	Author.
`revision`	string, nullable	Yes	Package revision.
`operational`	boolean	Yes	"Ready to Install" flag of the package.
`os`	array of string	Yes	Operating system.

GET /api/packages/{id}

Returns a single Empirum software package by its GUID.

Required role: package.read

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Software package ID (GUID).

Responses

Status	Description	Schema
`200`	OK	Package

Response fields (Package):

Field	Type	Required	Description
`id`	string (uuid)	Yes
`name`	string	Yes
`packageName`	string, nullable	Yes	Package name.
`type`	string, nullable	Yes
`subType`	string, nullable	Yes	Subtype.
`version`	string, nullable	Yes	Version.
`author`	string, nullable	Yes	Author.
`revision`	string, nullable	Yes	Package revision.
`operational`	boolean	Yes	"Ready to Install" flag of the package.
`os`	array of string	Yes	Operating system.

GET /api/packages/{id}/status

Returns the fleet-wide deployment status of one package across every computer it is assigned to.

Required role: package.read

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Software package ID (GUID).
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).
`groupId`	query	string (uuid)	No	Restrict results to computers in this deployment group (GUID).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfPackageDeploymentDevice

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`computerId`	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`computerName`	string, nullable	Yes	Computer name.
`status`	DeploymentStatus (enum: Pending, Success, Failed)	Yes	Status.
`lastJobTime`	string (date-time), nullable	Yes	Time of the last job (UTC).
`errorText`	string, nullable	Yes	Error text.

PUT /api/packages/{id}/operational

Enables or disables the package for installation (the EMC "Ready to Install" checkbox).

Required role: package.write

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Software package ID (GUID).

Request body (required, application/json, schema SetPackageOperationalRequest)

Request body for enabling/disabling a package for installation (Software.bInstallReady — the EMC "Ready to Install" checkbox).

Field	Type	Required	Description
`operational`	boolean	Yes	"Ready to Install" flag of the package.

Example request body (placeholder values):

{
    "operational": false
}

Responses

Status	Description	Schema
`200`	OK	PackageOperationalResult

Response fields (PackageOperationalResult):

Result of an operational toggle. Changed=false means the flag already had the requested value (idempotent no-op).

Field	Type	Required	Description
`packageId`	string (uuid)	Yes	Software package ID (GUID).
`operational`	boolean	Yes	"Ready to Install" flag of the package.
`changed`	boolean	Yes	`true` if the value changed.

POST /api/packages/hash-generation

Enqueues package hash generation for one package, or for all packages when none is specified.

Required role: package.write

Request body (optional, application/json, schema HashGenerationRequest)

Request body for triggering package hash generation. Omit the body (or PackageId) to generate hashes for all packages.

Field	Type	Required	Description
`packageId`	string (uuid), nullable	No	Software package ID (GUID).

Example request body (placeholder values):

{
    "packageId": "00000000-0000-0000-0000-000000000000"
}

Responses

Status	Description	Schema
`202`	Accepted	HashGenerationTriggered
`404`	Not Found	ProblemDetails

Response fields (HashGenerationTriggered):

Result of enqueuing a CreateHashes job. PackageId/PackageName are null for the all-packages variant. There is no trackingId: the legacy queue insert creates no QueueJobResult row, so completion is not trackable — the hashes appear on the depot shares (PackageHashes.json) when the ActivationQueue SWM service finishes.

Field	Type	Required	Description
`packageId`	string (uuid), nullable	Yes	Software package ID (GUID).
`packageName`	string, nullable	Yes	Package name.
`note`	string, nullable	No

POST /api/packages/import

Imports a package from the PackageStore folder and hashes it directly (enqueues an ImportPackage job; hash generation is chained by the backend).

Required role: package.write

Request body (required, application/json, schema PackageImportRequest)

Request body for importing a package from the PackageStore folder. FolderPath is strictly relative to the PackageStore root (segments allowed, e.g. "Vendor\Product\Version"); absolute paths, drive letters, UNC paths and ".." are rejected. Overwrite maps to the legacy Force parameter — without it, re-importing an existing package fails on the backend.

Field	Type	Required	Description
`folderPath`	string	Yes	Package folder path strictly relative to the PackageStore root (the Empirum 'ACTPath' option). Segments allowed; absolute paths, drive letters, UNC paths and ".." are rejected. Forward slashes are normalized to backslashes. Example: "Vendor\Product\1.0".
`overwrite`	boolean	No	True replaces an existing package with the same identity (legacy Force). Default false — re-importing an existing package then fails on the backend.

Example request body (placeholder values):

{
    "folderPath": "string",
    "overwrite": false
}

Responses

Status	Description	Schema
`202`	Accepted	PackageImportTriggered
`400`	Bad Request	ProblemDetails
`409`	Conflict	ProblemDetails

Response fields (PackageImportTriggered):

Result of enqueuing an ImportPackage job. Unlike hash generation, import jobs ARE trackable: poll GET /api/packages/import/{trackingId}.

Field	Type	Required	Description
`trackingId`	string (uuid)	Yes	Tracking ID (GUID) for follow-up requests.
`packageLocation`	string	Yes	Package location.
`note`	string, nullable	No

GET /api/packages/import/{trackingId}

Returns the current status of a package import job (Pending, Running, Success or Failed).

Required role: package.read

Parameters

Name	In	Type	Required	Description
`trackingId`	path	string (uuid)	Yes	Tracking ID (GUID) returned by the triggering operation.

Responses

Status	Description	Schema
`200`	OK	PackageImportStatus
`404`	Not Found	ProblemDetails

Response fields (PackageImportStatus):

Current status of an import job (latest QueueJobResult row for the tracking id). Status is the raw backend value: Pending, Running, Success or Failed.

Field	Type	Required	Description
`trackingId`	string (uuid)	Yes	Tracking ID (GUID) for follow-up requests.
`status`	string	Yes	Status.
`message`	string, nullable	Yes	Human-readable message.
`timestamp`	string (date-time)	Yes	Timestamp (UTC).

POST /api/packages/search

Searches packages using one or more filter criteria.

Required role: package.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Request body (required, application/json, schema PackageSearchFilter)

Field	Type	Required	Description
`name`	string, nullable	No	Substring match on software display name. Case-insensitive on default Empirum collation.
`packageName`	string, nullable	No	Substring match on the Empirum internal package path identifier.
`author`	string, nullable	No	Substring match on author/vendor (Software.Author).
`type`	string, nullable	No	Substring match on package type.
`subType`	string, nullable	No	Substring match on package sub-type.
`version`	string, nullable	No	Substring match on version.

Example request body (placeholder values):

{
    "name": "string",
    "packageName": "string",
    "author": "string",
    "type": "string",
    "subType": "string",
    "version": "string"
}

Responses

Status	Description	Schema
`200`	OK	PagedResultOfPackage

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`id`	string (uuid)	Yes	ID of the package.
`name`	string	Yes	Name of the package.
`packageName`	string, nullable	Yes	Package name.
`type`	string, nullable	Yes	Type of the package.
`subType`	string, nullable	Yes	Subtype.
`version`	string, nullable	Yes	Version.
`author`	string, nullable	Yes	Author.
`revision`	string, nullable	Yes	Package revision.
`operational`	boolean	Yes	"Ready to Install" flag of the package.
`os`	array of string	Yes	Operating system.

Patches

Patch catalog, patch and product lookups, patch and product approval.

Method	Path	Summary
POST	`/api/patches/search`	Searches the patch catalog without any assignment context.
GET	`/api/patches/{patchId}`	Resolves a catalog patch to its human-readable identity.
GET	`/api/patches/products/{productId}`	Resolves a patch-catalog product id to its name.
GET	`/api/patches/{patchId}/products`	Lists the product versions a patch is linked into, with the number of link items each `productId` scope touches — the choices for the approval / add-to-group writes.
POST	`/api/patches/{patchId}/approval`	Approves (releases) a catalog patch for ONE product version — the link items an EMC operator would select under that product node. Other product versions the patch is linked into are never touched.
DELETE	`/api/patches/{patchId}/approval`	Revokes a patch approval. Without `productId` every link item of the patch is reverted (the repair path for patches over-approved by the pre-603407 API).
POST	`/api/patches/products/{productId}/approval`	Approves (activates/allows as patch) an entire catalog product.

POST /api/patches/search

Searches the patch catalog without any assignment context.

Required role: pm.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Request body (required, application/json, schema PatchCatalogFilter)

Filter for the context-free patch catalog search. All string fields are substring matches except VendorSeverity (exact severity name); AND-combined. Assigned: false = patches not in any PM group (the unassigned-catalog view), true = in at least one PM group, null = all.

Field	Type	Required	Description
`nameContains`	string, nullable	No	Filter by a substring of the name.
`qNumber`	string, nullable	No	Patch Q-number (KB article).
`bulletinId`	string, nullable	No	Security bulletin ID.
`cve`	string, nullable	No	Filter by CVE ID.
`patchType`	PatchType (enum: SecurityPatch, SoftwareDistribution, SecurityTool, NonSecurityPatch, CustomAction)	No	Patch type.
`vendorSeverity`	string, nullable	No	Severity as rated by the vendor.
`minCvss`	number (double), nullable	No	Minimum CVSS score.
`minVrr`	number (double), nullable	No	Minimum VRR score.
`assigned`	boolean, nullable	No	Filter for assigned or unassigned items.
`releasedAfter`	string (date), nullable	No	Only patches released after this date.
`releasedBefore`	string (date), nullable	No	Only patches released before this date.
`updatedAfter`	string (date), nullable	No	Only patches updated after this date.
`updatedBefore`	string (date), nullable	No	Only patches updated before this date.

Example request body (placeholder values):

{
    "nameContains": "string",
    "qNumber": "string",
    "bulletinId": "string",
    "cve": "string",
    "patchType": "SecurityPatch",
    "vendorSeverity": "string",
    "minCvss": 0.0,
    "minVrr": 0.0,
    "assigned": false,
    "releasedAfter": "2026-01-01",
    "releasedBefore": "2026-01-01",
    "updatedAfter": "2026-01-01",
    "updatedBefore": "2026-01-01"
}

Responses

Status	Description	Schema
`200`	OK	PagedResultOfPatchCatalogItem

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

One patch-catalog entry (PM_Patches grain — NOT the 19M-row link-item fan-out). CveIds come from PM_Cveids via PM_PatchToCveids; IsAssigned means any link item of this patch is a member of any PM group (PM_GroupAssignments).

Field	Type	Required	Description
`patchId`	integer (int32)	Yes	Patch ID.
`patchUid`	string (uuid)	Yes	Unique patch identifier.
`name`	string	Yes	Name of the patch.
`qNumber`	string, nullable	Yes	Patch Q-number (KB article).
`bulletinId`	string, nullable	Yes	Security bulletin ID.
`patchType`	PatchType (enum: SecurityPatch, SoftwareDistribution, SecurityTool, NonSecurityPatch, CustomAction)	Yes	Patch type.
`vendorSeverity`	string, nullable	Yes	Severity as rated by the vendor.
`cvssScore`	number (double), nullable	Yes	CVSS score.
`vrrScore`	number (double), nullable	Yes	Vulnerability Risk Rating (VRR) score.
`releaseDate`	string (date), nullable	Yes	Release date.
`updateDate`	string (date), nullable	Yes	Update date.
`isAssigned`	boolean	Yes	`true` if assigned.
`cveIds`	array of string	Yes	Related CVE IDs.
`sizeBytes`	integer (int64), nullable	No	Size in bytes.

GET /api/patches/{patchId}

Resolves a catalog patch to its human-readable identity.

Required role: pm.read

Parameters

Name	In	Type	Required	Description
`patchId`	path	integer (int32)	Yes	Patch ID.

Responses

Status	Description	Schema
`200`	OK	PatchCatalogItem

Response fields (PatchCatalogItem):

Field	Type	Required	Description
`patchId`	integer (int32)	Yes	Patch ID.
`patchUid`	string (uuid)	Yes	Unique patch identifier.
`name`	string	Yes
`qNumber`	string, nullable	Yes	Patch Q-number (KB article).
`bulletinId`	string, nullable	Yes	Security bulletin ID.
`patchType`	PatchType (enum: SecurityPatch, SoftwareDistribution, SecurityTool, NonSecurityPatch, CustomAction)	Yes	Patch type.
`vendorSeverity`	string, nullable	Yes	Severity as rated by the vendor.
`cvssScore`	number (double), nullable	Yes	CVSS score.
`vrrScore`	number (double), nullable	Yes	Vulnerability Risk Rating (VRR) score.
`releaseDate`	string (date), nullable	Yes	Release date.
`updateDate`	string (date), nullable	Yes	Update date.
`isAssigned`	boolean	Yes	`true` if assigned.
`cveIds`	array of string	Yes	Related CVE IDs.
`sizeBytes`	integer (int64), nullable	No	Size in bytes.

GET /api/patches/products/{productId}

Resolves a patch-catalog product id to its name.

Required role: pm.read

Parameters

Name	In	Type	Required	Description
`productId`	path	integer (int32)	Yes	PM_Products id.

Responses

Status	Description	Schema
`200`	OK	PmProductInfo

Response fields (PmProductInfo):

Human-readable identity of a patch-catalog product (PM_Products row).

Field	Type	Required	Description
`id`	integer (int32)	Yes
`productName`	string	Yes	Product name.

GET /api/patches/{patchId}/products

Lists the product versions a patch is linked into, with the number of link items each productId scope touches — the choices for the approval / add-to-group writes.

Required role: pm.read

Parameters

Name	In	Type	Required	Description
`patchId`	path	integer (int32)	Yes	PM_Patches id.

Responses

Status	Description	Schema
`200`	OK	array of PatchProductLink

Response fields (PatchProductLink):

One product version (PM_Products row) a patch is linked into, with the number of PM_PatchLinkedItems rows (the EMC console's approval grain) that a write scoped to this productId touches. ApprovalStatus = MAX(ItemStatus) over those link items.

Field	Type	Required	Description
`productId`	integer (int32)	Yes	Patch catalog product ID.
`productName`	string	Yes	Product name.
`isVisible`	boolean	Yes	`true` if visible.
`linkItemCount`	integer (int32)	Yes	Number of link items.
`approvalStatus`	PmPatchStatus (enum: Available, Downloading, Downloaded, Approved, Disapproved, Deleted, Approving, DownloadFailed, Revised, Deleting)	Yes	Approval status.

POST /api/patches/{patchId}/approval

Approves (releases) a catalog patch for ONE product version — the link items an EMC operator would select under that product node. Other product versions the patch is linked into are never touched.

Required role: pm.approve

Parameters

Name	In	Type	Required	Description
`patchId`	path	integer (int32)	Yes	PM_Patches id, e.g. from the missing-patch issue's `patchId` field or the catalog search.
`productId`	query	integer (int32)	No	PM_Products id (the missing-patch item's `productId`, or one of `GET /api/patches/{patchId}/products`). Required unless `allProducts`.
`allProducts`	query	boolean	No	Explicitly approve the patch for every product version it is linked into (the EMC multi-select). Neither parameter → 400 `ProductScopeRequired` listing the product versions.

Responses

Status	Description	Schema
`200`	OK	PatchApprovalResult

Response fields (PatchApprovalResult):

Aggregate result of an approve/disapprove call over the link items of a patch in scope (PBI 603407): ProductId = the product version the call was scoped to (null = every product version the patch is linked into — explicit allProducts or unscoped disapprove), LinkItemsTotal = link items in that scope, PatchCount = 1 (kept for shape parity with PatchMembershipResult). Approval is asynchronous EMC-side: Approving count > 0 means the EMC ActivationQueue PM service is downloading the patch binary and will set Approved itself — poll for final state.

Field	Type	Required	Description
`patchId`	integer (int32)	Yes	Patch ID.
`approving`	integer (int32)	Yes	Items that are approved by this request.
`alreadyApproved`	integer (int32)	Yes	Items that were already approved.
`invalidState`	integer (int32)	Yes	Items that could not be changed because of their state.
`message`	string	Yes	Human-readable message.
`productId`	integer (int32), nullable	No	Patch catalog product ID.
`linkItemsTotal`	integer (int32)	No	Total number of link items.
`patchCount`	integer (int32)	No	Number of patches.

DELETE /api/patches/{patchId}/approval

Revokes a patch approval. Without productId every link item of the patch is reverted (the repair path for patches over-approved by the pre-603407 API).

Required role: pm.approve

Parameters

Name	In	Type	Required	Description
`patchId`	path	integer (int32)	Yes	PM_Patches id.
`productId`	query	integer (int32)	No	Optional PM_Products id — revert only that product version.

Responses

Status	Description	Schema
`200`	OK	PatchApprovalResult

Response fields (PatchApprovalResult):

Field	Type	Required	Description
`patchId`	integer (int32)	Yes	Patch ID.
`approving`	integer (int32)	Yes	Items that are approved by this request.
`alreadyApproved`	integer (int32)	Yes	Items that were already approved.
`invalidState`	integer (int32)	Yes	Items that could not be changed because of their state.
`message`	string	Yes	Human-readable message.
`productId`	integer (int32), nullable	No	Patch catalog product ID.
`linkItemsTotal`	integer (int32)	No	Total number of link items.
`patchCount`	integer (int32)	No	Number of patches.

POST /api/patches/products/{productId}/approval

Approves (activates/allows as patch) an entire catalog product.

Required role: pm.approve

Parameters

Name	In	Type	Required	Description
`productId`	path	integer (int32)	Yes	PM_Products id, e.g. from `GET /api/pmgroup/{id}/products`.

Responses

Status	Description	Schema
`200`	OK	ProductApprovalResult

Response fields (ProductApprovalResult):

Result of a product-level approval fan-out across the product's PM_PatchLinkedItems AND PM_ServicePackLinkedItems. Per-link outcomes are aggregated; Disapproved/Deleted links count as InvalidState, never a whole-request conflict.

Field	Type	Required	Description
`productId`	integer (int32)	Yes	Patch catalog product ID.
`approving`	integer (int32)	Yes	Items that are approved by this request.
`alreadyApproved`	integer (int32)	Yes	Items that were already approved.
`invalidState`	integer (int32)	Yes	Items that could not be changed because of their state.
`patchLinkCount`	integer (int32)	Yes	Number of patch link items.
`servicePackLinkCount`	integer (int32)	Yes	Number of service pack link items.

Patch Management Groups

Patch Management (PM) groups, their products and patches, tree assignments and emergency patching.

Method	Path	Summary
GET	`/api/pmgroup`	Returns a paged list of Patch Management catalogue groups, optionally filtered by category and name.
POST	`/api/pmgroup`	Creates a Patch Management catalogue group.
GET	`/api/pmgroup/{id}`	Returns a single Patch Management catalogue group by its id.
GET	`/api/pmgroup/{id}/products`	Returns a paged list of the products (patch-catalog entries) contained in the PM group.
POST	`/api/pmgroup/{id}/products`	Adds a patch-catalog product to the PM group as Include or Test assignments.
GET	`/api/pmgroup/{id}/patches`	Returns a paged list of the patches in the PM group.
POST	`/api/pmgroup/{id}/patches`	Adds patches to the PM group as Include or Test assignments, scoped to ONE product version (`productId` — the rows an EMC operator would select) or explicitly to every product version the patches are linked into (`allProducts`). Neither → 400 `ProductScopeRequired`.
GET	`/api/pmgroup/{id}/assignments`	Returns a paged list of the Empirum groups (tree nodes) the PM group is assigned to.
POST	`/api/pmgroup/{id}/assignments`	Assigns the PM group to an Empirum group-tree node (ComputerGroupTree or AssignmentGroupTree).
DELETE	`/api/pmgroup/{id}/assignments`	Removes the PM group's assignment from a tree node.
DELETE	`/api/pmgroup/{id}/patches/{patchId}`	Removes a patch (all of its link items) from the PM group.
DELETE	`/api/pmgroup/{id}/products/{productId}`	Removes all patches for a product from the PM group.
POST	`/api/pmgroup/{id}/emergency-patching`	Triggers emergency patch remediation for the PM group across the target computers.
DELETE	`/api/pmgroup/{id}/emergency-patching`	Removes the emergency assignment group for this PM group, including all child groups.

GET /api/pmgroup

Returns a paged list of Patch Management catalogue groups, optionally filtered by category and name.

Required role: pm.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).
`category`	query	PmGroupCategory (enum: Patch, ServicePack)	No	Filter by group category: Patch or ServicePack. Omit for all.
`nameContains`	query	string	No	Only groups whose name contains this substring.

Responses

Status	Description	Schema
`200`	OK	PagedResultOfPmGroup

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

A Patch Management catalogue group (PM_Groups).

Field	Type	Required	Description
`id`	integer (int32)	Yes	ID of the PM group.
`name`	string	Yes	Name of the PM group.
`category`	PmGroupCategory (enum: Patch, ServicePack)	Yes	Category.
`mode`	PmGroupMode (enum: Normal, IncludeAll, ExcludeAll)	Yes	Mode.
`days`	integer (int16)	Yes	Days.
`testMinutes`	integer (int16)	Yes	Duration of the test phase in minutes.
`info`	string, nullable	Yes

POST /api/pmgroup

Creates a Patch Management catalogue group.

Required role: pm.write

Request body (required, application/json, schema CreatePmGroupRequest)

Request body for creating a PM group. Mode is restricted to Normal — the IncludeAll/ExcludeAll backfill of approved patches lives only in the console's UpdateGroup path, so a REST-created IncludeAll group would be silently empty.

Field	Type	Required	Description
`name`	string	Yes	Name of the PM group.
`category`	PmGroupCategory (enum: Patch, ServicePack)	No	Category.
`mode`	PmGroupMode (enum: Normal, IncludeAll, ExcludeAll)	No	Mode.
`days`	integer (int16)	No	Days.
`testMinutes`	integer (int16)	No	Duration of the test phase in minutes.
`info`	string, nullable	No

Example request body (placeholder values):

{
    "name": "string",
    "category": "Patch",
    "mode": "Normal",
    "days": 0,
    "testMinutes": 0,
    "info": "string"
}

Responses

Status	Description	Schema
`200`	OK	Not described in the specification
`409`	Conflict	PmGroupCreateConflict

GET /api/pmgroup/{id}

Returns a single Patch Management catalogue group by its id.

Required role: pm.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	PM group ID.

Responses

Status	Description	Schema
`200`	OK	PmGroup

Response fields (PmGroup):

A Patch Management catalogue group (PM_Groups).

Field	Type	Required	Description
`id`	integer (int32)	Yes
`name`	string	Yes
`category`	PmGroupCategory (enum: Patch, ServicePack)	Yes	Category.
`mode`	PmGroupMode (enum: Normal, IncludeAll, ExcludeAll)	Yes	Mode.
`days`	integer (int16)	Yes	Days.
`testMinutes`	integer (int16)	Yes	Duration of the test phase in minutes.
`info`	string, nullable	Yes

GET /api/pmgroup/{id}/products

Returns a paged list of the products (patch-catalog entries) contained in the PM group.

Required role: pm.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	PM group id.
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfPmGroupProduct

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

A product (patch-catalog entry) contained in a PM group, derived from its patch/service-pack link items — EMC has no products-in-group table. "Activated" in the EMC WebConsole = ItemStatus 4 (Approved) AND product IsVisible.

Field	Type	Required	Description
`productId`	integer (int32)	Yes	Patch catalog product ID.
`productName`	string	Yes	Product name.
`isVisible`	boolean	Yes	`true` if visible.
`totalItemCount`	integer (int32)	Yes	Total number of items.
`approvedCount`	integer (int32)	Yes	Number of approved items.
`disapprovedCount`	integer (int32)	Yes	Number of disapproved items.
`includeCount`	integer (int32)	Yes	Number of include assignments.
`excludeCount`	integer (int32)	Yes	Number of exclude assignments.
`testCount`	integer (int32)	Yes	Number of test assignments.

POST /api/pmgroup/{id}/products

Adds a patch-catalog product to the PM group as Include or Test assignments.

, pm.approve.

Required role: pm.write

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	PM group ID.

Request body (required, application/json, schema AddProductToGroupRequest)

Request body for adding a catalog product to a PM group. Membership is resolved to the product's link items matching the group's category.

Field	Type	Required	Description
`productId`	integer (int32)	Yes	Patch catalog product ID.
`groupType`	PmAssignmentType (enum: Include, Exclude, Test)	No	Group type.

Example request body (placeholder values):

{
    "productId": 0,
    "groupType": "Include"
}

Responses

Status	Description	Schema
`200`	OK	Not described in the specification
`409`	Conflict	PmGroupProductConflict

GET /api/pmgroup/{id}/patches

Returns a paged list of the patches in the PM group.

Required role: pm.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	PM group id.
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfPmGroupPatch

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

A patch (PM_Patches grain) inside a PM group, with its assignment type (GroupType) and current approval status (ItemStatus).

Field	Type	Required	Description
`patchId`	integer (int32)	Yes	Patch ID.
`patchUid`	string (uuid)	Yes	Unique patch identifier.
`patchName`	string	Yes	Patch name.
`qNumber`	string, nullable	Yes	Patch Q-number (KB article).
`productName`	string, nullable	Yes	Product name.
`groupType`	PmAssignmentType (enum: Include, Exclude, Test)	Yes	Group type.
`approvalStatus`	PmPatchStatus (enum: Available, Downloading, Downloaded, Approved, Disapproved, Deleted, Approving, DownloadFailed, Revised, Deleting)	Yes	Approval status.

POST /api/pmgroup/{id}/patches

Adds patches to the PM group as Include or Test assignments, scoped to ONE product version (productId — the rows an EMC operator would select) or explicitly to every product version the patches are linked into (allProducts). Neither → 400 ProductScopeRequired.

Required role: pm.write

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	PM group ID.

Request body (required, application/json, schema AddPatchesToGroupRequest)

Request body for adding patches to a PM group (PBI 603407). Exactly one scope is required: ProductId (PM_Products id — only the link items of that product version, i.e. the rows an EMC operator would select) or AllProducts=true (every product version each patch is linked into — the EMC multi-select). Neither → 400 ProductScopeRequired; both → 400.

Field	Type	Required	Description
`patchIds`	array of integer (int32)	Yes	Patch IDs.
`groupType`	PmAssignmentType (enum: Include, Exclude, Test)	Yes	Group type.
`productId`	integer (int32), nullable	No	Patch catalog product ID.
`allProducts`	boolean	No	Apply to all products.

Example request body (placeholder values):

{
    "patchIds": [
        0
    ],
    "groupType": "Include",
    "productId": 0,
    "allProducts": false
}

Responses

Status	Description	Schema
`200`	OK	PatchMembershipResult

Response fields (PatchMembershipResult):

Result of a group-membership change. Idempotent semantics: re-adding an existing assignment counts as AlreadyAssigned; adding with a different GroupType moves the item (MovedFromOtherType), mirroring the EMC console's upsert. ProductId = the scope of the call (null = all product versions), PatchCount = distinct patches requested, LinkItemsTotal = link items in scope (= Added + AlreadyAssigned + MovedFromOtherType).

Field	Type	Required	Description
`added`	integer (int32)	Yes	Items that were added.
`alreadyAssigned`	integer (int32)	Yes	`true` if the assignment already existed (no change).
`movedFromOtherType`	integer (int32)	Yes	Items moved from another assignment type.
`productId`	integer (int32), nullable	No	Patch catalog product ID.
`patchCount`	integer (int32)	No	Number of patches.
`linkItemsTotal`	integer (int32)	No	Total number of link items.

GET /api/pmgroup/{id}/assignments

Returns a paged list of the Empirum groups (tree nodes) the PM group is assigned to.

isTestAssignment marks nodes that receive the PM group's Test-Group rollout (patches deployed there first, for the group's Days/TestMinutes window). testOnly=true narrows to the test nodes — the group's first-wave verification rings.

Required role: pm.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	PM group id.
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).
`testOnly`	query	boolean	No	Only assignments with the test flag (first-wave nodes).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfPmGroupAssignment

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

An Empirum group-tree node a PM group is assigned to (CompConfGrPMGroups). IsTestAssignment mirrors TestFlag — the node receives the PM group's test class. PmClientGaps (assign response only, null on the GET list) warns when the PM client Scan/Fix packages are not assigned at the node or an ancestor (codes ScanPackageNotAssigned / FixPackageNotAssigned, matching the missing-patch issue) — without them the PM group's patches are never scanned for or installed on the node's devices. Heuristic: devices may still receive the packages via another group.

Field	Type	Required	Description
`treeId`	string (uuid)	Yes	Group tree node ID.
`groupName`	string, nullable	Yes	Group name.
`isTestAssignment`	boolean	Yes	`true` if this is a test assignment.
`pmClientGaps`	array of string, nullable	No

POST /api/pmgroup/{id}/assignments

Assigns the PM group to an Empirum group-tree node (ComputerGroupTree or AssignmentGroupTree).

isTestAssignment marks the node as the group's test/pilot ring and requires the group to already be assigned at an ancestor node. No activation is needed — the next patch scan resolves the new configuration. Returns 409 with codes AlreadyAssigned, ConflictingTestFlag or TestRequiresParentAssignment. The 201 body carries pmClientGaps (ScanPackageNotAssigned / FixPackageNotAssigned) when the PM client Scan/Fix packages are not assigned at the node or an ancestor — without them the group's patches are never scanned for or installed. The resulting assignment list is GET /api/pmgroup/{id}/assignments.

Required role: pm.write

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	PM group ID.

Request body (required, application/json, schema AssignPmGroupRequest)

Request body for assigning a PM group to an Empirum tree node.

Field	Type	Required	Description
`treeId`	string (uuid)	Yes	Group tree node ID.
`isTestAssignment`	boolean	No	`true` if this is a test assignment.

Example request body (placeholder values):

{
    "treeId": "00000000-0000-0000-0000-000000000000",
    "isTestAssignment": false
}

Responses

Status	Description	Schema
`200`	OK	Not described in the specification
`409`	Conflict	PmGroupAssignmentConflict

DELETE /api/pmgroup/{id}/assignments

Removes the PM group's assignment from a tree node.

Required role: pm.write

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	PM group ID.
`treeId`	query	string (uuid)	No	Group tree node ID.

Responses

Status	Description	Schema
`200`	OK	–

DELETE /api/pmgroup/{id}/patches/{patchId}

Removes a patch (all of its link items) from the PM group.

Required role: pm.write

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	PM group ID.
`patchId`	path	integer (int32)	Yes	Patch ID.

Responses

Status	Description	Schema
`200`	OK	–

DELETE /api/pmgroup/{id}/products/{productId}

Removes all patches for a product from the PM group.

Required role: pm.write

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	PM group ID.
`productId`	path	integer (int32)	Yes	Patch catalog product ID.

Responses

Status	Description	Schema
`200`	OK	–

POST /api/pmgroup/{id}/emergency-patching

Triggers emergency patch remediation for the PM group across the target computers.

Required role: pm.execute

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	PM group ID.

Request body (required, application/json, schema StartEmergencyPatchingRequest)

Request body for the emergency-patching orchestration (PBI 591780). The PM group id comes from the route (POST /api/pmgroup/{id}/emergency-patching).

Field	Type	Required	Description
`computerIds`	array of integer (int32)	Yes	Computer IDs (Empirum `client_id`).

Example request body (placeholder values):

{
    "computerIds": [
        0
    ]
}

Responses

Status	Description	Schema
`200`	OK	EmergencyPatchingStarted
`404`	Not Found	EmergencyPatchingConflict
`409`	Conflict	EmergencyPatchingConflict

Response fields (EmergencyPatchingStarted):

The full step ledger of one emergency-patching run: what was created, what already existed, and what failed — the caller sees exactly what exists and can re-run (idempotent) or DELETE (recoverable).

Field	Type	Required	Description
`groupId`	string (uuid)	Yes	Deployment group ID (GUID).
`groupName`	string	Yes	Group name.
`groupCreated`	boolean	Yes	`true` if the group was created.
`pmGroupId`	integer (int32)	Yes	PM group ID.
`pmGroupName`	string	Yes	PM group name.
`pmGroupAssignment`	EmergencyStepOutcome (enum: Created, AlreadyPresent, Failed)	Yes	PM group assignment.
`packages`	array of EmergencyPackageAssignment	Yes	Packages.
`computers`	array of EmergencyComputerOutcome	Yes	Computers.
`note`	string	Yes

DELETE /api/pmgroup/{id}/emergency-patching

Removes the emergency assignment group for this PM group, including all child groups.

Required role: pm.execute

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	PM group ID.

Responses

Status	Description	Schema
`200`	OK	EmergencyPatchingRemoval

Response fields (EmergencyPatchingRemoval):

DELETE result: the removed emergency group and how many child groups (in-flight Reinstall_* scan groups) went with it.

Field	Type	Required	Description
`groupId`	string (uuid)	Yes	Deployment group ID (GUID).
`groupName`	string	Yes	Group name.
`deletedChildGroups`	integer (int32)	Yes	Deleted child groups.

Operating System Imports

OS installation image packages and their SKUs (editions).

Method	Path	Summary
GET	`/api/operating-system-imports`	Returns a paged list of all OS installation image packages, each with its SKUs nested.
GET	`/api/operating-system-imports/{id}`	Returns a single OS installation image package by its GUID, with its SKUs nested.
GET	`/api/operating-system-imports/{id}/skus/{skuId}/groups`	Reverse lookup: returns every group with a direct assignment of this SKU (the SKU, not the package, is the assignable object). Direct assignments only — these object types are never assigned to computers, and no inheritance resolution applies.
POST	`/api/operating-system-imports/search`	Searches OS installation image packages by name.

GET /api/operating-system-imports

Returns a paged list of all OS installation image packages, each with its SKUs nested.

Required role: package.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfOperatingSystemImport

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

An OS installation image package (Software.Type = "OSInstallationImage"), e.g. a Windows 10 ISO, with its SKUs (editions) nested. The package itself is never directly assignable to a group — a specific SKU is, via POST /api/group/{id}/os-image-sku. PackageName/Version/Author/Revision are deliberately omitted — live-DB verification showed PackageName always duplicates Name and the others are always NULL for this Software.Type.

Field	Type	Required	Description
`id`	string (uuid)	Yes	ID of the OS image package.
`name`	string	Yes	Name of the OS image package.
`skus`	array of OperatingSystemImportSku	Yes	Available SKUs (editions).

GET /api/operating-system-imports/{id}

Returns a single OS installation image package by its GUID, with its SKUs nested.

Required role: package.read

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	OS installation image package ID (GUID).

Responses

Status	Description	Schema
`200`	OK	OperatingSystemImport

Response fields (OperatingSystemImport):

Field	Type	Required	Description
`id`	string (uuid)	Yes
`name`	string	Yes
`skus`	array of OperatingSystemImportSku	Yes	Available SKUs (editions).

GET /api/operating-system-imports/{id}/skus/{skuId}/groups

Reverse lookup: returns every group with a direct assignment of this SKU (the SKU, not the package, is the assignable object). Direct assignments only — these object types are never assigned to computers, and no inheritance resolution applies.

Required role: package.read

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	OS installation image package ID (GUID).
`skuId`	path	integer (int32)	Yes	OS image SKU (edition) ID.
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfDeviceGroup

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`groupId`	string (uuid)	Yes	Deployment group ID (GUID).
`name`	string	Yes	Name of the group.
`assignedToTree`	string, nullable	Yes	Tree the group is assigned to.
`description`	string, nullable	Yes	Description of the group.

POST /api/operating-system-imports/search

Searches OS installation image packages by name.

Required role: package.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Request body (required, application/json, schema OperatingSystemImportSearchFilter)

Field	Type	Required	Description
`name`	string, nullable	No	Substring match on the OS installation image package display name.

Example request body (placeholder values):

{
    "name": "string"
}

Responses

Status	Description	Schema
`200`	OK	PagedResultOfOperatingSystemImport

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`id`	string (uuid)	Yes	ID of the OS image package.
`name`	string	Yes	Name of the OS image package.
`skus`	array of OperatingSystemImportSku	Yes	Available SKUs (editions).

PXE Boot Images

PXE boot images and the groups they are assigned to.

Method	Path	Summary
GET	`/api/pxe-bootimages`	Returns a paged list of all PXE boot images.
GET	`/api/pxe-bootimages/{id}`	Returns a single PXE boot image by its id.
GET	`/api/pxe-bootimages/{id}/groups`	Reverse lookup: returns every group with a direct assignment of this PXE boot image. Direct assignments only — these object types are never assigned to computers, and no inheritance resolution applies.
POST	`/api/pxe-bootimages/search`	Searches PXE boot images by name.

GET /api/pxe-bootimages

Returns a paged list of all PXE boot images.

Required role: package.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfPxeBootImage

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

A PXE boot image (e.g. "StdWinPE") — the assignable object for POST /api/group/{id}/pxe-bootimage. Not a Software row; catalogued in dhcp_boot_info.

Field	Type	Required	Description
`id`	integer (int32)	Yes	ID of the PXE boot image.
`name`	string	Yes	Name of the PXE boot image.
`bootFile`	string	Yes	Boot file.
`sysInfo`	integer (int32)	Yes	System information.
`archInfo`	integer (int32)	Yes	Architecture information.

GET /api/pxe-bootimages/{id}

Returns a single PXE boot image by its id.

Required role: package.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	PXE boot image ID.

Responses

Status	Description	Schema
`200`	OK	PxeBootImage

Response fields (PxeBootImage):

A PXE boot image (e.g. "StdWinPE") — the assignable object for POST /api/group/{id}/pxe-bootimage. Not a Software row; catalogued in dhcp_boot_info.

Field	Type	Required	Description
`id`	integer (int32)	Yes
`name`	string	Yes
`bootFile`	string	Yes	Boot file.
`sysInfo`	integer (int32)	Yes	System information.
`archInfo`	integer (int32)	Yes	Architecture information.

GET /api/pxe-bootimages/{id}/groups

Reverse lookup: returns every group with a direct assignment of this PXE boot image. Direct assignments only — these object types are never assigned to computers, and no inheritance resolution applies.

Required role: package.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	PXE boot image ID.
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfDeviceGroup

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`groupId`	string (uuid)	Yes	Deployment group ID (GUID).
`name`	string	Yes	Name of the group.
`assignedToTree`	string, nullable	Yes	Tree the group is assigned to.
`description`	string, nullable	Yes	Description of the group.

POST /api/pxe-bootimages/search

Searches PXE boot images by name.

Required role: package.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Request body (required, application/json, schema PxeBootImageSearchFilter)

Field	Type	Required	Description
`name`	string, nullable	No	Substring match on the boot image name (e.g. "WinPE").

Example request body (placeholder values):

{
    "name": "string"
}

Responses

Status	Description	Schema
`200`	OK	PagedResultOfPxeBootImage

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

A PXE boot image (e.g. "StdWinPE") — the assignable object for POST /api/group/{id}/pxe-bootimage. Not a Software row; catalogued in dhcp_boot_info.

Field	Type	Required	Description
`id`	integer (int32)	Yes	ID of the PXE boot image.
`name`	string	Yes	Name of the PXE boot image.
`bootFile`	string	Yes	Boot file.
`sysInfo`	integer (int32)	Yes	System information.
`archInfo`	integer (int32)	Yes	Architecture information.

Language Pack Imports

OS Language Packs and the groups they are assigned to.

Method	Path	Summary
GET	`/api/language-pack-imports`	Returns a paged list of all OS Language Packs.
GET	`/api/language-pack-imports/{id}`	Returns a single OS Language Pack by its GUID.
GET	`/api/language-pack-imports/{id}/groups`	Reverse lookup: returns every group with a direct assignment of this OS Language Pack. Direct assignments only — these object types are never assigned to computers, and no inheritance resolution applies.
POST	`/api/language-pack-imports/search`	Searches OS Language Packs by name.

GET /api/language-pack-imports

Returns a paged list of all OS Language Packs.

Required role: package.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfLanguagePackImport

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`id`	string (uuid)	Yes	ID of the Language Pack.
`name`	string	Yes	Name of the Language Pack.

GET /api/language-pack-imports/{id}

Returns a single OS Language Pack by its GUID.

Required role: package.read

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Language Pack ID.

Responses

Status	Description	Schema
`200`	OK	LanguagePackImport

Response fields (LanguagePackImport):

Field	Type	Required	Description
`id`	string (uuid)	Yes
`name`	string	Yes

GET /api/language-pack-imports/{id}/groups

Reverse lookup: returns every group with a direct assignment of this OS Language Pack. Direct assignments only — these object types are never assigned to computers, and no inheritance resolution applies.

Required role: package.read

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Language Pack ID.
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfDeviceGroup

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`groupId`	string (uuid)	Yes	Deployment group ID (GUID).
`name`	string	Yes	Name of the group.
`assignedToTree`	string, nullable	Yes	Tree the group is assigned to.
`description`	string, nullable	Yes	Description of the group.

POST /api/language-pack-imports/search

Searches OS Language Packs by name.

Required role: package.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Request body (required, application/json, schema LanguagePackImportSearchFilter)

Field	Type	Required	Description
`name`	string, nullable	No	Substring match on the OS Language Pack display name.

Example request body (placeholder values):

{
    "name": "string"
}

Responses

Status	Description	Schema
`200`	OK	PagedResultOfLanguagePackImport

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`id`	string (uuid)	Yes	ID of the Language Pack.
`name`	string	Yes	Name of the Language Pack.

Agent Templates

Agent Templates and the groups they are assigned to.

Method	Path	Summary
GET	`/api/agent-templates`	Returns a paged list of all Agent Templates.
GET	`/api/agent-templates/{id}`	Returns a single Agent Template by its GUID.
GET	`/api/agent-templates/{id}/groups`	Reverse lookup: returns every group with a direct assignment of this Agent Template. Direct assignments only — these object types are never assigned to computers, and no inheritance resolution applies.
POST	`/api/agent-templates/search`	Searches Agent Templates by name.

GET /api/agent-templates

Returns a paged list of all Agent Templates.

Required role: package.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfAgentTemplate

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`id`	string (uuid)	Yes	ID of the Agent Template.
`name`	string	Yes	Name of the Agent Template.
`pollingIntervalSeconds`	integer (int32), nullable	Yes	Agent polling interval in seconds.
`suppressReboot`	boolean, nullable	Yes	`true` if reboots are suppressed.
`remindUserOnReboot`	boolean, nullable	Yes	`true` if the user is reminded before a reboot.
`remindUserOnRebootIntervalMinutes`	integer (int32), nullable	Yes	Reminder interval in minutes.
`forceRebootAfterMinutes`	integer (int32), nullable	Yes	Minutes after which a reboot is forced.

GET /api/agent-templates/{id}

Returns a single Agent Template by its GUID.

Required role: package.read

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Agent Template ID.

Responses

Status	Description	Schema
`200`	OK	AgentTemplate

Response fields (AgentTemplate):

Field	Type	Required	Description
`id`	string (uuid)	Yes
`name`	string	Yes
`pollingIntervalSeconds`	integer (int32), nullable	Yes	Agent polling interval in seconds.
`suppressReboot`	boolean, nullable	Yes	`true` if reboots are suppressed.
`remindUserOnReboot`	boolean, nullable	Yes	`true` if the user is reminded before a reboot.
`remindUserOnRebootIntervalMinutes`	integer (int32), nullable	Yes	Reminder interval in minutes.
`forceRebootAfterMinutes`	integer (int32), nullable	Yes	Minutes after which a reboot is forced.

GET /api/agent-templates/{id}/groups

Reverse lookup: returns every group with a direct assignment of this Agent Template. Direct assignments only — these object types are never assigned to computers, and no inheritance resolution applies.

Required role: package.read

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Agent Template ID.
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfDeviceGroup

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`groupId`	string (uuid)	Yes	Deployment group ID (GUID).
`name`	string	Yes	Name of the group.
`assignedToTree`	string, nullable	Yes	Tree the group is assigned to.
`description`	string, nullable	Yes	Description of the group.

POST /api/agent-templates/search

Searches Agent Templates by name.

Required role: package.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Request body (required, application/json, schema AgentTemplateSearchFilter)

Field	Type	Required	Description
`name`	string, nullable	No	Substring match on the Agent Template display name.

Example request body (placeholder values):

{
    "name": "string"
}

Responses

Status	Description	Schema
`200`	OK	PagedResultOfAgentTemplate

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`id`	string (uuid)	Yes	ID of the Agent Template.
`name`	string	Yes	Name of the Agent Template.
`pollingIntervalSeconds`	integer (int32), nullable	Yes	Agent polling interval in seconds.
`suppressReboot`	boolean, nullable	Yes	`true` if reboots are suppressed.
`remindUserOnReboot`	boolean, nullable	Yes	`true` if the user is reminded before a reboot.
`remindUserOnRebootIntervalMinutes`	integer (int32), nullable	Yes	Reminder interval in minutes.
`forceRebootAfterMinutes`	integer (int32), nullable	Yes	Minutes after which a reboot is forced.

Software Classes

Software Classes (bundles of software packages).

Method	Path	Summary
GET	`/api/softwareclasses`	Returns a paged list of all Software Classes.
GET	`/api/softwareclasses/{id}`	Returns a single Software Class by its id.
POST	`/api/softwareclasses/search`	Searches Software Classes by name.

GET /api/softwareclasses

Returns a paged list of all Software Classes.

Required role: package.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfSoftwareClass

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`id`	string (uuid)	Yes	ID of the Software Class.
`name`	string	Yes	Name of the Software Class.
`matchMode`	SoftwareClassMatchMode (enum: Or, And)	Yes	Match mode.
`packageIds`	array of string (uuid)	Yes	Software package IDs (GUIDs).

GET /api/softwareclasses/{id}

Returns a single Software Class by its id.

Required role: package.read

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Software Class ID.

Responses

Status	Description	Schema
`200`	OK	SoftwareClass

Response fields (SoftwareClass):

Field	Type	Required	Description
`id`	string (uuid)	Yes
`name`	string	Yes
`matchMode`	SoftwareClassMatchMode (enum: Or, And)	Yes	Match mode.
`packageIds`	array of string (uuid)	Yes	Software package IDs (GUIDs).

POST /api/softwareclasses/search

Searches Software Classes by name.

Required role: package.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Request body (required, application/json, schema SoftwareClassSearchFilter)

Field	Type	Required	Description
`name`	string, nullable	No	Substring match on the Software Class name.

Example request body (placeholder values):

{
    "name": "string"
}

Responses

Status	Description	Schema
`200`	OK	PagedResultOfSoftwareClass

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`id`	string (uuid)	Yes	ID of the Software Class.
`name`	string	Yes	Name of the Software Class.
`matchMode`	SoftwareClassMatchMode (enum: Or, And)	Yes	Match mode.
`packageIds`	array of string (uuid)	Yes	Software package IDs (GUIDs).

Variable Definitions

Empirum variable definitions, their children and inverse lookups of computers, groups and configurations that use a variable.

Method	Path	Summary
GET	`/api/variable-definitions`	Returns a paged list of all Variable Definitions.
GET	`/api/variable-definitions/{varId}`	Returns a single Variable Definition by its VarID.
GET	`/api/variable-definitions/{varId}/computers`	Inverse search: returns every computer with an explicit direct value set for this VarID.
GET	`/api/variable-definitions/{varId}/groups`	Inverse search: returns every group with an explicit direct value set for this VarID.
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).
GET	`/api/variable-definitions/{varId}/children`	Returns every child variable definition of this VarID.
POST	`/api/variable-definitions/search`	Searches Variable Definitions by name (matches either the raw Designation or the dotted "{parent}.{child}" form).

GET /api/variable-definitions

Returns a paged list of all Variable Definitions.

Required role: package.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfVariableDefinition

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

One variable definition from the DefCompPkgVar catalogue — describes what a computer/group variable is (name, default value, data type), never its resolved value (that lives in CompVariables/GroupVariables, read via /api/computer/{id}/variables and /api/group/{id}/variables). string VariableDefinition.DottedName is string VariableDefinition.Designation for a top-level variable, or "{parent}.{child}" for one nested under a parent variable (via DefCompPkgVar.ParentID; nesting is one level deep, verified against a live Empirum DB). bool VariableDefinition.IsCollection is DefCompPkgVar's own Collection flag — verified NOT to correlate with whether the variable has children via ParentID; its exact meaning is unverified against EMC source and should not be used to infer nesting. int VariableDefinition.ComboType/string? VariableDefinition.ComboTypeName are DefCompPkgVar's data/UI type (distinct from the unrelated Type column, which is the Computer/User/OS/Group scope, not exposed here) — see VariableDefinitionDbRepository.ComboTypeNames for the mapping, sourced from the EMC repo's authoritative EVarControlType enum (Library/Intern/Database/VariablesAccess/VariableDefinition.h), the C++ type backing the Administration console's variable-definition editor.

Field	Type	Required	Description
`varId`	integer (int32)	Yes	Variable definition ID.
`designation`	string	Yes	Designation.
`dottedName`	string	Yes	Fully qualified (dotted) variable name.
`description`	string, nullable	Yes	Description of the variable.
`defaultValue`	string, nullable	Yes	Default value.
`isCollection`	boolean	Yes	DefCompPkgVar's own Collection flag. Does not indicate whether other variables nest under this one — check DottedName/other definitions' ParentID for that.
`comboType`	integer (int32)	Yes	The variable's raw data/UI type code from DefCompPkgVar.ComboType. See comboTypeName for its name when known.
`comboTypeName`	string, nullable	Yes	The friendly name for comboType (Text/Number/Date/Time/DateAndTime/ComboBox/Checkbox/IpAddress/Dropdown/UserDefined/DropdownExt/AdBrowse/Password/Scheduler/Timeframe), or null if comboType is a value outside this known set.

GET /api/variable-definitions/{varId}

Returns a single Variable Definition by its VarID.

Required role: package.read

Parameters

Name	In	Type	Required	Description
`varId`	path	integer (int32)	Yes	Variable definition ID.

Responses

Status	Description	Schema
`200`	OK	VariableDefinition

Response fields (VariableDefinition):

Field	Type	Required	Description
`varId`	integer (int32)	Yes	Variable definition ID.
`designation`	string	Yes	Designation.
`dottedName`	string	Yes	Fully qualified (dotted) variable name.
`description`	string, nullable	Yes
`defaultValue`	string, nullable	Yes	Default value.
`isCollection`	boolean	Yes	DefCompPkgVar's own Collection flag. Does not indicate whether other variables nest under this one — check DottedName/other definitions' ParentID for that.
`comboType`	integer (int32)	Yes	The variable's raw data/UI type code from DefCompPkgVar.ComboType. See comboTypeName for its name when known.
`comboTypeName`	string, nullable	Yes	The friendly name for comboType (Text/Number/Date/Time/DateAndTime/ComboBox/Checkbox/IpAddress/Dropdown/UserDefined/DropdownExt/AdBrowse/Password/Scheduler/Timeframe), or null if comboType is a value outside this known set.

GET /api/variable-definitions/{varId}/computers

Inverse search: returns every computer with an explicit direct value set for this VarID.

Required role: package.read

Parameters

Name	In	Type	Required	Description
`varId`	path	integer (int32)	Yes	Variable definition ID.
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfVariableDefinitionComputerAssignment

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

A computer with a direct CompVariables row for a given VarID — not an inherited or effective value, no precedence applied. Returned by GET /api/variable-definitions/{varId}/computers — the inverse-search "which computers have this variable set" query. Never values coming from an inherited/effective resolution, and never values assigned via a Variable Configuration (VaPaConfigurations — a separate, unrelated mechanism, see DOMAIN_SEMANTICS.md).

Field	Type	Required	Description
`clientId`	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`hostname`	string	Yes	Hostname of the computer.
`value`	string, nullable	Yes

GET /api/variable-definitions/{varId}/groups

Inverse search: returns every group with an explicit direct value set for this VarID.

Required role: package.read

Parameters

Name	In	Type	Required	Description
`varId`	path	integer (int32)	Yes	Variable definition ID.
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfVariableDefinitionGroupAssignment

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

A group with a direct GroupVariables row for a given VarID — not an inherited or effective value, no ancestor precedence applied. Returned by GET /api/variable-definitions/{varId}/groups — the inverse-search "which groups have this variable set" query. Never values coming from an inherited/effective resolution, and never values assigned via a Variable Configuration (VaPaConfigurations — a separate, unrelated mechanism, see DOMAIN_SEMANTICS.md).

Field	Type	Required	Description
`groupId`	string (uuid)	Yes	Deployment group ID (GUID).
`name`	string	Yes	Name of the variable.
`value`	string, nullable	Yes

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).

Required role: package.read

Parameters

Name	In	Type	Required	Description
`varId`	path	integer (int32)	Yes	Variable definition ID.
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfVariableDefinitionConfigurationAssignment

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

A Variable Configuration (VaPaConfigurations) with an explicit entry for a given VarID — matched via VaPaConfigurationsVariables.Key, which stores the variable's dotted "{parent}.{child}" name (or bare Designation for a top-level variable), not a VarID foreign key (live-verified — see VariableDefinitionDbRepository.GetVariableConfigurationAssignments). Returned by GET /api/variable-definitions/{varId}/variable-configurations — the inverse-search "which configurations contain this variable" query, analogous to .../computers and .../groups. The value stored here only takes effect once the configuration is assigned to a group (POST /api/group/{id}/variable-configurations) — it is never an inherited/effective value on its own.

Field	Type	Required	Description
`configurationId`	integer (int32)	Yes	Variable Configuration ID.
`configGuid`	string (uuid)	Yes	Variable Configuration GUID.
`name`	string	Yes	Name of the variable.
`value`	string	Yes

GET /api/variable-definitions/{varId}/children

Returns every child variable definition of this VarID.

Required role: package.read

Parameters

Name	In	Type	Required	Description
`varId`	path	integer (int32)	Yes	Variable definition ID.
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfVariableDefinitionChild

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

One child variable definition of a parent variable (DefCompPkgVar.ParentID pointing at the parent's VarID) — returned by GET /api/variable-definitions/{varId}/children, the answer to "what must a caller supply when creating a new collection entry via POST .../variables/{varId}/collection". Not specific to collection variables: any variable with children returns them here, since ParentID nesting exists independently of the Collection flag (see VariableDefinition.IsCollection's doc comment). bool VariableDefinitionChild.IsRequired is derived — true exactly when VariableDefinition VariableDefinitionChild.Definition's DefaultValue is null — mirroring the same rule VariableCollectionRules.Validate applies when accepting a collection-entry POST body, so what this endpoint reports can never drift from what the write path actually enforces.

Field	Type	Required	Description
`definition`	VariableDefinition	Yes	Definition.
`isRequired`	boolean	Yes	True when this child has no DefaultValue and must be supplied explicitly in a POST .../collection body; false when omitting it falls back to defaultValue (an empty-string default still counts as set).

POST /api/variable-definitions/search

Searches Variable Definitions by name (matches either the raw Designation or the dotted "{parent}.{child}" form).

Required role: package.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Request body (required, application/json, schema VariableDefinitionSearchFilter)

Field	Type	Required	Description
`name`	string, nullable	No	Substring match on the variable's Designation or dotted name (e.g. "SQLINSTANCE" or "SUBDEPOT_SERVICES.SQLINSTANCE").

Example request body (placeholder values):

{
    "name": "string"
}

Responses

Status	Description	Schema
`200`	OK	PagedResultOfVariableDefinition

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`varId`	integer (int32)	Yes	Variable definition ID.
`designation`	string	Yes	Designation.
`dottedName`	string	Yes	Fully qualified (dotted) variable name.
`description`	string, nullable	Yes	Description of the variable.
`defaultValue`	string, nullable	Yes	Default value.
`isCollection`	boolean	Yes	DefCompPkgVar's own Collection flag. Does not indicate whether other variables nest under this one — check DottedName/other definitions' ParentID for that.
`comboType`	integer (int32)	Yes	The variable's raw data/UI type code from DefCompPkgVar.ComboType. See comboTypeName for its name when known.
`comboTypeName`	string, nullable	Yes	The friendly name for comboType (Text/Number/Date/Time/DateAndTime/ComboBox/Checkbox/IpAddress/Dropdown/UserDefined/DropdownExt/AdBrowse/Password/Scheduler/Timeframe), or null if comboType is a value outside this known set.

Variable Configurations

Variable Configurations (named collections of variable values).

Method	Path	Summary
GET	`/api/variable-configurations`	Returns a paged list of all Variable Configurations.
GET	`/api/variable-configurations/{id}`	Returns a single Variable Configuration by its id.
POST	`/api/variable-configurations/search`	Searches Variable Configurations by name.

GET /api/variable-configurations

Returns a paged list of all Variable Configurations.

Required role: package.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfVariableConfigurationSummary

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Variable Configuration without the nested Variables list — returned by the list and search endpoints, which don't need per-configuration variable detail. Fetch a single configuration by id for the full VariableConfiguration including Variables.

Field	Type	Required	Description
`id`	integer (int32)	Yes	ID of the Variable Configuration.
`configGuid`	string (uuid)	Yes	Variable Configuration GUID.
`name`	string	Yes	Name of the Variable Configuration.
`description`	string, nullable	Yes	Description of the Variable Configuration.
`createdDate`	string (date-time)	Yes	Creation date.
`lastUpdated`	string (date-time)	Yes	Time of the last update (UTC).

GET /api/variable-configurations/{id}

Returns a single Variable Configuration by its id.

Required role: package.read

Parameters

Name	In	Type	Required	Description
`id`	path	integer (int32)	Yes	Variable Configuration ID.

Responses

Status	Description	Schema
`200`	OK	VariableConfiguration

Response fields (VariableConfiguration):

Field	Type	Required	Description
`id`	integer (int32)	Yes
`configGuid`	string (uuid)	Yes	Variable Configuration GUID.
`name`	string	Yes
`description`	string, nullable	Yes
`createdDate`	string (date-time)	Yes	Creation date.
`lastUpdated`	string (date-time)	Yes	Time of the last update (UTC).
`variables`	array of VariableConfigurationVariable	Yes	Variables.

POST /api/variable-configurations/search

Searches Variable Configurations by name.

Required role: package.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Request body (required, application/json, schema VariableConfigurationSearchFilter)

Field	Type	Required	Description
`name`	string, nullable	No	Substring match on the Variable Configuration name.
`variableKey`	string, nullable	No	Matches configurations containing a variable whose key matches this pattern. '' wildcard: "DEPLOY_" (starts-with), "_PATH" (ends-with), "TARGET" (contains). Without '', defaults to substring match.

Example request body (placeholder values):

{
    "name": "string",
    "variableKey": "string"
}

Responses

Status	Description	Schema
`200`	OK	PagedResultOfVariableConfigurationSummary

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

Field	Type	Required	Description
`id`	integer (int32)	Yes	ID of the Variable Configuration.
`configGuid`	string (uuid)	Yes	Variable Configuration GUID.
`name`	string	Yes	Name of the Variable Configuration.
`description`	string, nullable	Yes	Description of the Variable Configuration.
`createdDate`	string (date-time)	Yes	Creation date.
`lastUpdated`	string (date-time)	Yes	Time of the last update (UTC).

System

Backend version information, depot servers and depot synchronization.

Method	Path	Summary
GET	`/api/system`	Returns Empirum database version, patch management catalog metadata, and the REST API assembly version.
GET	`/api/system/sync-jobs`	Lists depot sync jobs with their last/next run and result, newest first (EMC DepotSync dialog, sync-jobs grid).
POST	`/api/system/sync-jobs`	Triggers an out-of-schedule depot sync job (enqueues a StartSync command for the depot's sync component).
GET	`/api/system/sync-jobs/depots`	Lists all depot servers with their sync-component heartbeat (online/offline/pending/unknown).
GET	`/api/system/depot-servers`	Lists all assignable depot servers (clients with the Empirum Depot Server or Master Server role).

GET /api/system

Returns Empirum database version, patch management catalog metadata, and the REST API assembly version.

Required role: computer.read

Responses

Status	Description	Schema
`200`	OK	EmpirumInfo

Response fields (EmpirumInfo):

Field	Type	Required	Description
`dbVersion`	string, nullable	Yes	Empirum database version.
`schema`	string, nullable	Yes	Database schema.
`pmLastSync`	string, nullable	Yes	Last synchronization of the patch catalog.
`pmDefinitionVersion`	string, nullable	Yes	Version of the patch definitions.
`pmDefinitionDate`	string, nullable	Yes	Date of the patch definitions.
`restApiVersion`	string, nullable	Yes	Version of the REST API.
`dbSizeMb`	integer (int64), nullable	No	Database size in MB.
`softwareDeploymentAndUemAgentLogEntries`	integer (int32)	No	Number of software deployment and UEM agent log entries.
`endpointDeviceCount`	integer (int32)	No	Number of managed endpoint devices.
`depotCount`	integer (int32)	No	Number of depot servers.
`softwarePackageCount`	integer (int32)	No	Number of software packages.
`locationUuid`	string (uuid), nullable	No	Location UUID.
`locationName`	string, nullable	No	Location name.

GET /api/system/sync-jobs

Lists depot sync jobs with their last/next run and result, newest first (EMC DepotSync dialog, sync-jobs grid).

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).
`computer`	query	string	No	Filter by computer.

Responses

Status	Description	Schema
`200`	OK	PagedResultOfSyncJobStatus

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

One depot sync job as reported by the depot's sync component (UEMDepotSyncStatusTable).

Field	Type	Required	Description
`computer`	string	Yes	Computer.
`domain`	string	Yes	Domain name.
`jobName`	string	Yes	Job name.
`result`	string	Yes	error \| success \| pending \| running \| canceled
`lastStart`	string (date-time), nullable	Yes	Start of the last run (UTC).
`lastEnd`	string (date-time), nullable	Yes	End of the last run (UTC).
`nextStart`	string (date-time), nullable	Yes	Start of the next scheduled run (UTC).
`sourceServer`	string, nullable	Yes	Source server.
`sourceFolder`	string, nullable	Yes	Source folder.
`targetServer`	string, nullable	Yes	Target server.
`targetFolder`	string, nullable	Yes	Target folder.
`info`	string, nullable	Yes
`syncComponentVersion`	string, nullable	Yes	Version of the depot sync component.
`uemAgentVersion`	string, nullable	Yes	Version of the UEM agent.

POST /api/system/sync-jobs

Triggers an out-of-schedule depot sync job (enqueues a StartSync command for the depot's sync component).

Required role: activation.execute

Request body (required, application/json, schema SyncJobTriggerRequest)

Request body for POST /api/system/sync-jobs — identifies one sync job exactly as EMC's DepotSync dialog does.

Field	Type	Required	Description
`computer`	string	Yes	Computer.
`domain`	string	Yes	Domain name.
`jobName`	string	Yes	Job name.

Example request body (placeholder values):

{
    "computer": "string",
    "domain": "string",
    "jobName": "string"
}

Responses

Status	Description	Schema
`202`	Accepted	SyncJobTriggered
`409`	Conflict	SyncJobAlreadyPending

Response fields (SyncJobTriggered):

202 response for a successfully enqueued out-of-schedule sync job.

Field	Type	Required	Description
`computer`	string	Yes	Computer.
`domain`	string	Yes	Domain name.
`jobName`	string	Yes	Job name.
`requestedAtUtc`	string (date-time)	Yes	Time of the request (UTC).

GET /api/system/sync-jobs/depots

Lists all depot servers with their sync-component heartbeat (online/offline/pending/unknown).

Required role: computer.read

Responses

Status	Description	Schema
`200`	OK	array of DepotServerStatus

Response fields (DepotServerStatus):

Heartbeat status of one depot server (Clients row with the 'Empirum Depot Server' computer role).

Field	Type	Required	Description
`clientId`	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`computer`	string	Yes	Computer.
`domain`	string	Yes	Domain name.
`status`	string	Yes	offline \| online \| pending \| unknown ('unknown' = the depot never reported; also matches old-style depot sync installations)
`lastCheck`	string (date-time), nullable	Yes
`info`	string, nullable	Yes
`syncComponentVersion`	string, nullable	Yes	Version of the depot sync component.
`uemAgentVersion`	string, nullable	Yes	Version of the UEM agent.

GET /api/system/depot-servers

Lists all assignable depot servers (clients with the Empirum Depot Server or Master Server role).

The picker for PUT /api/group/{id}/depot-servers — every entry is a valid assignment target. Includes the master server, unlike GET /api/system/sync-jobs/depots (the sync heartbeat view).

Required role: computer.read

Responses

Status	Description	Schema
`200`	OK	array of DepotServerCatalogEntry

Response fields (DepotServerCatalogEntry):

One assignable depot server (GET /api/system/depot-servers) — a Clients row carrying the 'Empirum Depot Server' or 'Empirum Master Server' computer role (the same set dbo.fnc_IsDepotServer accepts, so every entry is valid for PUT /api/group/{id}/depot-servers). Unlike GET /api/system/sync-jobs/depots (sync heartbeat view), this list includes the master server. Fqdn comes from the client's FQDN variable, falling back to the catalog default.

Field	Type	Required	Description
`clientId`	integer (int32)	Yes	Computer ID (Empirum `client_id`).
`name`	string	Yes	Name of the depot server.
`fqdn`	string, nullable	Yes	Fully qualified domain name.

Tasks

Tracking of externally triggered deployment tasks.

Method	Path	Summary
GET	`/api/tasks`	Lists external tasks (EmpExtTasks tracking ledger), newest first. A task is created when a consumer starts a deployment operation (software install/uninstall, computer or software reinstall, OS install) and is closed asynchronously once the client reported a result. Status 1 = Running, 2 = Finished, 3 = Failed, 4 = Cancelled (defined but unused by current Empirum versions). Finished and failed tasks are purged automatically after a retention period (default 30 days). Timestamps are UTC.
GET	`/api/tasks/{trackingId}`	Gets one external task by its tracking id, including the per-action breakdown (a computer reinstall consists of one OS action plus one action per assigned software package, each with its own status and properties such as ClientId and SoftwareGUID). Mirrors the legacy SOAP `CoreService.GetTaskStatus` poll.

GET /api/tasks

Lists external tasks (EmpExtTasks tracking ledger), newest first. A task is created when a consumer starts a deployment operation (software install/uninstall, computer or software reinstall, OS install) and is closed asynchronously once the client reported a result. Status 1 = Running, 2 = Finished, 3 = Failed, 4 = Cancelled (defined but unused by current Empirum versions). Finished and failed tasks are purged automatically after a retention period (default 30 days). Timestamps are UTC.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).

Responses

Status	Description	Schema
`200`	OK	PagedResultOfExternalTask

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

External task tracking record (EmpExtTasks) — created when an API consumer starts a deployment operation (install/uninstall/reinstall) and polled by that consumer until the client reported a result. Finished/failed tasks are purged by a cleanup job after a TTL (default 30 days), so a formerly valid tracking id legitimately turning 404 means "processed and cleaned up".

Field	Type	Required	Description
`trackingId`	string (uuid)	Yes	Public tracking GUID (`EmpExtTasks.RefID`) handed out by the operation that created the task.
`taskName`	string, nullable	Yes	Kind of task, e.g. `InstallSoftwareOnClient`, `UninstallSoftwareOnClient`, `ReinstallClient`, `ReinstallSoftware`, `InstallOSOnClient`, `RestoreClient`.
`status`	integer (int32)	Yes	Raw status: 1 = running, 2 = finished, 3 = failed, 4 = cancelled (defined but never written by current Empirum code).
`statusLabel`	string	Yes	`Running` / `Finished` / `Failed` / `Cancelled` / `Unknown` (legacy TaskStatus contract wording).
`errorText`	string, nullable	Yes	Failure detail; may transiently hold a retry marker (`Attempt N`) while the automatic install retry loop is active.
`startedAt`	string (date-time)	Yes	Task creation time (UTC).
`finishedAt`	string (date-time), nullable	Yes	Set when the last action reported a terminal status (UTC).
`actions`	array of ExternalTaskAction, nullable	No	Per-action breakdown (a reinstall task = one OS action plus one action per software package). Populated on the single-task endpoint only; null in list responses.

GET /api/tasks/{trackingId}

Gets one external task by its tracking id, including the per-action breakdown (a computer reinstall consists of one OS action plus one action per assigned software package, each with its own status and properties such as ClientId and SoftwareGUID). Mirrors the legacy SOAP CoreService.GetTaskStatus poll.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`trackingId`	path	string (uuid)	Yes	Tracking ID (GUID) returned by the triggering operation.

Responses

Status	Description	Schema
`200`	OK	ExternalTask

Response fields (ExternalTask):

Field	Type	Required	Description
`trackingId`	string (uuid)	Yes	Public tracking GUID (`EmpExtTasks.RefID`) handed out by the operation that created the task.
`taskName`	string, nullable	Yes	Kind of task, e.g. `InstallSoftwareOnClient`, `UninstallSoftwareOnClient`, `ReinstallClient`, `ReinstallSoftware`, `InstallOSOnClient`, `RestoreClient`.
`status`	integer (int32)	Yes	Raw status: 1 = running, 2 = finished, 3 = failed, 4 = cancelled (defined but never written by current Empirum code).
`statusLabel`	string	Yes	`Running` / `Finished` / `Failed` / `Cancelled` / `Unknown` (legacy TaskStatus contract wording).
`errorText`	string, nullable	Yes	Failure detail; may transiently hold a retry marker (`Attempt N`) while the automatic install retry loop is active.
`startedAt`	string (date-time)	Yes	Task creation time (UTC).
`finishedAt`	string (date-time), nullable	Yes	Set when the last action reported a terminal status (UTC).
`actions`	array of ExternalTaskAction, nullable	No	Per-action breakdown (a reinstall task = one OS action plus one action per software package). Populated on the single-task endpoint only; null in list responses.

Queues

Backend task queues (patch download, hash creation, package import).

Method	Path	Summary
GET	`/api/queues`	Lists pending and running backend tasks from the BTQH (BackendTaskQueueHost) plugin queues, newest first — the REST equivalent of EMC's "Back-end Tasks → Back-end Task Queue" dialog. Each Empirum backend plugin has its own queue: `PM` (patch management jobs: RecreatePatchGroup, PatchDownload, CheckTestGroups), `SWM` (software depot jobs: ImportPackage, CreateHashes), `PE` (pre-boot/driver jobs), `PMScan` (patch scan processing), `Scheduler` (cyclic tasks), `Server` (server-side jobs, e.g. ExecuteSP), `CoreTracking` (watchdog jobs polling external task status); installations may add further queues (e.g. VDI). Status 1 = Queued (waiting, including retries scheduled via `executionTime` = not-before time), 2 = Running. The queue host deletes an entry once its job completed, so entries appear while work is pending and disappear when processed — an empty list means the backend is idle. All timestamps are UTC.
GET	`/api/queues/names`	Lists the backend queue names available in this Empirum installation (valid values for the `queue` filter of `GET /api/queues`).

GET /api/queues

Lists pending and running backend tasks from the BTQH (BackendTaskQueueHost) plugin queues, newest first — the REST equivalent of EMC's "Back-end Tasks → Back-end Task Queue" dialog. Each Empirum backend plugin has its own queue: PM (patch management jobs: RecreatePatchGroup, PatchDownload, CheckTestGroups), SWM (software depot jobs: ImportPackage, CreateHashes), PE (pre-boot/driver jobs), PMScan (patch scan processing), Scheduler (cyclic tasks), Server (server-side jobs, e.g. ExecuteSP), CoreTracking (watchdog jobs polling external task status); installations may add further queues (e.g. VDI). Status 1 = Queued (waiting, including retries scheduled via executionTime = not-before time), 2 = Running. The queue host deletes an entry once its job completed, so entries appear while work is pending and disappear when processed — an empty list means the backend is idle. All timestamps are UTC.

Required role: computer.read

Parameters

Name	In	Type	Required	Description
`skip`	query	integer (int32)	No	Number of items to skip (paging).
`top`	query	integer (int32)	No	Maximum number of items to return (page size).
`queue`	query	string	No	Optional queue name filter (e.g. `PM`, `SWM`), case-insensitive; an unknown name yields an empty page.

Responses

Status	Description	Schema
`200`	OK	PagedResultOfQueueEntry

The response is a paged result (items, skip, top, totalCount, hasMore). Fields of each item:

One pending or running backend task from a BTQH (BackendTaskQueueHost) plugin queue (ActivationQueue_* tables) — the same data EMC shows under "Back-end Tasks → Back-end Task Queue". Rows exist only while work is pending or running; the queue host deletes the row once the job completed.

Field	Type	Required	Description
`queue`	string	Yes	Queue name = table suffix, e.g. `PM`, `SWM`, `PE`, `PMScan`, `Scheduler`, `Server`, `CoreTracking` (installs may add more, e.g. `VDI`).
`jobId`	integer (int32)	Yes	Identity of the queue row (unique per queue, not across queues).
`objectId`	string, nullable	Yes	Id of the affected object; meaning depends on ObjectType (client id, software GUID, ...).
`objectType`	integer (int32)	Yes	Raw `ObjectType.TypeId` of the affected object.
`objectTypeName`	string, nullable	Yes	Machine-readable type name from the `ObjectType` catalog (e.g. `Computer`, `Software`); null when the id is not in the catalog.
`objectTypeDescription`	string, nullable	Yes	Human-readable type description from the catalog.
`command`	string	Yes	Raw command the consuming plugin executes (e.g. `RecreatePatchGroup`, `ImportPackage`, `CreateHashes`).
`activity`	string	Yes	EMC's "Activity" display text for (ObjectType, Command) from `VDI_type_command_mapping`; falls back to Command when unmapped.
`status`	integer (int32)	Yes	Raw status: 1 = queued (incl. scheduled retries), 2 = running.
`statusLabel`	string	Yes	`Queued` / `Running` / `Unknown` (EMC wording).
`insertedAt`	string (date-time), nullable	Yes	When the job was enqueued (UTC).
`executionTime`	string (date-time), nullable	Yes	Not-before time (UTC): the host skips the job until this time — set for scheduled/cyclic jobs and for retries after a transient failure. Null = run ASAP.
`serverId`	integer (int32), nullable	Yes	Empirum server the job is bound to; 0/null = any.

GET /api/queues/names

Lists the backend queue names available in this Empirum installation (valid values for the queue filter of GET /api/queues).

Required role: computer.read

Responses

Status	Description	Schema
`200`	OK	array of string

Service Endpoints

Service-level endpoints of the REST API host.

Method	Path	Summary
GET	`/health`	Returns the health status of the REST API service. Use it for monitoring and connectivity checks.
POST	`/admin/logout`	Signs the current user out of the web-based principal management.

GET /health

Returns the health status of the REST API service. Use it for monitoring and connectivity checks.

Required role: none (no authentication required)

Responses

Status	Description	Schema
`200`	OK	–

POST /admin/logout

Signs the current user out of the web-based principal management.

Responses

Status	Description	Schema
`200`	OK	–

Empirum Rest-API Reference

Contact Us

Overview

Common Request Details

Operations per Area

Authentication

POST /api/auth/token

Administration

GET /api/admin/principals

POST /api/admin/principals

GET /api/admin/principals/{id}

PUT /api/admin/principals/{id}

DELETE /api/admin/principals/{id}

GET /api/admin/local-principals

POST /api/admin/local-principals

GET /api/admin/local-principals/{id}

PUT /api/admin/local-principals/{id}

DELETE /api/admin/local-principals/{id}

PATCH /api/admin/local-principals/{id}/revoke

GET /api/admin/roles

GET /api/admin/features

Computers

GET /api/computer

POST /api/computer

GET /api/computer/{id}

PATCH /api/computer/{id}

DELETE /api/computer/{id}

POST /api/computer/search

GET /api/computer/patch-status

POST /api/computer/software-search

POST /api/computer/distribution-history/search

GET /api/computer/issues/low-disk

GET /api/computer/issues/battery-wear

GET /api/computer/issues/bitlocker-off

GET /api/computer/issues/pending-reboot

GET /api/computer/issues/stale-agent

GET /api/computer/issues/stale-inventory

GET /api/computer/issues/failed-deployment

GET /api/computer/issues/shared-package-failure

GET /api/computer/issues/shared-package-failure/devices

GET /api/computer/issues/missing-patch

GET /api/computer/issues/stale-deployment

GET /api/computer/issues/agent-suspended

GET /api/computer/issues/overview

GET /api/computer/{id}/issues

GET /api/computer/{id}/security-posture

GET /api/computer/{id}/system-info

GET /api/computer/{id}/variables

POST /api/computer/{id}/variables/search

PUT /api/computer/{id}/variables/{varId}

GET /api/computer/{id}/variables/{varId}/collection

POST /api/computer/{id}/variables/{varId}/collection

PATCH /api/computer/{id}/variables/{varId}/collection/{collectionId}

DELETE /api/computer/{id}/variables/{varId}/collection/{collectionId}

GET /api/computer/{id}/reboot-status

GET /api/computer/{id}/groups

GET /api/computer/{id}/packages/{packageId}/groups

GET /api/computer/{id}/agent-template

GET /api/computer/{id}/os-image-sku

GET /api/computer/{id}/pxe-bootimage

GET /api/computer/{id}/language-packs

GET /api/computer/{id}/uem-agent

GET /api/computer/{id}/health

GET /api/computer/{id}/software-deployment

GET /api/computer/{id}/patch-status

POST /api/computer/{id}/patches-search

GET /api/computer/{id}/setup-error-log

GET /api/computer/{id}/distribution-history

GET /api/computer/{id}/inventory/installed-software

GET /api/computer/{id}/inventory/services

GET /api/computer/{id}/inventory/disks

GET /api/computer/{id}/inventory/batteries

GET /api/computer/{id}/inventory/network-adapters

GET /api/computer/{id}/inventory/printers

GET /api/computer/{id}/inventory/bios

GET /api/computer/{id}/inventory/computer-system

GET /api/computer/{id}/inventory/video-controllers

GET /api/computer/{id}/inventory/monitors

GET /api/computer/{id}/inventory/processors

GET /api/computer/{id}/inventory