HTTP Handlers

HTTP handlers let you make YouTrack data accessible from custom HTTP endpoints. These handlers extend the REST API so clients can call these endpoints like any other YouTrack REST API endpoint, not just the frontend code for a specific widget. This means you can use HTTP handlers to provision webhooks that can be accessed by third-party services.

YouTrack supports custom HTTP handlers written in JavaScript. The current YouTrack JavaScript implementation is compatible with the latest ECMAScript specification.

Sample HTTP Handler

Here is a sample script that creates an endpoint for handling HTTP GET requests:

            exports.httpHandler = {
                endpoints: [
                    {
                        scope: "issue",
                        method: "GET",
                        path: "/demo",
                        permissions: ['READ_ISSUE', 'READ_ARTICLE'],
                        handle: function (ctx) {
                            ctx.response.json({message: "Hello World"});
                        }
                    }
                ]
            }
        

The following handler accepts JSON in a POST request body and returns it in a JSON response. Save this global handler in a separate JavaScript file from the issue-scoped handler above.

            exports.httpHandler = {
                endpoints: [
                    {
                        scope: "global",
                        method: "POST",
                        path: "/demo",
                        handle: function (ctx) {
                            const body = ctx.request.json();
                            ctx.response.json({receivedBody: body});
                        }
                    }
                ]
            };
        

Use Workflow API Modules in HTTP Handlers

HTTP handlers can use modules from the YouTrack workflow API package @jetbrains/youtrack-scripting-api. For example, use the @jetbrains/youtrack-scripting-api/http module to send requests to external services.

The following sample handler accepts a JSON payload from the client, forwards it to an external service, then returns a value from the service response to the client:

                const http = require('@jetbrains/youtrack-scripting-api/http');

                const SERVICE_URL = 'https://api.example.com';

                exports.httpHandler = {
                    endpoints: [
                        {
                            method: 'POST',
                            path: '/forward',
                            handle: function (ctx) {
                                const requestJson = ctx.request.json();
                                const connection = new http.Connection(SERVICE_URL);

                                connection.addHeader('Content-Type', 'application/json');

                                const serviceResponse = connection.postSync(
                                    '/transform',
                                    null,
                                    JSON.stringify(requestJson)
                                ).json();

                                ctx.response.json({
                                    transformedValue: serviceResponse.transformedValue
                                });
                            }
                        }
                    ]
                };
            

For details about the HTTP module, see http. When the external service requires credentials, store them as secret app settings. For details, see Working with Settings for Secrets.

Schedule Async Functions from HTTP Handlers

HTTP handlers can also schedule asynchronous functions. Use this when the handler should return a response to the caller immediately and continue work after the handler transaction is complete. For example, you can call an external service with postAsync and process its response in a named async function:

                const http = require('@jetbrains/youtrack-scripting-api/http');

                const SERVICE_URL = 'https://api.example.com';

                exports.httpHandler = {
                    endpoints: [
                        {
                            scope: 'project',
                            method: 'POST',
                            path: '/schedule-sync',
                            handle: function (ctx) {
                                const connection = new http.Connection(SERVICE_URL);
                                connection.postAsync('/sync', null, ctx.request.body, 'onSyncResponse');

                                ctx.response.json({status: 'scheduled'});
                            }
                        }
                    ],
                    asyncFunctions: {
                        onSyncResponse: function (ctx) {
                            if (!ctx.response.isSuccess) {
                                console.warn('External sync failed: ' + ctx.response.body);
                            }
                        }
                    }
                };
            

For details about declaring async functions and sharing state across async calls, see Asynchronous Functions.

HTTP Handler API

Here is the reference for the script that implements a custom HTTP handler.

Each script exports one HTTP handler to the exports.httpHandler property. The HTTP handler is declared as an object containing the array of endpoints. It can also contain an optional asyncFunctions object.

Handler Context

The handle function receives a context object as its only argument. This object provides access to the incoming request, the outgoing response, the current user, app settings, app storage, and scope-specific YouTrack entities.

