JetBrains Developer Portal

https://www.jetbrains.com/help/youtrack/devportal/
Admin
JetBrains Developer Portal provides comprehensive API documentation for YouTrack and Hub, including...
Tokens:1,445,799
Snippets:9,284
Trust Score:10
Update:14 hours ago
Show doc for...
Tokens:
Raw
### Connection Quick Example

Source: https://www.jetbrains.com/help/youtrack/devportal/v1-Connection.html

Example usage of the Connection class to send a synchronous GET request.

```APIDOC
## Quick Example

### Description
Example of creating a connection and sending a synchronous GET request.

### Code 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);
}
```
```

--------------------------------

### Install YouTrack packages globally with npm

Source: https://www.jetbrains.com/help/youtrack/devportal/js-workflow-external-editor.html

Use these commands to install the workflow API package and app tools globally in your development environment. This is the easiest way to get started.

```bash
npm install -g @jetbrains/youtrack-scripting-api
```

```bash
npm install -g @jetbrains/youtrack-apps-tools
```

--------------------------------

### Start local development

Source: https://www.jetbrains.com/help/youtrack/devportal/apps-enhanced-dx-typescript.html

Builds the app and uploads a development version to YouTrack.

```bash
npm run dev
```

--------------------------------

### Sample request to get issue sprints

Source: https://www.jetbrains.com/help/youtrack/devportal/resource-api-issues-issueID-sprints.html.md/

Example CURL request to retrieve sprints for issue NP-113, requesting specific fields such as id, agile, name, goal, start, finish, and archived.

```CURL
https://example.youtrack.cloud/api/issues/NP-113/sprints?fields=id,agile(id,name),name,goal,start,finish,archived
```

--------------------------------

### HTTP Connection Setup

Source: https://www.jetbrains.com/help/youtrack/devportal/Import-DemoClient.html

Shows how to set up a reusable HTTP connection in the DemoClient constructor using the YouTrack scripting API.

```APIDOC
## HTTP Connection Setup

### Description
A client that reads from a web API usually creates a reusable HTTP connection in the constructor. This example demonstrates how to set up the connection using the YouTrack scripting API.

### Code Example
```javascript
const http = require('@jetbrains/youtrack-scripting-api/http');
class DemoClient {
  constructor(context) {
    const params = context.parameters;
    this.url = params.loadValue('url');
    this.sslKeyName = params.loadValue('sslKeyName');
    this.token = params.loadValue('password');
    this.connection = new http.Connection(this.url, this.sslKeyName)
      .addHeader('Authorization', `Bearer ${this.token}`);
  }
}
```
```

--------------------------------

### Sample response body for reading build bundles

Source: https://www.jetbrains.com/help/youtrack/devportal/resource-api-admin-customFieldSettings-bundles-build.html.md/

Example JSON response containing a list of build bundles with their names and IDs.

```JSON
[
  {
    "name": "Sample Project: Fixed in builds",
    "id": "95-0",
    "$type": "BuildBundle"
  },
  {
    "name": "Rest Api Project: Fixed in builds",
    "id": "95-2",
    "$type": "BuildBundle"
  },
  {
    "name": "Sandbox: Fixed in builds",
    "id": "95-3",
    "$type": "BuildBundle"
  }
]
```

--------------------------------

### fetchHub GET request example

Source: https://www.jetbrains.com/help/youtrack/devportal/apps-host-api.html

Example of using fetchHub to fetch data from the Hub service with a GET request. The method returns a promise that resolves with the fetched data.

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

--------------------------------

### Sample response body for adding a build bundle

Source: https://www.jetbrains.com/help/youtrack/devportal/resource-api-admin-customFieldSettings-bundles-build.html.md/

Example JSON response containing the ID and type of the newly created build bundle.

```JSON
{
  "id": "95-10",
  "$type": "BuildBundle"
}
```

--------------------------------

### fetchHub GET request example

Source: https://www.jetbrains.com/help/youtrack/devportal/apps-host-api.html.md/

Example of using fetchHub to make a GET request to the Hub API to fetch the current user's name, login, and avatar URL.

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

--------------------------------

### Sample request URL

Source: https://www.jetbrains.com/help/youtrack/devportal/resource-api-admin-customFieldSettings-bundles-build-bundleID-values.html.md/

Example URL for adding a build element with ID 86-1, requesting fields id, name, assembleDate, and description.

```CURL
https://example.youtrack.cloud/api/admin/customFieldSettings/bundles/build/86-1/values?fields=id,name,assembleDate,description
```

--------------------------------

### Sample response body

Source: https://www.jetbrains.com/help/youtrack/devportal/resource-api-admin-projects-projectID-customFields.html.md/

Example response showing the created ProjectCustomField with the requested field attributes.

```JSON
{
  "field": {
    "fieldType": {
      "valueType": "string",
      "id": "string",
      "$type": "FieldType"
    },
    "name": "Last message related emails",
    "id": "46-21",
    "$type": "CustomField"
  },
  "$type": "SimpleProjectCustomField"
}
```

--------------------------------

### Response from GET /api/tags

Source: https://www.jetbrains.com/help/youtrack/devportal/api-usecase-add-remove-tags.html

Example JSON response from the GET /api/tags request, showing the `id`, `name`, and `$type` fields for each tag.

```json
[ { "name": "Star", "id": "6-1", "$type": "Tag" }, { "name": "To deploy", "id": "6-4", "$type": "Tag" } ]
```

--------------------------------

### GET License - Sample Response Body (JSON)

Source: https://www.jetbrains.com/help/youtrack/devportal/operations-api-admin-globalSettings-license.html.md/

Example response body for a successful GET request, showing the license details and the $type field.

```JSON
{
  "username": "example",
  "license": "17269e7714ee93dec5002a17427b55f3126a37635d9a41349ffb02dfc0b1bd7b167dcb56232813da571653c087bb2e1ff9325e4775d494c2f99eab72100d1e90cf7532d8f4e721b27521d107fb3f62",
  "error": null,
  "$type": "License"
}
```

--------------------------------

### Sample response body

Source: https://www.jetbrains.com/help/youtrack/devportal/resource-api-admin-customFieldSettings-bundles-version.html.md/

Example response after creating a version bundle, including generated IDs for the bundle and its elements.

```JSON
{
  "values": [
    {
      "name": "2019.1.1",
      "id": "133-21",
      "$type": "VersionBundleElement"
    },
    {
      "name": "2019.1.2",
      "id": "133-22",
      "$type": "VersionBundleElement"
    }
  ],
  "name": "Base Versions",
  "id": "71-11",
  "$type": "VersionBundle"
}
```

--------------------------------

### notifyAllUsers example usage

Source: https://www.jetbrains.com/help/youtrack/devportal/v1-ProjectTeam.html.md/

Example of sending a notification when the permittedGroup field changes. Uses issue.oldValue('permittedGroup') to get the previous group and notifies its members.

```JAVASCRIPT
issue.oldValue('permittedGroup').notifyAllUsers('Visibility has been changed',
  'The visibility group for the issue ' + issue.getId() +
  ' has been changed to ' + permittedGroup.name);
