Connection

Represents an HTTP connection that sends requests to a target site from workflows, apps, and import scripts.

Properties

Name	Type	Description
headers	Array.<{name: String, value: String}>	The headers added to the connection.
url	string	The base URL of the target site. If empty, specify an absolute URL in each request method.

Constructors

Connection

Connection(url, sslKeyName, timeout)

Creates a connection to a target site.

Parameters

Name	Type	Description
url	string	The base URL of the target site. If empty, specify an absolute URL in each request method.
sslKeyName	string	The optional name of the SSL key used to establish a secure connection. To omit this parameter, pass `null`.
timeout	int	The optional timeout, in milliseconds, for outgoing HTTP requests.

Name

Type

Description

url

string

The base URL of the target site. If empty, specify an absolute URL in each request method.

sslKeyName

string

The optional name of the SSL key used to establish a secure connection.

To omit this parameter, pass null.

timeout

int

The optional timeout, in milliseconds, for outgoing HTTP requests.

See Also

doSync

Quick Example

// Gets the content of a PasteBin paste, assuming that we have received its key (`pasteBinKey`) in a prior request. const connection = new http.Connection('http://pastebin.com/raw/'); connection.addHeader({name: 'Content-Type', value: 'text/plain'}); const response = connection.getSync(pasteBinKey, ''); if (response && response.code === 200) { let text = ''; response.headers.forEach(function(header) { text += header.name + ': ' + header.value + '\n'; }); text += '\n' + response.response; issue.addComment(text); }

Request Styles

Style	Methods	Behavior
Synchronous	`connectSync` `deleteSync` `doSync` `getSync` `headSync` `optionsSync` `patchSync` `postSync` `putSync`	The request completes during the current execution and returns a Response.
Asynchronous	`deleteAsync` `doAsync` `getAsync` `patchAsync` `postAsync` `putAsync`	The request runs after the current transaction commits. YouTrack passes the response to a named async function.

Methods

addHeader

addHeader(header, value)

Adds a header to the connection. The value parameter can also reference a secret stored in the settings for a YouTrack app.

Parameters

Name	Type	Description
header	Object, string	A header object with the structure `{name: string, value: string}`. When the `value` parameter is specified separately, this string is used as the header name.
value	string	The value to assign to the header. This parameter is used only when `header` is a string.

Name

Type

Description

header

Object, string

A header object with the structure {name: string, value: string}.

When the value parameter is specified separately, this string is used as the header name.

value

string

The value to assign to the header. This parameter is used only when header is a string.

Return Value

Type	Description
Connection	The current Connection object.

basicAuth

basicAuth(login, password)

Adds a Basic authorization header generated from the specified login and password. The password parameter can also reference a secret stored in the settings for a YouTrack app.

Parameters

Name	Type	Description
login	String	The login for Basic authentication.
password	String	The password for Basic authentication.

Return Value

Type	Description
Connection	The current Connection object.

bearerAuth

bearerAuth(token)

Adds a Bearer authorization header for the specified token. The token parameter can also reference a secret stored in the settings for a YouTrack app.

Parameters

Name	Type	Description
token	String	The token for Bearer authentication.

Return Value

Type	Description
Connection	The current Connection object.

connectSync

connectSync(uri, queryParams)

Executes a synchronous CONNECT request.

Parameters

Name	Type	Description
uri	string	The request URI. The complete URL combines the URL passed to the Connection constructor with this string. If the constructor URL is empty, specify the absolute URL of the target site.
queryParams	Array.<{name: String, value: String}>, Object	The query parameters. If an object is passed, its keys are considered to be parameter names.

Name

Type

Description

uri

string

The request URI.

The complete URL combines the URL passed to the Connection constructor with this string.

If the constructor URL is empty, specify the absolute URL of the target site.

queryParams

Array.<{name: String, value: String}>, Object

The query parameters.

If an object is passed, its keys are considered to be parameter names.

Return Value

Type	Description
Response	The HTTP response.

deleteAsync

deleteAsync(uri, queryParams, handlerName)

Schedules an asynchronous DELETE request.

Available since 2026.2

Parameters

Name	Type	Description
uri	string	The request URI.
queryParams	Array, Object	The query parameters.
handlerName	string	The name of the async function that handles the response.

deleteSync

deleteSync(uri, queryParams)

Executes a synchronous DELETE request.

Parameters

Name	Type	Description
uri	string	The request URI. The complete URL combines the URL passed to the Connection constructor with this string. If the constructor URL is empty, specify the absolute URL of the target site.
queryParams	Array.<{name: String, value: String}>, Object	The query parameters. If an object is passed, its keys are considered to be parameter names.

Name

Type

Description

uri

string

The request URI.

