Host API

Host API is the supplementary API that supports communication between different parts of an app and YouTrack.

How to Use the Host API

When you want your widget to send HTTP requests to YouTrack or communicate with it using any of the YouTrack APIs, you must include a script that registers the widget in YouTrack in the HTML code of the widget.

Here you can see an example of the registration script:

            <script type="module">
                const host = await YTApp.register();
                host.alert('Hello world');
            </script>
        

When you've registered the widget, you can use the Host API to send alerts in YouTrack or invoke functions implemented as custom HTTP handlers.

YTApp Object

YouTrack injects the YTApp object into the widget iframe. Use this object to register the widget with the host application and to read information about the widget context.

Property or Method	Description
`register(plugin)`	Registers the widget in YouTrack and returns the Host API object. The optional `plugin` argument lets the widget expose callback functions to YouTrack. const host = await YTApp.register();
`entity`	The YouTrack entity that hosts the widget, or `null` when the widget doesn't have an entity context. The object always contains `id` and `type`. Depending on the extension point, it can also contain additional fields such as an issue summary, project key, or article summary.
`me`	The current user in the widget context. This object contains basic user profile fields such as `id`, `login`, `name`, `avatarUrl`, and `userType`. To read additional user data, use the YouTrack REST API with `host.fetchYouTrack()` or call a custom HTTP handler.
`locale`	The locale of the current YouTrack user interface.
`widget`	The current widget identifiers, including `id` and `appId`.

Host API Reference

Here is the list of methods and objects that the Host API provides.

alert

This method allows you to send an alert message to YouTrack from within an app.

Parameter	Type	Description	Required
`message`	String	The text of the alert message.	✓

Here you can find a sample code that uses this method:

                const host = await YTApp.register();
                host.alert('Hello world');
            

fetchYouTrack

This method lets the app use the YouTrack REST API.

Parameter	Type	Description	Required
`relativeURL`	String	The relative URL to the REST API endpoint.	✓
`requestParams`	RequestParams	Optional fetch parameters. For additional information, see requestParams below.

Parameter

Type

Description

Required

relativeURL

String

The relative URL to the REST API endpoint.

✓

requestParams

RequestParams

Optional fetch parameters.

For additional information, see requestParams below.

Here you can find a sample code that uses this method:

                const host = await YTApp.register();
                const user = await host.fetchYouTrack(`users/${YTApp.entity.id}?fields=id,login,name`);
            

Here's a sample that contains optional query parameters:

                const ytResponse = await host.fetchYouTrack(
                    'users',
                    {
                        query: {
                            fields: 'id,login,email'
                        }
                    }
                );
            

fetchApp

This method lets the app communicate with the custom HTTP handler and invoke its methods. The fetchApp method is similar to the fetchYouTrack method, but has an additional scope parameter. This parameter lets you indicate whether the request should be made to a scoped or global endpoint.

The fetchApp method parses JSON and returns a ready-to-use response object.

Parameter	Type	Description	Required
`relativeURL`	String	The relative URL to the custom HTTP endpoint. For more details, see HTTP Handlers.	✓
`requestParams`	RequestParams	Optional fetch parameters. For details, see requestParams below.

Here you can find a sample code that uses this method:

                const host = await YTApp.register();
                const appResponse = await host.fetchApp(
                    'backend/demo',
                    {
                        scope: true
                    }
                );
            

Here's a sample GET request with query parameters:

                const appResponse = await host.fetchApp(
                    'backend/demo',
                    {
                        query: {
                            key: '12345',
                            count: 20,
                            filter: true
                        }
                    }
                );
            

Here's a sample POST request with body:

                const appResponse = await host.fetchApp(
                    'backend/demo',
                    {
                        method: 'POST',
                        body: {
                            test: 'test'
                        }
                    }
                );
            

The Host API provides the navigation object to full-page widgets. This object lets a widget read and update the part of the page URL that belongs to the app. Use it when your widget has internal navigation and users need to open, share, or return to a specific screen.

The navigation object is only available for widgets that use full-page extension points, such as MAIN_MENU_ITEM and ADMINISTRATION_MENU_ITEM.

The methods provided by the navigation object are asynchronous and return promises.

For a working example, see the full-page widget in the built-in YouTrack Demo App.

The app-controlled part of the URL is represented by the following object:

                type AppLocation = {
                    pathname: string;
                    search: string;
                    hash: string;
                };
            

Property	Type	Description
`pathname`	String	The custom path segment that follows the part of the app URL controlled by YouTrack.
`search`	String	The query string without the leading `?` character. If the app URL has no query string, this property is an empty string.
`hash`	String	The fragment identifier without the leading `#` character. If the app URL has no fragment identifier, this property is an empty string.

getAppLocation

host.navigation.getAppLocation(): Promise<AppLocation>