Property	Description
`ctx.currentUser`	The current user who calls the endpoint. This property is an alias for `entities.User.current`. You can use `ctx.currentUser.isInGroup(groupName)` to check membership in a specific group. Starting with YouTrack 2025.3, the `groups` property contains the user's groups.
`ctx.settings`	The app settings configured according to the app's settings schema.
`ctx.globalStorage`	The global storage object provisioned for the app. For details, see App Global Storage.
`ctx.request`	The HTTP request object. For details, see HTTP Request.
`ctx.response`	The HTTP response object. For details, see HTTP Response.
`ctx.issue`, `ctx.project`, `ctx.article`, `ctx.user`	The scope-specific entity for endpoints that use the corresponding scope. For example, an endpoint with `scope: "issue"` receives `ctx.issue`.

For the full list of properties and methods available for YouTrack entities in app scripts, see the User and related JavaScript API reference pages.

Endpoints

Each endpoint contains the following properties:

Property	Description
`scope`	The scope entity of the endpoint. Setting the scope guarantees you that the scope entity will be available in the context of the `handle` function. YouTrack supports the following scopes: `issue`, `project`, `article`, `user`, `global`. Default value: `global`. For more details, see Scope.
`method`	The HTTP method that the endpoint implements. YouTrack supports GET, POST, PUT, and DELETE methods.
`path`	The relative path for accessing the endpoint. A leading slash is optional. For example, `"demo"` and `"/demo"` define the same endpoint path. To use the endpoint in an app, append this path to the name of the handler file and invoke the endpoint via `host.fetchApp()`. Example: `const appResponse = await host.fetchApp('backend/demo', {scope: true});`
`permissions`	Optional permission checks that apply in addition to access to the scope entity and the app's activation and visibility settings. List permission keys in an array. For example, `permissions: ['READ_ISSUE', 'READ_ARTICLE']` requires at least one listed permission. If `permissions` is omitted or the permission list is empty, no additional permission check applies. For endpoints with an `issue`, `article`, or `project` scope, project permissions are checked in the corresponding project. Each permission is referenced using its key. For a complete list of permissions and key values, see App Permissions.
`handle`	The function that YouTrack invokes when someone calls the endpoint with the given method.

Scope

Here you can learn more about available scope values for the HTTP endpoints.

Setting the scope guarantees that the scope entity will be available in the context of the handle function.

If you don't set the scope explicitly, the default value is global.

A single handler can combine global and user endpoints, or it can combine issue, article, and project endpoints. To use endpoints from both groups in one app, declare them in separate handler files. For details, see Scopes for HTTP Handlers.

Scope	Description	Related Extension Points
`issue`	Adds the `ctx.issue` entity to the context of the `handle` function.	`ISSUE_ABOVE_ACTIVITY_STREAM` `ISSUE_BELOW_SUMMARY` `ISSUE_FIELD_PANEL_LAST` `ISSUE_FIELD_PANEL_FIRST` `ISSUE_OPTIONS_MENU_ITEM`
`project`	Adds the `ctx.project` entity to the context of the `handle` function.	`HELPDESK_CHANNEL` `PROJECT_SETTINGS` `PROJECT_TAB`
`article`	Adds the `ctx.article` entity to the context of the `handle` function.	`ARTICLE_OPTIONS_MENU_ITEM` `ARTICLE_BELOW_SUMMARY` `ARTICLE_ABOVE_ACTIVITY_STREAM`
`user`	Adds the `ctx.user` entity to the context of the `handle` function.	`USER_CARD` `USER_PROFILE_SETTINGS`
`global`	The default scope.	Endpoints with this scope are accessible for all frontend extensions.

HTTP Request

HTTP request is an object (ctx.request) that the endpoint receives.

Properties

Here are the properties of the HTTP request object.

Property	Type	Description
`body`	string	The request body.
`bodyAsStream`	Object	A byte stream representation of the request body.
`headers`	Array.<{name: String, value: String}>	A collection of request headers, excluding `Authorization`, `Cookie`, and `Set-Cookie`.
`path`	string	The part of the request path after the handler name, including the leading slash. For an endpoint declared with `path: "demo"` or `path: "/demo"`, this value is `"/demo"`.
`fullPath`	string	The request path without the YouTrack context path. For example, `/api/extensionEndpoints/my-app/backend/demo`.
`method`	string	The HTTP method that the request used. Can be either GET, POST, PUT, or DELETE.
`parameterNames`	Array.<String>	An array of request parameter names.

