Release Notes REST API
Pre-Release Changes
Table of Contents
Empirum REST API v1 0.6.0 – Release Notes (from 0.5.2)
This release adds full support for Variables — reading, setting, and managing Empirum's computer and group variables (including collection-type variables and inheritance resolution) directly through the REST API, plus a new Variable Definitions catalog endpoint group for looking up variable metadata and where a variable is used. This is a purely additive release — no existing endpoints, request/response schemas, or roles were changed or removed.
Preview / pre-release. This REST API is an early preview and will later be fully integrated into Empirum. Endpoints, payloads, roles, and behavior may change without notice.
New: Computer Variable Endpoints
Read, set, and manage variable values directly on a computer, including collection-type variables (bundles of related values).
| Method | Path | Description | Requires Role |
|---|---|---|---|
| GET | /api/computer/{id}/variables |
Lists this computer's directly-assigned variable value(s). | computer.read |
| POST | /api/computer/{id}/variables/search |
Resolves a single computer variable's value, with optional inheritance resolution. | computer.read |
| PUT | /api/computer/{id}/variables/{varId} |
Sets this computer's own (direct) value for a scalar (non-collection) variable. A null or omitted value deletes the override, falling back to inheritance/catalog default on later reads. | computer.write |
| GET | /api/computer/{id}/variables/{varId}/collection |
Lists this computer's direct entries (bundles) for a collection variable. | computer.read |
| POST | /api/computer/{id}/variables/{varId}/collection |
Adds one new entry (bundle) to a collection variable on this computer. | computer.write |
| PATCH | /api/computer/{id}/variables/{varId}/collection/{collectionId} |
Partially updates one existing variable collection entry. | computer.write |
| DELETE | /api/computer/{id}/variables/{varId}/collection/{collectionId} |
Deletes an entire variable collection entry (all its child values). | computer.write |
New: Group Variable Endpoints
The same read/set/manage capability as computer variables, applied to deployment groups.
Group variable resolution only considers ancestor group inheritance — unlike computer variables, a group has no "own computer value" tier.
| Method | Path | Description | Requires Role |
|---|---|---|---|
| GET | /api/group/{id}/variables |
Lists this group's directly-assigned variable value(s). | group.read |
| POST | /api/group/{id}/variables/search |
Resolves a single group variable's value, with optional ancestor inheritance resolution. | group.read |
| PUT | /api/group/{id}/variables/{varId} |
Sets this group's own (direct) value for a scalar (non-collection) variable. A null or omitted value deletes the override, falling back to ancestor/catalog default on later reads. | group.write |
| GET | /api/group/{id}/variables/{varId}/collection |
Lists this group's direct entries (bundles) for a collection variable. No ancestor inheritance. | group.read |
| POST | /api/group/{id}/variables/{varId}/collection |
Adds one new entry (bundle) to a collection variable on this group. | group.write |
| PATCH | /api/group/{id}/variables/{varId}/collection/{collectionId} |
Partially updates one existing collection entry (bundle) on this group. | group.write |
| DELETE | /api/group/{id}/variables/{varId}/collection/{collectionId} |
Deletes an entire variable collection entry (all its child values). | group.write |
New: Variable Definitions Catalog Endpoints
Look up variable metadata (type, default value, parent/child relationships) and find every computer, group, or Variable Configuration that has an explicit value set for a given variable.
| Method | Path | Description | Requires Role |
|---|---|---|---|
| GET | /api/variable-definitions |
Returns a paged list of all Variable Definitions. | package.read |
| POST | /api/variable-definitions/search |
Searches Variable Definitions by name (matches either the raw Designation or the dotted "{parent}.{child}" form). | package.read |
| GET | /api/variable-definitions/{varId} |
Returns a single Variable Definition by its VarID. | package.read |
| GET | /api/variable-definitions/{varId}/children |
Returns every child variable definition of this VarID. | package.read |
| GET | /api/variable-definitions/{varId}/computers |
Inverse search: returns every computer with an explicit direct value set for this VarID. | package.read |
| GET | /api/variable-definitions/{varId}/groups |
Inverse search: returns every group with an explicit direct value set for this VarID. | package.read |
| GET | /api/variable-definitions/{varId}/variable-configurations |
Inverse search: returns every Variable Configuration with an explicit entry for this VarID (the stored value only takes effect once the configuration is assigned to a group). | package.read |
New Schemas
The following data types were added to the OpenAPI document to support the endpoints above: VariableDefinition, VariableDefinitionChild, VariableDefinitionComputerAssignment, VariableDefinitionGroupAssignment, VariableDefinitionConfigurationAssignment, VariableValue, VariableCollectionEntry, SetVariableValueRequest, VariableCollectionEntryRequest, VariableCollectionEntryPatchRequest, VariableDefinitionSearchFilter, VariableValueSearchFilter, and their corresponding paged-result wrappers.
Changed
None. No existing endpoint, request/response schema, or role was modified in this release.
Removed / Deprecated
None.
Upgrade Notes
This is a purely additive release — existing integrations built against v1 0.5.2 continue to work unchanged. Re-import the OpenAPI document (/openapi/v1.json) in Scalar or Postman to pick up the new Variables endpoints.