```

--------------------------------

### Sample request body for adding a build bundle

Source: https://www.jetbrains.com/help/youtrack/devportal/resource-api-admin-customFieldSettings-bundles-build.html.md/

JSON body for creating a build bundle with a name and a list of build elements.

```JSON
{
  "values": [
    {
      "name": "11111.3.2342",
      "$type": "BuildBundleElement"
    },
    {
      "name": "11112.3.6528",
      "$type": "BuildBundleElement"
    }
  ],
  "name": "Base Builds"
}
```

--------------------------------

### GET /api/activities - Example with author and issueQuery

Source: https://www.jetbrains.com/help/youtrack/devportal/api-usecase-issue-history.html

To get activity items authored by a specific user across multiple issues, use the GET Activity Items endpoint with the 'author' parameter and optionally 'issueQuery' to limit matching issues.

```http
/api/activities?categories=CustomFieldCategory,CommentsCategory&author=jane.doe&issueQuery=project:%20SP&fields=id,author(name,login),timestamp,target(id),added(name),removed(name)
```

--------------------------------

### Sample GET Response Body for TimeTrackingUserProfile

Source: https://www.jetbrains.com/help/youtrack/devportal/operations-api-users-userID-profiles-timetracking.html.md/

Example JSON response body for a successful GET request, showing the periodFormat object with id HOURS_MINUTES and type PeriodFieldFormat.

```JSON
{
  "periodFormat": {
    "id": "HOURS_MINUTES",
    "$type": "PeriodFieldFormat"
  },
  "$type": "TimeTrackingUserProfile"
}
```

--------------------------------

### Response with version bundle and values

Source: https://www.jetbrains.com/help/youtrack/devportal/api-usecase-archive-version-value.html

Example response showing the version bundle and its values, including the IDs used in the archive request.

```json
[
  {
    "values": [
      {
        "name": "2025.3",
        "archived": false,
        "released": true,
        "id": "133-12",
        "$type": "VersionBundleElement"
      },
      {
        "name": "2026.1",
        "archived": false,
        "released": false,
        "id": "133-19",
        "$type": "VersionBundleElement"
      }
    ],
    "name": "Affected versions",
    "id": "97-4",
    "$type": "VersionBundle"
  }
]
```

--------------------------------

### First result example

Source: https://www.jetbrains.com/help/youtrack/devportal/v1-search.html.md/

Example of using search and then calling first() on the returned Set to get the first matching issue. The code checks if firstIssue is not null before processing.

```JAVASCRIPT
const search = require('@jetbrains/youtrack-scripting-api/search');

const firstIssue = search.search(
  ctx.issue.project,
  'State: {In Progress}',
  ctx.currentUser
).first();

