startup-apps-backend-api

Variables

StudioStartupHost

const StudioStartupHost: StartupAppsBackendApi;

StudioHost singleton that provides methods for apps to use on the backend.

Interfaces

BackendAppModule

Extended by

BackendStartupAppModule

Properties

Property	Type
`activateBackend`	() => `Promise`<`void`>
`deactivateBackend`	() => `Promise`<`void`>

BackendStartupAppModule

Extends

BackendAppModule

Properties

Property	Type	Inherited from
`activateBackend`	() => `Promise`<`void`>	`BackendAppModule`.`activateBackend`
`deactivateBackend`	() => `Promise`<`void`>	`BackendAppModule`.`deactivateBackend`
`startupOptions`	() => `Promise`<`StudioHostConfigurableOpts`>	-

DownloadAndOpenArgs

Props for downloading and opening a briefcase via Studio.

Type Parameters

Type Parameter
`T`

Properties

Property	Type	Description
`downloadProps?`	`T`	Can be used to track & display progress. File name and briefcase id will be decided by Studio. Downloaded briefcase will always be a fully qualified one, allowing both pulling and pushing.
`iModelId`	`string`	iModel id
`iTwinId`	`string`	iTwin id
`openFileProps?`	`OpenBriefcaseFileProps`	Props for opening briefcase via Studio. briefcase location and path is fully controlled by Studio.
`upgradeSchemas?`	`UpgradeSchemas`	If set, schema versions will be checked & upgraded if they are outdated. See BriefcaseDb.validateSchemas and BriefcaseDb.upgradeSchemas for more details. Defaults to not upgrading schemas.

SandboxExecuteOptions

Options for executing code in a sandbox. until 2026.09

Properties

Property	Type	Description
`signal?`	`AbortSignal`	Optional abort signal to cancel execution. Aborting will terminate the sandbox. :::caution[Alpha] This API should not be used in production and may be trimmed from a public release. :::
`timeoutMs?`	`number`	Optional timeout in milliseconds. Defaults to 30_000ms. :::caution[Alpha] This API should not be used in production and may be trimmed from a public release. :::

SandboxHandle

Handle returned from StudioStartupHost.createSandbox. until 2026.09 This api is experimental and may change or be removed in future releases for better alternatives.

Methods

execute()

execute(code, options?): Promise<unknown>;

Executes code in the sandbox and returns the result.

Parameters

Parameter	Type	Description
`code`	`string`	The JavaScript code to execute. Use ‘return’ to return a value.
`options?`	`SandboxExecuteOptions`	see SandboxExecuteOptions.

Returns

Promise<unknown>

A promise that resolves with the execution result.

Throws

Error if the sandbox is disposed, execution fails, or times out. Callers should wrap this in a try-catch to handle execution errors gracefully.

Example

try {
  const result = await sandbox.execute("return 2 + 2");
  console.log(result); // 4
} catch (err) {
  console.error("Sandbox execution failed:", err);
  sandbox.exit();
}

Properties

Property	Type	Description
`exit`	() => `void`	Closes the sandbox window and cleans up resources. After calling this, the sandbox is no longer usable. :::caution[Alpha] This API should not be used in production and may be trimmed from a public release. :::

SandboxOptions

Options for creating a sandbox. until 2026.09

Properties

Property	Type	Description
`api?`	`Record`<`string`, `SandboxApiFunction`>	API methods to expose to the sandbox. Each method must be an async function that accepts serializable arguments and returns a serializable value. The sandbox can call these methods via the global `api` object. Example `const sandbox = await StudioStartupHost.createSandbox({ api: { add: async (a: number, b: number) => a + b, greet: async (name: string) =>` Hello, ${name}!`, }, }); const result = await sandbox.execute("return api.add(2, 3)"); // result === 5` :::caution[Alpha] This API should not be used in production and may be trimmed from a public release. :::

StartupAppsBackendApi

Backend API for startup apps, including functions imported from StudioBackendApi.

Extends

StudioBackendApi

Methods

addUserPreferencesSchemaFile()

addUserPreferencesSchemaFile(schemaPath): Promise<void>;

Adds a schema json file to the user preferences.

Parameters

Parameter	Type	Description
`schemaPath`	`string`	Path to the schema json file.

Returns

Promise<void>

Inherited from

StudioBackendApi.addUserPreferencesSchemaFile

appChannel()

appChannel(channel): string;

Wraps given IPC channel name with a prefix matching the app name. Ensures IPC channel is unique among apps. Not using this wrapper might cause IPC channel name clashes among different apps. Use StudioApp.appChannel to wrap the IPC channel in the frontend.

Parameters