The complete URL combines the URL passed to the Connection constructor with this string.

If the constructor URL is empty, specify the absolute URL of the target site.

queryParams

Array.<{name: String, value: String}>, Object

The query parameters.

If an object is passed, its keys are considered to be parameter names.

Return Value

Type	Description
Response	The HTTP response.

doAsync

doAsync(requestType, uri, queryParams, payload, handlerName)

Schedules an asynchronous HTTP request. The request is executed after the current transaction commits, and the response is passed to the named async function handler. The handler must be declared in the asyncFunctions property of the rule or HTTP handler. Inside the handler, the response is available as the response property of the context object. It provides the same properties and methods as Response.

Available since 2026.2

Parameters

Name	Type	Description
requestType	string	A valid HTTP request type.
uri	string	A relative URI.
queryParams	Array.<{name: String, value: String}>, Object	The query parameters.
payload	string, Object	The content to send in the request.
handlerName	string	The name of the async function that handles the response.

doSync

doSync(requestType, uri, queryParams, payload)

Sends a synchronous HTTP request of the specified type. For common request types, you can call a dedicated method such as getSync() or postSync() instead.

Parameters

Name	Type	Description
requestType	string	A valid HTTP request type. For a list of supported request types, see REQUEST_TYPES.
uri	string	A relative URI. The complete URL combines the URL passed to the Connection constructor with this string. If the constructor URL is empty, specify the absolute URL of the target site.
queryParams	Array.<{name: String, value: String}>	The query parameters.
payload	string, Array, Object	The content to send in the request.

Return Value

Type	Description
Response	The HTTP response.

getAsync

getAsync(uri, queryParams, handlerName)

Schedules an asynchronous GET request.

Available since 2026.2

Parameters

Name	Type	Description
uri	string	The request URI.
queryParams	Array, Object	The query parameters.
handlerName	string	The name of the async function that handles the response.

getSync

getSync(uri, queryParams)

Executes a synchronous GET request.

Parameters

Name	Type	Description
uri	String	The request URI. The complete URL combines the URL passed to the Connection constructor with this string. If the constructor URL is empty, specify the absolute URL of the target site.
queryParams	Array.<{name: String, value: String}>, Object	The query parameters. If an object is passed, its keys are considered to be parameter names.

Name

Type

Description

uri

String

The request URI.

The complete URL combines the URL passed to the Connection constructor with this string.

If the constructor URL is empty, specify the absolute URL of the target site.

queryParams

Array.<{name: String, value: String}>, Object

The query parameters.

If an object is passed, its keys are considered to be parameter names.

Return Value

Type	Description
Response	The HTTP response.

headSync

headSync(uri, queryParams)

Executes a synchronous HEAD request.

Parameters

Name	Type	Description
uri	string	The request URI. The complete URL combines the URL passed to the Connection constructor with this string. If the constructor URL is empty, specify the absolute URL of the target site.
queryParams	Array.<{name: String, value: String}>, Object	The query parameters. If an object is passed, its keys are considered to be parameter names.

Name

Type

Description

uri

string

The request URI.

The complete URL combines the URL passed to the Connection constructor with this string.

If the constructor URL is empty, specify the absolute URL of the target site.

queryParams

Array.<{name: String, value: String}>, Object

The query parameters.

If an object is passed, its keys are considered to be parameter names.

Return Value

Type	Description
Response	The HTTP response.

optionsSync

optionsSync(uri, queryParams)

Executes a synchronous OPTIONS request.

Parameters

Name	Type	Description
uri	string	The request URI. The complete URL combines the URL passed to the Connection constructor with this string. If the constructor URL is empty, specify the absolute URL of the target site.
queryParams	Array.<{name: String, value: String}>, Object	The query parameters. If an object is passed, its keys are considered to be parameter names.

Name

Type

Description

uri

string

The request URI.

The complete URL combines the URL passed to the Connection constructor with this string.

If the constructor URL is empty, specify the absolute URL of the target site.

queryParams

Array.<{name: String, value: String}>, Object

The query parameters.

If an object is passed, its keys are considered to be parameter names.

Return Value

Type	Description
Response	The HTTP response.

patchAsync

patchAsync(uri, queryParams, payload, handlerName)

Schedules an asynchronous PATCH request.

Available since 2026.2

Parameters

Name	Type	Description
uri	string	The request URI.
queryParams	Array, Object	The query parameters.
payload	string, Object	The content to send in the request.
handlerName	string	The name of the async function that handles the response.

patchSync

patchSync(uri, queryParams, payload)

Executes a synchronous PATCH request.

Parameters

Name	Type	Description
uri	string	The request URI. The complete URL combines the URL passed to the Connection constructor with this string. If the constructor URL is empty, specify the absolute URL of the target site.
queryParams	Array.<{name: String, value: String}>, Object	The query parameters. If an object is passed, its keys are considered to be parameter names.
payload	string	The content to send in the request.