if (firstIssue) {
  // Process the first matching issue.
}
```

--------------------------------

### Sample request body

Source: https://www.jetbrains.com/help/youtrack/devportal/resource-api-admin-customFieldSettings-bundles-version.html.md/

JSON body for creating a version bundle with two version elements and a name.

```JSON
{
  "values": [
    {
      "name": "2019.1.1",
      "$type": "VersionBundleElement"
    },
    {
      "name": "2019.1.2",
      "$type": "VersionBundleElement"
    }
  ],
  "name": "Base Versions",
  "$type": "VersionBundle"
}
```

--------------------------------

### Sample GET request for user bundle individuals

Source: https://www.jetbrains.com/help/youtrack/devportal/resource-api-admin-customFieldSettings-bundles-user-bundleID-individuals.html.md/

Example GET request to retrieve users from a user bundle with ID '8-2', requesting the 'name', 'id', and 'login' fields.

```CURL
https://example.youtrack.cloud/api/admin/customFieldSettings/bundles/user/8-2/individuals?fields=name,id,login
```

--------------------------------

### Sample GET response for user bundle individuals

Source: https://www.jetbrains.com/help/youtrack/devportal/resource-api-admin-customFieldSettings-bundles-user-bundleID-individuals.html.md/

Example JSON response containing a list of user objects with login, name, id, and $type fields.

```JSON
[
  {
    "login": "jane.doe",
    "name": "Jane Doe",
    "id": "1-3",
    "$type": "User"
  },
  {
    "login": "Jane_Smith",
    "name": "Jane Smith",
    "id": "1-4",
    "$type": "User"
  }
]
```

--------------------------------

### slaEnterFunction example: onEnter: (ctx) => { console.log('onEnter', ctx.issue.id); }

Source: https://www.jetbrains.com/help/youtrack/devportal/v1-entities.html

Example of an SLA enter function that logs the issue ID. Called when the SLA policy starts applying to the ticket.

```javascript
onEnter: (ctx) => { console.log('onEnter', ctx.issue.id); }
```

--------------------------------

### Sample request to read global settings

Source: https://www.jetbrains.com/help/youtrack/devportal/operations-api-admin-globalSettings.html.md/

Example request URL that specifies the fields to return, including appearanceSettings, license, localeSettings, restSettings, systemSettings, and updateInfo.

```CURL
https://example.youtrack.cloud/api/admin/globalSettings?fields=appearanceSettings(dateFieldFormat(id,presentation),timeZone(id,presentation)),id,license(freeUsername,id,isFreeLicenseUsed),localeSettings(id,locale(id,locale,name)),restSettings(allowAllOrigins,allowedOrigins,hubServiceOrigins,id),systemSettings(allowStatisticsCollection,baseUrl,id,maxExportItems,maxOrderedIssues,maxUploadFileSize),updateInfo(id,isChecking,result(date,downloadUrl,id,message,success,updateAvailable))
```

--------------------------------

### Sample HTTP Handler for GET requests

Source: https://www.jetbrains.com/help/youtrack/devportal/apps-reference-http-handlers.html

Creates an endpoint that handles HTTP GET requests. The handler responds with a JSON message 'Hello World'. Requires READ_ISSUE and READ_ARTICLE permissions.

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

--------------------------------

### Sample response body for GET project team

Source: https://www.jetbrains.com/help/youtrack/devportal/operations-api-admin-projects-projectID-team.html.md/

Example JSON response returned by the GET request, showing the project team's id, users, ownUsers, groups, and $type.

```JSON
{
  "id": "23-7",
  "users": [
    {
      "login": "jane.doe",
      "id": "1-2"
    },
    {
      "login": "john.smith",
      "id": "1-3"
    }
  ],
  "ownUsers": [
    {
      "login": "jane.doe",
      "id": "1-2"
    }
  ],
  "groups": [
    {
      "name": "Developers",
      "id": "23-1"
    }
  ],
  "$type": "ProjectTeam"
}
```

--------------------------------

### Read DatabaseBackupSettings - Sample Request

Source: https://www.jetbrains.com/help/youtrack/devportal/operations-api-admin-databaseBackup-settings.html.md/

Example GET request URL to read database backup settings with specific fields. Requires Low-level Admin Read permission.

```CURL
https://example.youtrack.cloud/api/admin/databaseBackup/settings?fields=archiveFormat,availableDiskSpace,backupStatus(backupCancelled,backupError(date,errorMessage),backupInProgress,stopBackup),isOn,location,cronExpression,filesToKeep,notifiedUsers(login,name,id)
```

--------------------------------

### Get a Specific Tag - Sample Response

Source: https://www.jetbrains.com/help/youtrack/devportal/api-usecase-work-with-tags.html

Example JSON response for the 'Get a Specific Tag' request. Shows the tag object with its owner, visibleFor group, and a list of associated issues.

```json
{
  "issues": [
    {
      "idReadable": "SP-45",
      "summary": "REST API lets you create issues!",
      "$type": "Issue"
    },
    {
      "idReadable": "RAP-2",
      "summary": "Example for Get specific issue tag",
      "$type": "Issue"
    },
    {
      "idReadable": "RAP-4",
      "summary": "New issue with new tag",
      "$type": "Issue"
    }
  ],
  "owner": {
    "login": "john.doe",
    "name": "John Doe",
    "$type": "User"
  },
  "visibleFor": {
    "name": "All Users",
    "id": "3-0",
    "$type": "UserGroup"
  },
  "name": "GET",
  "id": "6-4",
  "$type": "IssueTag"
}
```
Tokens:
Raw