Issues

Resource that provides access to issues.

Resource	/api/issues
Returned entity	Issue. For the description of the entity attributes, see Supported Fields section.
Supported methods	`GET`: Read a List of Issues. `POST`: Add a New Issue.
Supported sub-resources	/api/issues/{issueID}: Operations with Specific Issue /api/issues/{issueID}/sprints: Issue Sprints /api/issues/{issueID}/timeTracking: Issue Time Tracking /api/issues/{issueID}/links: Issue Links /api/issues/{issueID}/attachments: Issue Attachments /api/issues/{issueID}/vcsChanges: Issue VCS Changes /api/issues/{issueID}/activities: Issue Activity Items /api/issues/{issueID}/activitiesPage: Activity Cursor Page /api/issues/{issueID}/project: Issue Project /api/issues/{issueID}/tags: Issue Tags /api/issues/{issueID}/customFields: Issue Custom Fields /api/issues/{issueID}/comments: Issue Comments

Issue attributes

Represents an issue in YouTrack.

This table describes attributes of the Issue entity.

To receive an attribute in the response from the server, specify it explicitly in the fields request parameter.
To update an attribute, provide it in the body of a POST request.

Field	Type	Description
id	String	The ID of the issue. `Read-only`.
idReadable	String	The issue ID. `Read-only`.
created	Long	The timestamp of the moment when the issue was created. `Read-only`. `Can be null`.
updated	Long	The timestamp of the last update of the issue. `Read-only`. `Can be null`.
resolved	Long	The timestamp of the moment when the issue was assigned a state that is considered to be resolved. Returns `null`, if the issue is still in an unresolved state. `Read-only`. `Can be null`.
numberInProject	Long	The issue number in the project. `Read-only`.
project	Project	The project to which the issue is assigned. `Can be null`.
summary	String	The text that is entered as the issue summary. `Can be null`.
description	String	The text that is entered as the issue description. `Can be null`.
usesMarkdown	Boolean	When `true`, the issue description is parsed as Markdown. When `false`, the issue description is parsed as YouTrack Wiki. Changing this value does not transform the markup from one syntax to another.
wikifiedDescription	String	Issue description as it is shown in UI after processing with wiki/markdown (including HTML markup). `Read-only`.
reporter	User	The user who reported (created) the issue. `Read-only`. `Can be null`.
updater	User	The user who last updated the issue. `Read-only`. `Can be null`.
draftOwner	User	Creator of this draft if issue is a draft, null if issue was already reported. `Read-only`. `Can be null`.
isDraft	Boolean	true if issue is a draft, false if it was already reported. `Read-only`.
visibility	Visibility	Visibility settings of the issue. They describe who is allowed to see the issue. `Can be null`.
votes	Int	Number of votes for this issue. `Read-only`.
comments	Array of IssueComments	A list of comments for the issue.
commentsCount	Int	A number of comments in the issue. `Read-only`.
tags	Array of IssueTags	The list of tags that are added to the issue.
links	Array of IssueLinks	Issue links (for example, `relates to`, `parent for`, and so on). `Read-only`.
externalIssue	ExternalIssue	Reference to the issue or similar object in an originating third-party system. `Read-only`. `Can be null`.
customFields	Array of IssueCustomFields	The collection of custom fields that are present in the issue. `Read-only`.
voters	IssueVoters	Object that contains data about voters for the issue and for its duplicates. `Read-only`.
watchers	IssueWatchers	Object that contains data about users watching this issue or its duplicates. `Read-only`.
attachments	Array of IssueAttachments	The list of attachments in the issue.
subtasks	IssueLink	The list of sub-tasks of the issue. `Read-only`.
parent	IssueLink	The parent issue for the current one. If the issue is not a sub-task of any issue, then `null`. `Read-only`.

Read a List of Issues

Get all issues that match the specified query.

If you don't provide the query parameter, the server returns all issues.
If you don't specify any sorting in the query, the default issue sorting is sort by: updated desc.
If you don't provide the $top parameter, the number of returned issues is limited to the Max issues to export value in the Global Settings of your YouTrack.

Request syntax

GET /api/issues?{fields}&{$top}&{$skip}&{query}&{customFields}

Request parameters

Parameter	Type	Description
fields	String	A list of Issue attributes that should be returned in the response. If no field is specified, only the `entityID` is returned.
$skip	Int	Optional. Lets you set a number of returned entities to skip before returning the first one.
$top	Int	Optional. Lets you specify the maximum number of entries that are returned in the response.
query	String	Issues search query. Read more about search syntax here: Search Query Reference
customFields	String	The name of the custom field to show in the response. When you use this parameter and request the custom field data in the request URL, the response only shows the requested custom fields instead of all of them. To show more than one custom field, use this parameter several times. See Sample 2 for reference.