Name

Type

Description

uri

string

The request URI.

The complete URL combines the URL passed to the Connection constructor with this string.

If the constructor URL is empty, specify the absolute URL of the target site.

queryParams

Array.<{name: String, value: String}>, Object

The query parameters.

If an object is passed, its keys are considered to be parameter names.

payload

string

The content to send in the request.

Return Value

Type	Description
Response	The HTTP response.

postAsync

postAsync(uri, queryParams, payload, handlerName)

Schedules an asynchronous POST request.

Available since 2026.2

Parameters

Name	Type	Description
uri	string	The request URI.
queryParams	Array, Object	The query parameters.
payload	string, Object	The content to send in the request.
handlerName	string	The name of the async function that handles the response.

postSync

postSync(uri, queryParams, payload)

Executes a synchronous POST request.

Parameters

Name	Type	Description
uri	string	The request URI. The complete URL combines the URL passed to the Connection constructor with this string. If the constructor URL is empty, specify the absolute URL of the target site.
queryParams	Array.<{name: String, value: String}>, Object	The query parameters. If an object is passed, its keys are considered to be parameter names. If the payload parameter is empty, the query parameters are passed as a form entity.
payload	string, Object	The content to send in the request. For posting attachment files from YouTrack to a third-party application, pass the payload as an object, set its `type` value to `multipart/form-data`, and pass the attachments in `parts`. For each part, `name`, `size`, `fileName`, and `content` values are required. For details and an example, see Posting Binary Content with multipart/form-data Type.

Name

Type

Description

uri

string

The request URI.

The complete URL combines the URL passed to the Connection constructor with this string.

If the constructor URL is empty, specify the absolute URL of the target site.

queryParams

Array.<{name: String, value: String}>, Object

The query parameters.

If an object is passed, its keys are considered to be parameter names.

If the payload parameter is empty, the query parameters are passed as a form entity.

payload

string, Object

The content to send in the request.

For posting attachment files from YouTrack to a third-party application, pass the payload as an object, set its type value to multipart/form-data, and pass the attachments in parts.

For each part, name, size, fileName, and content values are required.

For details and an example, see Posting Binary Content with multipart/form-data Type.

Return Value

Type	Description
Response	The HTTP response.

Example

const attachment = issue.attachments.first(); connection.postSync('issues/' + issue.id + '/attachments', [], { type: 'multipart/form-data', parts: [ { // These four fields are required for each part. // Optionally, you can also set the `contentType` value individually for each part. name: 'my-part-name', size: attachment.size, fileName: 'filename', content: attachment.content } ] });

putAsync

putAsync(uri, queryParams, payload, handlerName)

Schedules an asynchronous PUT request.

Available since 2026.2

Parameters

Name	Type	Description
uri	string	The request URI.
queryParams	Array, Object	The query parameters.
payload	string, Object	The content to send in the request.
handlerName	string	The name of the async function that handles the response.

putSync

putSync(uri, queryParams, payload)

Executes a synchronous PUT request.

Parameters

Name	Type	Description
uri	string	The request URI. The complete URL combines the URL passed to the Connection constructor with this string. If the constructor URL is empty, specify the absolute URL of the target site.
queryParams	Array.<{name: String, value: String}>, Object	The query parameters. If an object is passed, its keys are considered to be parameter names. If the payload parameter is empty, the query parameters are passed as a form entity.
payload	string	The content to send in the request.

Name

Type

Description

uri

string

The request URI.

The complete URL combines the URL passed to the Connection constructor with this string.

If the constructor URL is empty, specify the absolute URL of the target site.

queryParams

Array.<{name: String, value: String}>, Object

The query parameters.

If an object is passed, its keys are considered to be parameter names.

If the payload parameter is empty, the query parameters are passed as a form entity.

payload

string

The content to send in the request.

Return Value

Type	Description
Response	The HTTP response.

setHeader

setHeader(header, value)

Sets a header to the current connection. If the specified header already exists, its value is updated. The value parameter can also contain references to secrets stored in the settings for a YouTrack app.

Parameters

Name	Type	Description
header	Object, string	A header object with the structure `{name: string, value: string}`. If the `value` parameter is specified separately, the provided string is used as the name of the header.
value	string	The value to assign to the header. This parameter is used only when `header` is a string.

Name

Type

Description

header

Object, string

A header object with the structure {name: string, value: string}.

If the value parameter is specified separately, the provided string is used as the name of the header.

value

string

The value to assign to the header. This parameter is used only when header is a string.

Return Value

Type	Description
Connection	The current Connection object.

10 September 2026