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 |
|
Supported sub-resources |
|
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. |
idReadable | String | The issue ID. |
created | Long | The timestamp of the moment when the issue was created. |
updated | Long | The timestamp of the last update of the issue. |
resolved | Long | The timestamp of the moment when the issue was assigned a state that is considered to be resolved. Returns |
numberInProject | Long | The issue number in the project. |
project | Project | The project to which the issue is assigned. |
summary | String | The text that is entered as the issue summary. |
description | String | The text that is entered as the issue description. |
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). |
reporter | User | The user who reported (created) the issue. |
updater | User | The user who last updated the issue. |
draftOwner | User | Creator of this draft if issue is a draft, null if issue was already reported. |
isDraft | Boolean | true if issue is a draft, false if it was already reported. |
visibility | Visibility | Visibility settings of the issue. They describe who is allowed to see the issue. |
votes | Int | Number of votes for this issue. |
comments | Array of IssueComments | A list of comments for the issue. |
commentsCount | Int | A number of comments in the issue. |
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). |
externalIssue | ExternalIssue | Reference to the issue or similar object in an originating third-party system. |
customFields | Array of IssueCustomFields | The collection of custom fields that are present in the issue. |
voters | IssueVoters | Object that contains data about voters for the issue and for its duplicates. |
watchers | IssueWatchers | Object that contains data about users watching this issue or its duplicates. |
attachments | Array of IssueAttachments | The list of attachments in the issue. |
subtasks | IssueLink | The list of sub-tasks of the issue. |
parent | IssueLink | The parent issue for the current one. If the issue is not a sub-task of any issue, then |
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
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 |
$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
Sample response body
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
Sample response body
Add a New Issue
Create new issue.
Required permissions
Requires permissions: Create Issue
Request syntax
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 |
draftId | String | ID of a draft to report as the new issue. If no |
muteUpdateNotifications | Boolean | Set this parameter to |
Sample 1
Let's create an issue with a specific summary, description, and the value of the Priority custom field.
Sample request
Sample request body
Sample response body
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.