Sample 1

Let's get the list of issues filtered by the search query for: me #Unresolved. For each issue, we'll request its database ID, summary, description, and the reporter.

Sample request

https://example.youtrack.cloud/api/issues?query=for:%20me%20%23Unresolved%20&fields=id,summary,description,reporter(login)
            

Sample response body

[
  {
    "description": null,
    "summary": "Sprint 3. Task 2",
    "reporter": {
      "login": "root",
      "$type": "User"
    },
    "idReadable": "SP-38",
    "id": "2-42",
    "$type": "Issue"
  },
  {
    "description": "Let's create new issue from REST API",
    "summary": "Issue from REST #1",
    "reporter": {
      "login": "root",
      "$type": "User"
    },
    "idReadable": "SP-7",
    "id": "2-6",
    "$type": "Issue"
  }
]
            

Sample 2

Let's get the list of issues and request some of their custom fields values. If we don't set any customFields parameter, the response will contain all the custom fields. To get only the specific custom fields in the response, let's include their names in the customFields parameters. Include a separate customFields parameter in your request URI for each custom field that you want to see in the response.

Sample request

https://example.youtrack.cloud/api/issues?query=for:%20me%20%23Unresolved%20&fields=id,summary,customFields(name,value(name))&customFields=type&customFields=assignee&customFields=priority
            

Sample response body

[
  {
    "summary": "The report",
    "customFields": [
      {
        "value": {
          "name": "Jane Doe",
          "$type": "User"
        },
        "name": "Assignee",
        "$type": "SingleUserIssueCustomField"
      },
      {
        "value": [
          {
            "name": "Major",
            "$type": "EnumBundleElement"
          }
        ],
        "name": "Priority",
        "$type": "MultiEnumIssueCustomField"
      },
      {
        "value": {
          "name": "Bug",
          "$type": "EnumBundleElement"
        },
        "name": "Type",
        "$type": "SingleEnumIssueCustomField"
      }
    ],
    "id": "99-44",
    "$type": "Issue"
  },
  {
    "summary": "The release featue",
    "customFields": [
      {
        "value": {
          "name": "John Smith",
          "$type": "User"
        },
        "name": "Assignee",
        "$type": "SingleUserIssueCustomField"
      },
      {
        "value": [
          {
            "name": "Major",
            "$type": "EnumBundleElement"
          }
        ],
        "name": "Priority",
        "$type": "MultiEnumIssueCustomField"
      },
      {
        "value": {
          "name": "Feature",
          "$type": "EnumBundleElement"
        },
        "name": "Type",
        "$type": "SingleEnumIssueCustomField"
      }
    ],
    "id": "99-724",
    "$type": "Issue"
  }
]
            

Add a New Issue

Create new issue.

Required permissions

Requires permissions: Create Issue

Request syntax

POST /api/issues?{fields}&{draftId}&{muteUpdateNotifications}

Request parameters

Parameter	Type	Description
fields	String	A list of Issue attributes that should be returned in the response. If no field is specified, only the `entityID` is returned.
draftId	String	ID of a draft to report as the new issue. If no `draftId` is provided, the issue is created from scratch. In this case, you must specify the project in the request payload.
muteUpdateNotifications	Boolean	Set this parameter to `true` if no notifications should be sent on changes made by this request. This doesn't mute notifications sent by any workflow rules. Using this parameter requires Apply Commands Silently permission in all projects affected by the request. Available since 2021.3.

Sample 1

Let's create an issue with a specific summary, description, and the value of the Priority custom field.

Sample request

https://example.youtrack.cloud/api/issues?fields=idReadable

Sample request body

{
  "summary": "Houston!",
  "description": "We have a problem!",
  "project": {
    "id": "0-0"
  },
  "customFields": [
    {
      "value": {
        "name": "Critical"
      },
      "name": "Priority",
      "id": "92-1",
      "$type": "SingleEnumIssueCustomField"
    }
  ]
}
            

Sample response body

{
  "idReadable": "SP-39",
  "$type": "Issue"
}
            

Sample 2

Let's create an issue and set its reporter to a particular user. This approach allows you to create issues on behalf of other users.

Sample request

https://example.youtrack.cloud/api/issues?fields=idReadable,reporter(id,login)

Sample request body

{
  "summary": "Houston!",
  "description": "We have a problem!",
  "project": {
    "id": "81-1"
  },
  "reporter": {
    "id": "24-0",
    "$type": "User"
  }
}
            

Sample response body

{
  "idReadable": "NP-167",
  "reporter": {
    "login": "jane.doe",
    "id": "24-0",
    "$type": "User"
  },
  "$type": "Issue"
}
            

Last modified: 9 May 2022