Parameter	Type	Description
`channel`	`string`	unique channel name within your app.

Returns

string

channel name that is unique among loaded apps.

Inherited from

StudioBackendApi.appChannel

appInstallPath()

appInstallPath(): string;

gets the locations where the application bundle, assets or schema sub-folders resides

Returns

string

attachRpcInterface()

attachRpcInterface<T>(definition): void;

Attach an RPC interface to the backend.

Type Parameters

Type Parameter
`T` extends `RpcInterface`

Parameters

Parameter	Type	Description
`definition`	`RpcInterfaceDefinition`<`T`>	RPC interface definition.

Returns

void

Inherited from

StudioBackendApi.attachRpcInterface

closeBriefcase()

closeBriefcase(key): void;

closes briefcase connection

Parameters

Parameter	Type	Description
`key`	`string`

Returns

void

deleteBriefcase()

deleteBriefcase(key): Promise<void>;

Delete existing briefcase, releasing its briefcase id. If briefcase is still open, this will close it. Note - should be extremely sparingly. All local changes, including those made by other Studio apps, will be lost. until 2026.09

Parameters

Parameter	Type
`key`	`string`

Returns

Promise<void>

downloadAndOpenBriefcase()

downloadAndOpenBriefcase(args): Promise<BriefcaseDb>;

Opens a briefcase, downloading it if it does not exist on disk.

Parameters

Parameter	Type
`args`	`DownloadAndOpenArgs`<`DownloadBriefcaseProps`>

Returns

Promise<BriefcaseDb>

Throws

error if DownloadAndOpenArgs.upgradeSchema is true and the schema is too old or too new.

finalizeFrontendInitData()

finalizeFrontendInitData(jsonData): void;

Sets the initialization or configuration data for the app’s frontend. This function must be invoked before calling StudioApp.getFrontendInitData() in the frontend. If not invoked, the StudioApp.getFrontendInitData() function will time out. Ideally, finalizeFrontendInitData() should be called at the very beginning of activateBackend().

Parameters

Parameter	Type	Description
`jsonData`	`Record`<`string`, `JSONSchemaType`>	JSON object containing initialization data.

Returns

void

A Promise that resolves when the data is finalized.

Inherited from

StudioBackendApi.finalizeFrontendInitData

getLocations()

getLocations(): Promise<StudioLocations>;

Returns the locations of folders used by iTwin Studio for storing application-specific files.

Returns

Promise<StudioLocations>

Inherited from

StudioBackendApi.getLocations

getUrlEnvironmentPrefix()

getUrlEnvironmentPrefix(): UrlEnvironmentPrefix;

Returns

UrlEnvironmentPrefix

the current environment prefix iTwinStudio is in.

Note

it returns url prefix like “dev-”, “qa-” or ""

Inherited from

StudioBackendApi.getUrlEnvironmentPrefix

getUserEntitlement()

getUserEntitlement(iTwinId): Promise<Entitlement>;

Get user entitlement for the application.

Parameters

Parameter	Type	Description
`iTwinId`	`string`	Id of the iTwin.

Returns

Promise<Entitlement>

User entitlement information.

getUserPreference()

getUserPreference(preferenceName): undefined | JSONSchemaType;

Gets a user preference from the user preferences.

Parameters

Parameter	Type	Description
`preferenceName`	`string`	Name of the preference.

Returns

undefined | JSONSchemaType

Inherited from

StudioBackendApi.getUserPreference

initializeTelemetry()

initializeTelemetry(
   instrumentalKey,
   enableAutoTracking?,
   recordExceptions?): void;

Initialize telemetry service

Parameters

Parameter	Type	Description
`instrumentalKey`	`string`	instrumental key for app insights
`enableAutoTracking?`	`boolean`	allow you to configure autoTracking for appInsights, false by default.
`recordExceptions?`	`boolean`	allow Studio to post unhandled exceptions for you, true by default.

Returns

void

Throws

if instrumental key is undefined or empty string then this method throws

Inherited from

StudioBackendApi.initializeTelemetry

logError()

logError(error, metaData?): void;

Logs an error, with the category being the app name.

Parameters

Parameter	Type	Description
`error`	`string`	Error message.
`metaData?`	`LoggingMetaData`	Additional metadata.

Returns

void

Note

Please use studio-cli helpers migrate-to-logger path/to/src --logCategory category to migrate to Logger apis.

Inherited from

StudioBackendApi.logError

logException()

logException(exception): void;

Logs an exception, with the category being the app name.

Parameters

Parameter	Type	Description
`exception`	`unknown`	Exception object.

Returns

void

Note