Functions

Here are the functions that you can use to work with HTTP requests. These JavaScript functions are available on ctx.request inside the endpoint's handle function. The handle function runs whenever the app receives a matching HTTP request.

Function	Return Type	Description
`json()`	JSON	Parses the request body as JSON and returns the resulting value.
`getParameter(name)`	string or null	Returns the first value of the named request parameter, or `null` if the parameter is absent.
`getParameters(name)`	Array.<String>	Returns all values of the named request parameter as an array of strings. Returns an empty array if the parameter is absent.

HTTP Response

The HTTP response object (ctx.response) provides properties and functions for setting the response body, status code, and headers sent to the client.

Properties

Here are the properties of the HTTP response object.

The body and bodyAsStream properties are write-only. You can read and set code.

Property	Type	Description
`body`	string or Object	Sets the response body. To send JSON with the corresponding content type, use `ctx.response.json(object)`.
`bodyAsStream`	Object	Sets the response body from a byte stream.
`code`	number	The HTTP status code. Default value: `200`.

Functions

Here are the functions that you can use to work with HTTP responses. These are referenced by accessing the ctx.response object provided in the handle function of an HTTP handler. These functions let you format responses in JSON or plain text and customize the response header. They modify the response object and do not return a value.

Function	Return type	Description
`json(object)`		Adds the `Content-Type: application/json` HTTP header to the response that the handler returns to the client. The response is presented in the format of a JSON string.
`text(string)`		Adds the `Content-Type: text/plain` HTTP header to the response that the handler returns to the client. The response is presented in the format of a string.
`addHeader(header, value)`		Adds an HTTP header value to the response. If you pass `null` as the value, the corresponding header will be removed from the response. Repeated calls with the same header name add values to that header. YouTrack ignores attempts to set `Content-Security-Policy`, `X-Frame-Options`, `X-Content-Type-Options`, or `X-XSS-Protection` with this function.

Function

Return type

Description

json(object)

Adds the Content-Type: application/json HTTP header to the response that the handler returns to the client. The response is presented in the format of a JSON string.

text(string)

Adds the Content-Type: text/plain HTTP header to the response that the handler returns to the client. The response is presented in the format of a string.

addHeader(header, value)

Adds an HTTP header value to the response. If you pass null as the value, the corresponding header will be removed from the response. Repeated calls with the same header name add values to that header.

YouTrack ignores attempts to set Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, or X-XSS-Protection with this function.

Requirements

You can include additional requirements for the HTTP handler objects. An HTTP handler object has the requirements field that you may use to define the requirements for the script.

For details about how requirements work for JavaScript scripts in YouTrack in the workflow context, see Requirements.

Accessing Custom REST Endpoints

When you call a custom REST endpoint, you invoke its corresponding HTTP handler. The endpoints used are based on the scope property assigned to the handler.

Scope	URL
`issue`	<host>/api/issues/<issueId>/extensionEndpoints/app/handler/endpoint
`article`	<host>/api/articles/<articleId>/extensionEndpoints/app/handler/endpoint
`project`	<host>/api/admin/projects/<projectId>/extensionEndpoints/app/handler/endpoint
`user`	<host>/api/users/<userId>/extensionEndpoints/app/handler/endpoint
`global`	<host>/api/extensionEndpoints/app/handler/endpoint

Set the following variables to match your app:

app — the name from your app's manifest.
handler — the name of the file that contains the HTTP handler script in the app package without the .js file extension.
endpoint — the path from the declaration. For example, "path": "/endpoint"

To call a scoped endpoint, the user must have access to the scope entity. For example, the endpoint /api/issues/DEMO-1/extensionEndpoints/app/handler/endpoint requires access to the issue with the ID DEMO-1.

The endpoint must also pass its permissions check. The HTTP handler must be active and visible to the user in the app's global settings. For project-level handlers, the app must also be attached to the corresponding project, and the handler must be active and visible in that project.

Global endpoints require an authenticated user. External clients must authenticate their requests as described in Authentication for Apps.

06 November 2026