Returns an AppLocation object that represents the current app URL.

Here you can find a sample code that reads query parameters from the current app URL:

                    const host = await YTApp.register();
                    const location = await host.navigation.getAppLocation();
                    const params = new URLSearchParams(location.search);
                    const requestType = params.get('requestType');
                

updateAppLocation

host.navigation.updateAppLocation(location: Partial<AppLocation>): Promise<void>

Updates the app URL and adds a new entry to the browser history. Use this method when the user navigates to another screen inside the widget and the browser Back button should return to the previous app URL.

You can update pathname, search, and hash independently. Properties that are not specified in the location object keep their current values.

Parameter	Type	Description	Required
`location`	`Partial<AppLocation>`	The app URL properties to update. This object can contain any combination of `pathname`, `search`, and `hash`.	✓

Here you can find a sample code that updates the app URL when a user opens a specific screen inside the widget:

                    const host = await YTApp.register();
                    const params = new URLSearchParams();
                    params.set('requestType', 'vacation');

                    await host.navigation.updateAppLocation({
                        pathname: '/requests/new',
                        search: params.toString()
                    });
                

replaceAppLocation

host.navigation.replaceAppLocation(location: Partial<AppLocation>): Promise<void>

Replaces the current app URL without adding a new entry to the browser history. Use this method when you need to normalize or clean up the URL without changing how the browser Back button behaves.

You can replace pathname, search, and hash independently. Properties that are not specified in the location object keep their current values.

Parameter	Type	Description	Required
`location`	`Partial<AppLocation>`	The app URL properties to replace. This object can contain any combination of `pathname`, `search`, and `hash`.	✓

Here you can find a sample code that removes a temporary query parameter from the current app URL:

                    const host = await YTApp.register();
                    const location = await host.navigation.getAppLocation();
                    const params = new URLSearchParams(location.search);
                    params.delete('temporaryToken');

                    await host.navigation.replaceAppLocation({
                        search: params.toString()
                    });
                

onAppLocationChange

To handle changes to the app URL, pass the onAppLocationChange callback to YTApp.register().

This callback is invoked when the app URL changes, including cases when the user navigates with the browser Back and Forward buttons.

                    const host = await YTApp.register({
                        onAppLocationChange: (location) => {
                            renderScreen(location.pathname, location.search, location.hash);
                        }
                    });
                

requestParams

The requestParams object is an extended version of the Ring UI RequestParams, which builds upon the Fetch API's RequestInit object with a few key differences.

Unlike RequestInit in the standard Fetch API, RequestParams:

includes the query parameter to pass the query parameters for the call.
automatically provides the necessary call header: "Accepts": "application/json".
automatically stringifies the body parameter.

In addition to the base properties supported by the RequestInit object, requestParams supports the following supplemental properties:

Property	Description
`query`	A JavaScript object containing key-value pairs that are used as query parameters for the HTTP request. For example: const query = { key: '12345', shelterID: 'abc00', count: 20, animals: true };
`scope`	A Boolean property that indicates whether the request should be made to a scoped or global endpoint. Pass `true` for scoped handlers. This ensures that the scope entity will be available for the handler from the context. For more details, see Scope. // appResponse is a parsed JSON: const appResponse = await host.fetchApp('backend/demo', {scope: true}); console.log('test', appResponse.test);

Apps that use the DASHBOARD_WIDGET and MARKDOWN extension points generate a special embedding component each time its widgets are inserted into a dashboard or text field. This component stores the data the widget displays in these locations. As a result, these widgets are supported by a more extensive API that we call the CustomWidgetAPILayer.

Here is the list of additional methods that are supported for these extension points.

setTitle

setTitle(label: string, ?labelUrl: string): void

Sets the text displayed in the widget header. If a value is specified for the labelUrl parameter, the text is set as a link to the target URL.

Only available for widgets that use the DASHBOARD_WIDGET or MARKDOWN extension points.

Parameter	Type	Description	Required
`label`	String	The string that is shown as the widget title.	✓
`labelURL`	String	The address of the target page that opens when a user clicks the widget title. If this optional parameter is not specified, the widget title is set as text only.

setLoadingAnimationEnabled

setLoadingAnimationEnabled(isEnabled: boolean): void

Toggles the image rotation animation for the widget reload icon. Call this method when the widget populates data from a remote server to indicate that a process is running in the background.

Only available for widgets that use the DASHBOARD_WIDGET or MARKDOWN extension points.

Parameter	Type	Description	Required
`isEnabled`	Boolean	Determines whether the widget reload icon rotates or not.	✓

enterConfigMode

enterConfigMode(): void

Invokes configuration mode. When in configuration mode, the visual presentation of the widget changes to indicate that its settings can be updated. The refresh icon is also hidden.

Only available for widgets that use the DASHBOARD_WIDGET or MARKDOWN extension points.