Please use studio-cli helpers migrate-to-logger path/to/src --logCategory category to migrate to Logger apis.

Inherited from

StudioBackendApi.logException

logInfo()

logInfo(info, metaData?): void;

Logs an info level message, with the category being the app name.

Parameters

Parameter	Type	Description
`info`	`string`	Info message.
`metaData?`	`LoggingMetaData`	Additional metadata.

Returns

void

Note

Please use studio-cli helpers migrate-to-logger path/to/src --logCategory category to migrate to Logger apis.

Inherited from

StudioBackendApi.logInfo

logTrace()

logTrace(trace, metaData?): void;

Logs a trace, with the category being the app name.

Parameters

Parameter	Type	Description
`trace`	`string`	Trace message.
`metaData?`	`LoggingMetaData`	Additional metadata.

Returns

void

Note

Please use studio-cli helpers migrate-to-logger path/to/src --logCategory category to migrate to Logger apis.

Inherited from

StudioBackendApi.logTrace

logWarning()

logWarning(warning, metaData?): void;

Logs a warning, with the category being the app name.

Parameters

Parameter	Type	Description
`warning`	`string`	Warning message.
`metaData?`	`LoggingMetaData`	Additional metadata.

Returns

void

Note

Please use studio-cli helpers migrate-to-logger path/to/src --logCategory category to migrate to Logger apis.

Inherited from

StudioBackendApi.logWarning

postFeatureUsage()

postFeatureUsage(featureGuid): Promise<void>;

Posts feature usage to the licensing service.

Parameters

Parameter	Type	Description
`featureGuid`	`string`	Feature guid against which the feature is tracked.

Returns

Promise<void>

Note

Only works in iTwinStudio standard edition in the prod env and iTwinStudio standard edition beta builds for the qa env, and requires a valid GPRID is defined in app.config.json.

postTelemetry()

postTelemetry(telemetry): void;

Sends the telemetry to azure app insights Note: initializeTelemetry needs to be called first before using postTelemetry

Parameters

Parameter	Type	Description
`telemetry`	`StudioTelemetry`	telemetry data to send

Returns

void

Inherited from

StudioBackendApi.postTelemetry

resolveAssetPath()

resolveAssetPath(pathFromProjectRoot): string;

Resolves the path to the asset file.

Parameters

Parameter	Type	Description
`pathFromProjectRoot`	`string`	path to the asset file relative to the project root folder (where package.json is located).

Returns

string

path to the asset file.

Example

const path = StudioHost.resolveAssetPath("assets/my-asset.ext");
// path === "C:/path/to/app/install/dist/assets/my-asset.ext"
fs.readFileSync(path); // read the asset file

Inherited from

StudioBackendApi.resolveAssetPath

runtimeInfo()

runtimeInfo(): StudioHostRuntimeInfo;

runtime information like product flavor and version etc

Returns

StudioHostRuntimeInfo

Inherited from

StudioBackendApi.runtimeInfo

saveUserPreferences()

saveUserPreferences(newUserPreferences): Promise<void>;

Saves the user preferences in the preferences property database.

Parameters

Parameter	Type	Description
`newUserPreferences`	`UserPreferenceObject`	user/overwrite preferences.

Returns

Promise<void>

Inherited from

StudioBackendApi.saveUserPreferences

setBriefcase()

setBriefcase(key): void;

iTwin studio holds a single instance of briefcase connection at a time. To notify the backend about the change of briefcase, call this method on iModel selection and when switching between apps.

Parameters

Parameter	Type	Description
`key`	`string`

Returns

void

setLogLevel()

setLogLevel(minLevel): void;

Set the minimum logging level for an app. Logging category will be the app name, which is used by logging functions logException, logError, logWarning, logInfo and logTrace.

Parameters

Parameter	Type	Description
`minLevel`	`LogLevel`	Least severe level at which messages in the specified category should be displayed

Returns

void

Note

Please use studio-cli helpers migrate-to-logger path/to/src --logCategory category to migrate to Logger apis.

showOpenDialog()

showOpenDialog(options): Promise<OpenDialogReturnValue>;

Shows a “open file” dialog.

Parameters

Parameter	Type	Description
`options`	`OpenDialogOptions`	Electron open dialog options

Returns

Promise<OpenDialogReturnValue>

A Promise that resolves to the open dialog return value

Inherited from

StudioBackendApi.showOpenDialog

showSaveDialog()

showSaveDialog(options): Promise<SaveDialogReturnValue>;

Shows a “save file” dialog.

Parameters

Parameter	Type	Description
`options`	`SaveDialogOptions`	Electron save dialog options

Returns

Promise<SaveDialogReturnValue>

