# @interopio/manager-api

Source: https://docs.interop.io/manager/changelog/manager-api/index.html

## 5.0

> ### 5.0.0
>
> *Release date: 28.08.2026*
>
> #### Breaking Changes
>
> For more details, see the [Upgrade](https://docs.interop.io/manager/upgrade/index.md#interopiomanagerapi-500) section.
>
> - The type of the `attachment` field of the `AddFeedbackRequest` DTO has been changed from `string` to `File | NodeJSReadStream`.
>
> - The type of the `upload_file_minidump` field of the `CreateCrashRequest` DTO has been changed from `string` to `File | NodeJSReadStream`.
>
> - The declared return type of the `whoAmI()` method has been changed from `Promise<User>` to `Promise<WhoAmIResponse>`. The method has always returned only the `id`, `email`, `apps`, and `groups` fields at runtime; the type now reflects that.
>
> - The following exports have been removed from the `@interopio/manager-api` package:
>
>     - `BaseAPI`
>     - `AuthOptions`
>     - `CustomRequest`
>     - `CustomRequestResponse`
>     - `ClientOptions`
>     - `IOManagerCache`
>     - `IOManagerCacheItem`
>     - `IOManagerLogger`
>     - `IOManagerAsyncSequelizer`
>     - `SanitizedIOManagerApiError`
>     - `IOManagerRequestValidationError`
>     - `CachedClientAPI`
>     - `CachedClientOptions`
>     - `IOManagerConnectionState`
>     - `isIOManagerTimeoutError`
>
> #### New Features
>
> - Added a `ClientAPIV2` class - a client for the **io.Manager** Server V2 user-facing REST API.
>
> - Added a `getFileResultBytes(commandId: string): Promise<Blob>` method to the `Commands` class. It returns the command result file as its own bytes. Note that using this method requires **io.Manager** 4.0 or later.
>
> - Added a `groupsV2` client - a `GroupsV2` class for the **io.Manager** Server `/v2/groups` REST API. It reads, creates, updates, and deletes `stored` groups, and expands a set of group names into the full set of groups and granular permission groups they map to.
>
> - Added an `advancedLayouts` client - an `AdvancedLayouts` class for working with advanced Layouts through the **io.Manager** Server admin REST API. Using this client requires **io.Manager** 4.0 or later.
>
> - Added `getMigration()`, `getMigrationLayouts()`, and `runMigration()` methods to the `AdvancedLayouts` class for reviewing and running the one-time migration of legacy Layouts to advanced Layouts. All three methods require the `IO_MANAGER:LAYOUTS:WRITE` permission group and are available only when advanced Layouts are enabled on the server. Using these methods requires **io.Manager** 4.0 or later.
>
> - Added a `getDump(id: string): Promise<Blob>` method to the `Crashes` class. Use this method to download the binary crash dump file for a given crash ID. The call reuses the client's existing authentication, so no additional credentials need to be supplied.
>
> - Added a `getLogsArchive(options?: GetLogsArchiveOptions): Promise<Blob>` method to the `ServerAPI` class. It returns a zip archive of the log files the **io.Manager** Server writes, including rotated backups. Use the `includeBackups` and `fileNames` options to narrow what the archive contains. Note that using this method requires **io.Manager** 4.0 or later.
>
> - Added an optional `configKeys` parameter to the `systemConfig.getAll()` method. Use this parameter to narrow which config-file names appear in each entry's `configs` map.
>
> - Added an `isSystemConfigFile(name: string): boolean` method to the `systemConfig` client. It reports whether a config-file name is one of the config files the **io.Connect** platform consumes itself, as opposed to a custom config file added for apps to read. Only custom config files are readable by apps through the **io.Manager** client API.
>
> - Added a `browser-platform.json` member to the `ConnectConfigKey` enumeration, so that it names every config file the **io.Connect** platform consumes itself: `system.json`, `themes.json`, `stickywindows.json`, `channels.json`, `logger.json`, and `browser-platform.json`.
>
> - The following methods have been added to the `ManagerLibAPI` interface exposed by the `ManagerLib` export, accessible via the `io.manager` object after the library has been included as an additional library when initializing **io.Connect Desktop** or **io.Connect Browser**. Domain operations are grouped under the `layouts`, `users`, `groups`, and `configs` namespaces:
>
> | New Method | Description |
> |------------|-------------|
> | `users.query(args: QueryByNameRequest): Promise<QueryUsersResponse>` | Looks up users known to **io.Manager** by name. Matching is case-insensitive and partial; results are de-duplicated and sorted alphabetically. |
> | `groups.query(args: QueryByNameRequest): Promise<QueryGroupsResponse>` | Looks up groups known to **io.Manager** by name. Matching is case-insensitive and partial; results are de-duplicated and sorted alphabetically. |
> | `layouts.checkConflict(request: CheckLayoutConflictRequest): Promise<CheckLayoutConflictResult>` | Checks whether saving a Layout with the given identity would conflict with an existing Layout, before the save is submitted. Returns a discriminated union narrowed by the `kind` field - `"advanced"` or `"legacy"` - that exposes the conflicting Layout when one is found, or no `conflict` when the Layout can be saved cleanly. |
> | `checkCapability(capability: ClientCapability): Promise<CapabilityStatus>` | Checks whether a given client-side capability is usable in the current session and, when it isn't, why. Supports both platform-level capabilities (e.g. `ADVANCED_LAYOUTS`) and method-level capabilities prefixed with `API_METHOD_`. |
> | `checkCapabilities(): Promise<Record<ClientCapability, CapabilityStatus>>` | Checks every client-side capability at once, returning a map from each `ClientCapability` identifier to its `CapabilityStatus`. |
> | `configs.list(): Promise<string[]>` | Returns the names of the custom config files set in **io.Manager**. |
> | `configs.get(name: string): Promise<string \| undefined>` | Returns the raw string contents of the named custom config file, or `undefined` if it isn't set. |
> | `configs.onChange(callback, options?: { name?: string }): Promise<UnsubscribeFunction>` | Subscribes to changes in the custom config files set in **io.Manager**. On subscribe, the callback fires once per currently-set file (filtered by `options.name` when set); thereafter it fires on every add, modify, or remove. A removal is signaled by `value: undefined`. |
>
> The `configs` namespace exposes only the custom config files an administrator has added in **io.Manager**. The config files the **io.Connect** platform itself consumes aren't available to apps: naming one of them produces the same result as naming a config file that has never been set.
>
> The existing `fetchData()` method now also accepts a `preferences` opt-in toggle on its `FetchDataArgs` parameter - set it to `true` to refresh the set of app preferences available to the user, alongside apps, Layouts, commands, and configs.
>
> A new `ClientCapability` enumeration has been added alongside the `checkCapability()` method, exported from the `@interopio/manager-api/desktop` and `@interopio/manager-api/browser` sub-path entry points. It provides constants for two flavors of capability identifier - platform-level (e.g. `ADVANCED_LAYOUTS`) and method-level (`API_METHOD_*` constants identifying individual `io.manager.*` methods). For the full list of members, see the [`ClientCapability`](https://docs.interop.io/manager/apis/initiating-interactions-from-io-connect/index.md#types-clientcapability) reference.
>
> The `CapabilityStatus` interface returned by `checkCapability()` and the `CapabilityUnavailableReason` enumeration it reports (`METHOD_NOT_AVAILABLE`, `SERVER_DISABLED`, `SERVER_INCOMPATIBLE`) are exported from the same sub-path entry points. `CapabilityUnavailableReason` is also the `code` carried by the `Error` a member throws when called while unavailable, so a single mapping handles both the up-front check and a `catch` block.
>
> ```javascript
> import { ClientCapability } from "@interopio/manager-api/desktop";
>
> // Refreshing the available apps, Layouts, and preferences.
> await io.manager.fetchData({
>     layouts: true,
>     applications: true,
>     preferences: true
> });
>
> // Looking up users and groups by name.
> const users = await io.manager.users.query({ name: "alice" });
> const groups = await io.manager.groups.query({ name: "traders" });
>
> // Checking whether the chosen identity would conflict with an existing
> // Layout before submitting the save.
> const conflict = await io.manager.layouts.checkConflict({
>     type: "Workspace",
>     name: "my-workspace",
>     accessLevel: "private"
> });
>
> if (conflict.kind === "advanced" && conflict.conflict) {
>     // Prompt the user before overwriting `conflict.conflict`.
> } else if (conflict.kind === "legacy" && conflict.conflict) {
>     // Prompt the user before overwriting `conflict.conflict`.
> }
>
> // Checking client-side capabilities - and learning why one is unavailable.
> const checkConflictStatus = await io.manager.checkCapability(ClientCapability.API_METHOD_LAYOUTS_CHECK_CONFLICT);
> if (!checkConflictStatus.available) {
>     // checkConflictStatus.reason is "METHOD_NOT_AVAILABLE", "SERVER_DISABLED", or "SERVER_INCOMPATIBLE".
> }
>
> // Listing and reading the config files set in io.Manager.
> const names = await io.manager.configs.list();
> const contents = await io.manager.configs.get("my-config.json");
>
> // Subscribing for changes to a specific config file.
> const unsubscribe = await io.manager.configs.onChange(event => {
>     if (event.value === undefined) {
>         // The config file was removed.
>     } else {
>         // The config file was added or modified.
>     }
> }, { name: "my-config.json" });
> ```
>
> > ⚠️ *Note that using these methods requires **io.Manager** 4.0 or later and **io.Connect Desktop** 10.5 (unreleased). For more details, see the [APIs > Initiating Interactions from io.Connect](https://docs.interop.io/manager/apis/initiating-interactions-from-io-connect/index.md) section.*
>
> #### Deprecated Methods
>
> The following methods have been deprecated:
>
> | Deprecated Method | New Method |
> |-------------------|------------|
> | `Commands.getFileResult()` | Use `Commands.getFileResultBytes()` instead. |
> | `ServerAPI.getLog()` | Use `ServerAPI.getLogsArchive()` instead. |
>
> #### Improvements & Bug Fixes
>
> - Corrected the declared return type of the `io.manager.onConnectionStateChange()` method to `Promise<UnsubscribeFunction>`. The method has always returned a `Promise` at runtime; the type now reflects that, so `await` the call to obtain the unsubscribe function.
>
> #### Dependency Changes
>
> The following dependencies have been updated:
>
> - `@interopio/schemas` from version `^9.7.0` to `^10.0.0`

## 4.0

> ### 4.2.0
>
> *Release date: 10.03.2026*
>
> #### New Features
>
> - Added a new `ManagerLib` export that integrates the `@interopio/manager-api` library with the [`@interopio/desktop`](https://www.npmjs.com/package/@interopio/desktop) library in **io.Connect Desktop** projects and the [`@interopio/browser-platform`](https://www.npmjs.com/package/@interopio/browser-platform) and [`@interopio/browser`](https://www.npmjs.com/package/@interopio/browser) libraries in **io.Connect Browser** projects. This export provides [methods for interacting with **io.Manager**](https://docs.interop.io/manager/apis/initiating-interactions-from-io-connect/index.md) from interop-enabled apps running in **io.Connect Desktop** and **io.Connect Browser** - retrieving the connection state, subscribing for connection state changes, and refreshing platform data such as available apps, Layouts, system configuration, and more.
>
> > ⚠️ *Note that using this feature requires **io.Connect Desktop** 10.3 or later and **io.Connect Browser** 4.3 or later.*
>
> New sub-path exports have been added to the library, which expose the `ManagerLib` export for usage in **io.Connect Desktop** and **io.Connect Browser** projects:
>
> | Export | Description |
> |--------|-------------|
> | `@interopio/manager-api/browser` | Exposes the `ManagerLib` export for usage with the `@interopio/browser-platform` and `@interopio/browser` libraries. |
> | `@interopio/manager-api/desktop` | Exposes the `ManagerLib` export for usage with the `@interopio/desktop` library. |
>
> To use the functionalities provided by the `ManagerLib` export, you must include it in the `libraries` array of the configuration object for initializing the respective io.Connect library.
>
> When the io.Connect library has been initialized, a new `manager` property will be available on the io.Connect API object and the following methods will be accessible via the `io.manager` object:
>
> | New Method | Description |
> |------------|-------------|
> | `getConnectionState(): Promise<IOManagerConnectionState>` | Retrieves information related to the state of the connection to **io.Manager**. |
> | `fetchData(args: FetchDataArgs): Promise<void>` | Triggers data refresh from **io.Manager**. You can specify the types of data to be refreshed (e.g. data related to apps, Layouts, system configurations). |
> | `onConnectionStateChange(callback): UnsubscribeFunction` | Notifies when the state of the connection to **io.Manager** changes. Returns an unsubscribe function. |
>
> The following example demonstrates using the `ManagerLib` export in an **io.Connect Desktop** client app:
>
> ```javascript
> import IODesktop from "@interopio/desktop";
> import { ManagerLib } from "@interopio/manager-api/desktop";
>
> // Including the `ManagerLib` export as an additional library.
> const config = { libraries: [ManagerLib] };
>
> const io = await IODesktop(config);
>
> // Retrieving the state of the connection to io.Manager.
> const connectionState = await io.manager.getConnectionState();
>
> // Providing a handler and subscribing for changes in the connection state.
> const handler = connectionState => console.log(`Connection state: ${JSON.stringify(connectionState)}`);
>
> const unsubscribe = io.manager.onConnectionStateChange(handler);
>
> // Refreshing the available apps and Layouts.
> const dataToFetch = {
>     layouts: true,
>     applications: true
> };
>
> await io.manager.fetchData(dataToFetch);
> ```
>
> > ℹ️ *For more details on using the methods in **io.Connect Desktop** and **io.Connect Browser** projects and for a complete API reference, see the [APIs > Initiating Interactions from io.Connect](https://docs.interop.io/manager/apis/initiating-interactions-from-io-connect/index.md) section.*

> ### 4.1.1
>
> *Release date: 24.02.2026*
>
> #### Improvements & Bug Fixes
>
> - Migrated from `zod` to `zod/mini` for a smaller bundle footprint.
>
> - Improved integration between **io.Connect** and **io.Manager**.

> ### 4.1.0
>
> *Release date: 30.01.2026*
>
> #### New Features
>
> - New API methods have been added:
>
> | New Method | Description |
> |------------|-------------|
> | `api.getAllCommandDescriptions(): Promise<AggregatedCommandDescription[]>` | Retrieves all supported commands across all io.Connect platform versions. Each `AggregatedCommandDescription` object of the resulting array describes a unique supported command and contains information about the command type, the command description, version-specific command parameter examples, and a list of the io.Connect platform versions which support the command. |

> ### 4.0.7
>
> *Release date: 15.08.2025*
>
> #### Improvements & Bug Fixes
>
> - Improved integration between **io.Connect** and **io.Manager**.

> ### 4.0.6
>
> *Release date: 15.08.2025*
>
> #### Improvements & Bug Fixes
>
> - Improved integration between **io.Connect** and **io.Manager**.

> ### 4.0.5
>
> *Release date: 15.08.2025*
>
> #### Improvements & Bug Fixes
>
> - Improved integration between **io.Connect** and **io.Manager**.

> ### 4.0.4
>
> *Release date: 15.08.2025*
>
> #### Improvements & Bug Fixes
>
> - Improved integration between **io.Connect** and **io.Manager**.

> ### 4.0.3
>
> *Release date: 12.08.2025*
>
> #### Improvements & Bug Fixes
>
> - Improved integration between **io.Connect** and **io.Manager**.

> ### 4.0.2
>
> *Release date: 08.08.2025*
>
> #### Improvements & Bug Fixes
>
> - Improved integration between **io.Connect** and **io.Manager**.

> ### 4.0.1
>
> *Release date: 07.08.2025*
>
> #### Improvements & Bug Fixes
>
> - Improved integration between **io.Connect** and **io.Manager**.
>
> #### Dependency Changes
>
> The following dependencies have been added to the package:
>
> - `zod` version `^4.0.10`

> ### 4.0.0
>
> *Release date: 11.07.2025*
>
> #### Breaking Changes
>
> - TypeScript types. For more details, see the [Upgrade](https://docs.interop.io/manager/upgrade/index.md#interopiomanagerapi-400) section.
> - The `MatchAll` export has been renamed to `ConfigMatchAll`.
>
> #### Improvements & Bug Fixes
>
> - Added URL encoding to all path and query parameters.
> - Added JSDoc comments to all API methods.
>
> #### Dependency Changes
>
> The following dependencies have been removed from the package:
>
> - `@types/request`
>
> The following dependencies have been updated:
>
> - `@interopio/schemas` from version `^9.2.0` to `^9.7.0`
> - `axios` from version `^1.7.4` to `^1.9.0`
> - `form-data` from version `^4.0.0` to `^4.0.2`
> - `jwt-decode` from version `^3.1.2` to `^4.0.0`

## 3.0

> ### 3.1.0
>
> *Release date: 16.08.2024*
>
> #### New Methods
>
> New API methods have been added:
>
> | New Method | Description |
> |------------|-------------|
> | `api.initialize(): Promise<void>` | Initializes the API client. Calling it is required before using any of the new methods described here. |
> | `api.hasCapability(capability: ServerCapability): boolean` | Checks whether the specified capability is supported by the **io.Manager** Server. Returns `true` if the capability is supported and `false` otherwise. Use the `ServerCapability` enumeration to specify the desired capability - e.g., `api.hasCapability(ServerCapability.ADMIN_API_V2_APP_ADD)`. |
> | `api.appsV2.addApp(app: AddAppRequest): Promise<App>` | Creates a new app definition or throws an error if an app definition with the same `name` property already exists. Returns the created app definition. |
> | `api.appsV2.addOrUpdateApp(app: AddOrUpdateAppRequest): Promise<App>` | Creates a new app definition or updates an existing one if an app definition with the same `name` property already exists. Returns the created or updated app definition. |
> | `api.appsV2.updateApp(app: UpdateAppRequest): Promise<App>` | Updates an app definition or throws an error if an app definition with the specified `name` property isn't found. Returns the updated app definition. |
> | `api.layoutsV2.addLayout(layout: AddLayoutRequest): Promise<Layout>` | Creates a new Layout definition or throws an error if a Layout definition with the same combination of `name`, `type` and `owner` properties already exists. Returns the created Layout definition. |
> | `api.layoutsV2.addOrUpdateLayout(layout: AddOrUpdateLayoutRequest): Promise<Layout>` | Creates a new Layout definition or updates an existing one if a Layout definition with the same `id` property (or the same combination of `name`, `type` and `owner` properties if `id` isn't provided) already exists. Returns the created or updated Layout definition. |
> | `api.layoutsV2.updateLayout(layout: UpdateLayoutRequest): Promise<Layout>` | Updates a Layout definition or throws an error if a Layout definition with the specified `id` property (or the specified combination of `name`, `type` and `owner` properties if `id` isn't provided) isn't found. Returns the updated Layout definition. |
>
> #### Deprecated Methods
>
> The following API methods have been deprecated:
>
> | Deprecated Method | New Method |
> |-------------------|-------------|
> | `api.apps.addOrUpdate()` | Use `api.appsV2.addOrUpdateApp()` instead. |
> | `api.layouts.addCommonLayout()` | Use `api.layoutsV2.addLayout()` instead. |
> | `api.layouts.addLayout()` | Use `api.layoutsV2.addLayout()` instead. |
> | `api.layouts.addUserLayout()` | Use `api.layoutsV2.addLayout()` instead. |
>
> #### Improvements & Bug Fixes
>
> - Audit fix for NPM packages.

## 2.0

> ### 2.0.2
>
> *Release date: 15.05.2024*
>
> #### Improvements & Bug Fixes
>
> - Extended typings for `NumberFilterCondition` and `DateFilterCondition` with `notExists` option.
> - Updated dependencies.
>
> ### 2.0.1
>
> *Release date: 27.03.2024*
>
> #### Improvements & Bug Fixes
>
> - Moved to @interopio/schemas@9.2.0 package.

> ### 2.0.0
>
> *Release date: 22.03.2024*
>
> #### Breaking Changes
>
> - Remove the `dataRequest parameter` from `systemConfig.getAll()`.

## 1.0

> ### 1.6.3
>
> *Release date: 10.02.2024*
>
> #### Improvements & Bug Fixes
>
> - Fixed Axios error interceptor.

> ### 1.6.2
>
> *Release date: 12.01.2024*
>
> #### Improvements & Bug Fixes
>
> - Audit fix for NPM packages.

> ### 1.6.0
>
> *Release date: 29.11.2023*
>
> #### New Features
>
> - Added a response interceptor.
>
> #### Improvements & Bug Fixes
>
> - Updated Axios to from 0.28.0 to 1.6.2.

> ### 1.5.0
>
> *Release date: 15.06.2023*
>
> #### New Features
>
> - Added a `core` option in `GlueInfo`.

> ### 1.4.0
>
> *Release date: 19.05.2023*
>
> #### New Features
>
> - Added a `assignLayoutToUser()` API method.
> - Added a `setExplicitUserItems()` API method.

> ### 1.3.2
>
> *Release date: 16.05.2023*
>
> #### Improvements & Bug Fixes
>
> - Relaxed hello request.

> ### 1.3.1
>
> *Release date: 16.05.2023*
>
> #### Improvements & Bug Fixes
>
> - Relaxed machine configuration.

> ### 1.3.0
>
> *Release date: 27.04.2023*
>
> #### New Features
>
> - Exposed `transformResponse` options.

> ### 1.2.0
>
> *Release date: 31.03.2023*
>
> #### Improvements & Bug Fixes
>
> - Updated to latest `@interopio/schemas`.

> ### 1.1.2
>
> *Release date: 01.11.2022*
>
> #### Improvements & Bug Fixes
>
> - Fixed System Configuration API bug.

> ### 1.1.1
>
> *Release date: 01.11.2022*
>
> #### Improvements & Bug Fixes
>
> - Fixed System Configuration API bug.

> ### 1.1.0
>
> *Release date: 31.10.2022*
>
> #### New Features
>
> - Added a `removeConfigForIdentifier()` method in the System Configuration API.

> ### 1.0.2
>
> *Release date: 23.10.2022*
>
> #### Improvements & Bug Fixes
>
> - Added a `weight` property to `Glue42SystemConfigIdentifier`.

> ### 1.0.1
>
> *Release date: 23.10.2022*
>
> #### Improvements & Bug Fixes
>
> - Made some of the properties of `AuditLog` optional.

> ### 1.0.0
>
> *Release date: 15.10.2022*
>
> #### Breaking Changes
>
> - Removed Node.js core dependencies `fs` and `path` which causes breaking changes in the Client API.

## 0.1

> ### 0.8.0
>
> *Release date: 27.09.2022*
>
> #### New Features
>
> - Added an `unload()` method to the Client API.

> ### 0.7.6
>
> *Release date: 19.09.2022*
>
> #### Improvements & Bug Fixes
>
> - Fixed typings.

> ### 0.7.5
>
> *Release date: 07.06.2022*
>
> #### Improvements & Bug Fixes
>
> - Fixed the `addFeedback()` method.

> ### 0.7.3
>
> *Release date: 07.06.2022*
>
> #### Improvements & Bug Fixes
>
> - Fixed URL joining when using a custom request module.

> ### 0.7.2
>
> *Release date: 07.06.2022*
>
> #### Improvements & Bug Fixes
>
> - Removed `urlJoin()` and fixed URL joining when using a custom request module.

> ### 0.7.0
>
> *Release date: 22.05.2022*
>
> #### New Features
>
> - Added support for passing a custom request library.

> ### 0.6.0
>
> *Release date: 22.03.2022*
>
> #### New Features
>
> - Added a Schema API.

> ### 0.5.0
>
> *Release date: 21.03.2022*
>
> #### New Features
>
> - Added support for [Basic](https://docs.interop.io/manager/authentication/basic/index.md) authentication in `Options`.
> - Added a `password` property in `User`.

> ### 0.4.5
>
> *Release date: 13.03.2022*
>
> #### New Features
>
> - Added a `getGroupsFeatures()` method in the Groups API.