exitConfigMode

exitConfigMode(): void

Exits configuration mode.

setError

setError(e: Error): void

Sets an error state in the widget, displaying an error message or taking other error-handling actions.

Only available for widgets that use the DASHBOARD_WIDGET or MARKDOWN extension points.

Parameter	Type	Description	Required
`e`	Error	The error object that contains details about the error.	✓

clearError

clearError(): void

Clears any previously set error state in the widget.

Only available for widgets that use the DASHBOARD_WIDGET or MARKDOWN extension points.

readCache

readCache(): Promise<unknown>

Reads data previously stored in the cache. Returns a promise that resolves to the cached data.

Only available for widgets that use the DASHBOARD_WIDGET or MARKDOWN extension points.

storeCache

storeCache(data: unknown): Promise<Void>

Stores any object in the client-side cache. Use this method to store populated data locally and display it immediately in the widget, then refresh it from the server. Returns a promise that resolves when the data is successfully stored.

Only available for widgets that use the DASHBOARD_WIDGET or MARKDOWN extension points.

Parameter	Type	Description	Required
`data`	Unknown	Specifies the data to be stored in the cache.	✓

readConfig

readConfig(): Promise<unknown>

Reads the widget configuration data. Returns a promise that resolves to the configuration data.

The schema for the config object must be declared in the settingsSchemaPath property of the widget manifest. Any undeclared payloads are ignored.

Only available for widgets that use the DASHBOARD_WIDGET or MARKDOWN extension points.

storeConfig

storeConfig(config: unknown): Promise<Void>

Stores configuration data for the widget. Exits configuration mode if configuration mode is active.

The schema for the config object must be declared in the settingsSchemaPath property of the widget manifest. Any undeclared payloads are ignored.

Returns a promise that resolves when the configuration data is successfully stored.

Only available for widgets that use the DASHBOARD_WIDGET or MARKDOWN extension points.

Parameter	Type	Description	Required
`config`	Unknown	The configuration data to be stored.	✓

downloadFile

downloadFile(serviceID: string, relativeURL: string, requestParams: unknown, fileName?: string): Promise<void>

Downloads a file from a specified service.

Returns a promise that resolves when the file is successfully downloaded.

Only available for widgets that use the DASHBOARD_WIDGET or MARKDOWN extension points.

Parameter	Type	Description	Required
`serviceID`	String	The ID of the service from which the file will be downloaded.	✓
relativeURL	String	The relative URL path to the file within the service.	✓
requestParams	Unknown	Parameters to be included in the request.	✓
fileName	String	The name of the file to be downloaded. If not specified, the service may provide a default name.

fetchHub

fetchHub(relativeURL: string, requestParams: RequestParams): unknown

Fetches data from the Hub service that is connected to or built into YouTrack. Similar to the fetch method but specifically designed for Hub services.

Returns the fetched data. The return type depends on the information retrieved from the service.

Only available for widgets that use the DASHBOARD_WIDGET or MARKDOWN extension points.

Parameter	Type	Description	Required
`relativeURL`	String	Sets the URL to the Hub service API endpoint. This is the path to the resource that you want to fetch. The URL is relative to the server home URL. For more information, refer to the Hub documentation.	✓
`requestParams`	RequestParams	Optional parameters that you want to include in the request.

For example:

CustomWidgetAPILayer.fetchHub('api/rest/users/me?fields=name,login,profile(avatar(url))')
                .then(response => console.log(response));

The following example shows how to use this method in a POST request:

host.fetchHub('api/rest/users/me', {
                method: 'POST',
                body: {favoriteProjects: []}
                })
                .then(response => console.log(response));

alert

alert(...args: Parameters<(typeof AlertService)['addAlert']>): void

Displays a system alert in the lower left corner of the page.

This is a wrapper for the AlertService component from the JetBrains Ring UI component library.

Only available for widgets that use the DASHBOARD_WIDGET or MARKDOWN extension points.

Parameter	Type	Description	Required
`args`	Parameters	The parameters required by the `addAlert` method of the `AlertService`.	✓

For example:

host.alert('Hello world', 'success', 5000)

removeWidget(): void

Removes the embedded widget from the user interface.

Only available for widgets that use the DASHBOARD_WIDGET or MARKDOWN extension points.

07 May 2026

Developer Portal for YouTrack and Hub Help

Host API

How to Use the Host API

YTApp Object

Host API Reference

alert

fetchYouTrack

fetchApp

navigation

getAppLocation

updateAppLocation

replaceAppLocation

onAppLocationChange

requestParams

Custom Widget API Reference

setTitle

setLoadingAnimationEnabled

enterConfigMode

exitConfigMode

setError

clearError

readCache

storeCache

readConfig

storeConfig

downloadFile

fetchHub

alert

removeWidget