A Promise that resolves to the save dialog return value

Inherited from

StudioBackendApi.showSaveDialog

terminate()

terminate(): void;

Gracefully closes Studio instance that is running this app.

Returns

void

Properties

Property	Type	Description	Inherited from
`checkInternetConnectivity`	() => `Promise`<`InternetConnectivityStatus`>	Performs an in-depth check to determine the current internet connectivity status. Recommended to use after http requests throw. until 2026.09 :::caution[Alpha] This API should not be used in production and may be trimmed from a public release. :::	`StudioBackendApi`.`checkInternetConnectivity`
`createSandbox?`	(`options?`) => `Promise`<`SandboxHandle`>	Provides methods for creating and managing sandboxed execution environments. Sandboxes are hidden BrowserWindows with no network or filesystem access. They also cannot access `require` or `import`. Example `const sandbox = await StudioStartupHost.createSandbox({ api: { add: async (a: number, b: number) => a + b, greet: async (name: string) =>` Hello, ${name}!`, }, }); const result = await sandbox.execute("return api.add(2, 3)"); // result === 5` :::caution[Alpha] This API should not be used in production and may be trimmed from a public release. :::	-
`getActiveBriefcase`	() => `undefined` \| `BriefcaseDb`	-	`StudioBackendApi`.`getActiveBriefcase`
`initializeSentry`	(`initializationOpts`) => `Promise`<`undefined` \| `Scope`>	Initializes Sentry with the provided options. Note Sentry is only initialized in standard flavors of iTwin Studio.	`StudioBackendApi`.`initializeSentry`
`onNewInstance`	(`listener`) => () => `void`	Fired when a new instance of the startup app is run.	-
`trackAnalyticsEvent`	(`event`) => `Promise`<`void`>	Tracks an analytics event using the Amplitude platform. Your app must have a valid GPR ID defined in app.config.json to successfully track events. When naming events, make sure that they are in `Sentence case` like shown in the example below. When providing custom properties, make sure that they are `snake_case` like shown in the example below. Example `trackAnalyticsEvent({ event_name: "Home button clicked", custom_property: "value" });` :::caution[Alpha] This API should not be used in production and may be trimmed from a public release. :::	-

StudioHostConfigurableOpts

Options that an app can provide to customize StudioHost startup. until 2026.09

Properties

Property	Type	Description
`disableITwinSelection?`	`boolean`	when true, the iTwin selection page will be disabled regardless of the value defined in the app.config.json file :::caution[Alpha] This API should not be used in production and may be trimmed from a public release. :::
`nativeHost?`	`NativeHostOpts`	:::caution[Alpha] This API should not be used in production and may be trimmed from a public release. :::
`presentation?`	`Omit`<`PresentationProps`, `"localeDirectories"` \| `"defaultLocale"` \| `"defaultUnitSystem"`>	:::caution[Alpha] This API should not be used in production and may be trimmed from a public release. :::
`rpcManager?`	`object`	:::caution[Alpha] This API should not be used in production and may be trimmed from a public release. :::
`rpcManager.interfaces?`	`RpcInterfaceDefinition`<`RpcInterface`>[]	-

References

StudioHostRuntimeInfo

Re-exports StudioHostRuntimeInfo

StudioTelemetry

Re-exports StudioTelemetry

Type Aliases

DownloadBriefcaseProps

type DownloadBriefcaseProps = Omit<RequestNewBriefcaseArg, "fileName" | "briefcaseId" | "iTwinId" | "iModelId" | "asOf">;

Props for downloading briefcase via Studio. briefcase location, path and briefcase id is fully controlled by Studio. Will always download the latest version.

OpenBriefcaseFileProps

type OpenBriefcaseFileProps = Omit<CoreOpenBriefcaseProps, "fileName">;

Props for opening briefcase via Studio. briefcase location and path is fully controlled by Studio.

SandboxApiFunction()

type SandboxApiFunction = (...args) => Promise<unknown>;

A function that can be exposed to the sandbox. Must be an async function that returns a serializable value.

Parameters

Parameter	Type
…`args`	`any`[]

Returns

Promise<unknown>

Note

Arguments and return values are serialized via the structured clone algorithm.

See

https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm until 2026.09

UpgradeSchemas

type UpgradeSchemas = "afterDownload" | "always" | undefined;

Indicates when to validate & upgrade schemas (if needed).

“afterDownload”: Only upgrade if the briefcase was freshly downloaded.
“always”: Upgrade schemas even if the briefcase was cached. NOTE: Cached briefcases might contain local changes. Upgrade will cause all local changes to be pushed together with schema changes.
undefined: Do not try to upgrade schemas. (default)