# 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

```JAVASCRIPT
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.                     |

See Also

* [doSync](#doSync)

## Quick Example

```JAVASCRIPT
// 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](#connectSync)    * [deleteSync](#deleteSync)    * [doSync](#doSync)    * [getSync](#getSync)    * [headSync](#headSync)    * [optionsSync](#optionsSync)    * [patchSync](#patchSync)    * [postSync](#postSync)    * [putSync](#putSync)    | The request completes during the current execution and returns a [Response](v1-Response.html). |
| Asynchronous |      * [deleteAsync](#deleteAsync)    * [doAsync](#doAsync)    * [getAsync](#getAsync)    * [patchAsync](#patchAsync)    * [postAsync](#postAsync)    * [putAsync](#putAsync)    | The request runs after the current transaction commits. YouTrack passes the response to a named [async function](async-functions.html). |

## Methods

### addHeader

```JAVASCRIPT
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.                     |

Return Value
: | Type | Description |
: | --- | --- |
: |  [Connection]()  |  The current Connection object.                 |

### basicAuth

```JAVASCRIPT
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

```JAVASCRIPT
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

```JAVASCRIPT
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.                       |

Return Value
: | Type | Description |
: | --- | --- |
: |  [Response](v1-Response.html)  |  The HTTP response.                 |

### deleteAsync

```JAVASCRIPT
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

```JAVASCRIPT
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.                       |

Return Value
: | Type | Description |
: | --- | --- |
: |  [Response](v1-Response.html)  |  The HTTP response.                 |

### doAsync

```JAVASCRIPT
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](v1-Response.html).

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

```JAVASCRIPT
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](v1-REQUEST_TYPES.html).                       |
: | 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](v1-Response.html)  |  The HTTP response.                 |

### getAsync

```JAVASCRIPT
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

```JAVASCRIPT
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.                       |

Return Value
: | Type | Description |
: | --- | --- |
: |  [Response](v1-Response.html)  |  The HTTP response.                 |

### headSync

```JAVASCRIPT
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.                       |

Return Value
: | Type | Description |
: | --- | --- |
: |  [Response](v1-Response.html)  |  The HTTP response.                 |

### optionsSync

```JAVASCRIPT
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.                       |

Return Value
: | Type | Description |
: | --- | --- |
: |  [Response](v1-Response.html)  |  The HTTP response.                 |

### patchAsync

```JAVASCRIPT
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

```JAVASCRIPT
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.                     |

Return Value
: | Type | Description |
: | --- | --- |
: |  [Response](v1-Response.html)  |  The HTTP response.                 |

### postAsync

```JAVASCRIPT
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

```JAVASCRIPT
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](JS-Workflow-REST-API.html#post-multipart).                       |

Return Value
: | Type | Description |
: | --- | --- |
: |  [Response](v1-Response.html)  |  The HTTP response.                 |

Example
: ```JAVASCRIPT
: 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

```JAVASCRIPT
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

```JAVASCRIPT
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.                     |

Return Value
: | Type | Description |
: | --- | --- |
: |  [Response](v1-Response.html)  |  The HTTP response.                 |

### setHeader

```JAVASCRIPT
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.                     |

Return Value
: | Type | Description |
: | --- | --- |
: |  [Connection]()  |  The current Connection object.                 |

## See also

[http](v1-http.html) [Response](v1-Response.html) [Asynchronous Functions](async-functions.html) [Make Outbound HTTP Requests](JS-Workflow-REST-API.html)