# Issues

Resource that provides access to issues.
|  Resource  |     ```GENERIC /api/issues ```    |
| --- | --- |
|  Returned entity  |  [Issue](api-entity-Issue.html). For the description of the entity attributes, see [Supported Fields](#Issue-supported-fields) section.  |
|  Supported methods  |      * `GET`: [Read a List of Issues](#get_all-Issue-method).    * `POST`: [Add a New Issue](#create-Issue-method).    |
|  Supported sub-resources  |      * [/api/issues/{issueID}](operations-api-issues.html)    * [/api/issues/{issueID}/sprints](resource-api-issues-issueID-sprints.html)    * [/api/issues/{issueID}/timeTracking](resource-api-issues-issueID-timeTracking.html)    * [/api/issues/{issueID}/links](resource-api-issues-issueID-links.html)    * [/api/issues/{issueID}/attachments](resource-api-issues-issueID-attachments.html)    * [/api/issues/{issueID}/vcsChanges](resource-api-issues-issueID-vcsChanges.html)    * [/api/issues/{issueID}/activities](resource-api-issues-issueID-activities.html)    * [/api/issues/{issueID}/activitiesPage](resource-api-issues-issueID-activitiesPage.html)    * [/api/issues/{issueID}/customFields](resource-api-issues-issueID-customFields.html)    * [/api/issues/{issueID}/project](resource-api-issues-issueID-project.html)    * [/api/issues/{issueID}/tags](resource-api-issues-issueID-tags.html)    * [/api/issues/{issueID}/comments](resource-api-issues-issueID-comments.html)    |

## Issue attributes

Represents an issue in YouTrack.

### Related Resources

Below you can find the list of resources that let you work with this entity.

* [/api/issues]()

* [/api/issues/{issueID}/links/{linkID}/issues](resource-api-issues-issueID-links-linkID-issues.html)

* [/api/admin/projects/{projectID}/issues](resource-api-admin-projects-projectID-issues.html)

### Attributes

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 database ID of the issue. `Read-only`.  |
|  attachments  |  [Array of IssueAttachments](api-entity-IssueAttachment.html)  |  The list of attachments in the issue.  |
|  comments  |  [Array of IssueComments](api-entity-IssueComment.html)  |  A list of comments for the issue.  |
|  commentsCount  |  Int  |  The number of comments in the issue. `Read-only`.  |
|  created  |  Long  |  The timestamp in milliseconds indicating the moment when the issue was created. Stored as a unix timestamp at UTC. `Read-only`.  |
|  customFields  |  [Array of IssueCustomFields](api-entity-IssueCustomField.html)  |  The collection of custom fields that are present in the issue. `Read-only`.  |
|  description  |  String  |  The issue description. `Can be null`.  |
|  draftOwner  |  [User](api-entity-User.html)  |  The creator of the draft if the issue is a draft. `null` if the issue is reported. `Read-only`. `Can be null`.  |
|  externalIssue  |  [ExternalIssue](api-entity-ExternalIssue.html)  |  Reference to the issue or similar object in an originating third-party system. `Read-only`. `Can be null`.  |
|  idReadable  |  String  |  The issue ID as seen in the YouTrack interface. `Read-only`.  |
|  isDraft  |  Boolean  |  `true` if this issue is a draft, `false` if it is reported. `Read-only`.  |
|  links  |  [Array of IssueLinks](api-entity-IssueLink.html)  |  Issue links (for example, `relates to`, `parent for`, and so on). `Read-only`.  |
|  numberInProject  |  Long  |  The issue number in the project. `Read-only`.  |
|  parent  |  [IssueLink](api-entity-IssueLink.html)  |  The parent issue for the current one. If the issue is not a sub-task of any issue, then `null`. `Read-only`.  |
|  pinnedComments  |  [Array of IssueComments](api-entity-IssueComment.html)  |  The list of comments that are pinned in the issue. `Read-only`.  |
|  project  |  [Project](api-entity-Project.html)  |  The project where the issue belongs. `Can be null`.  |
|  reporter  |  [User](api-entity-User.html)  |  The user who reported (created) the issue. `Read-only`. `Can be null`.  |
|  resolved  |  Long  |  The timestamp in milliseconds indicating the moment when the issue was assigned a state that is considered to be resolved. Stored as a unix timestamp at UTC. `null` if the issue is still in an unresolved state. `Read-only`. `Can be null`.  |
|  subtasks  |  [IssueLink](api-entity-IssueLink.html)  |  The list of sub-tasks of the issue. `Read-only`.  |
|  summary  |  String  |  The issue summary. `Can be null`.  |
|  tags  |  [Array of Tags](api-entity-Tag.html)  |  The list of tags that are added to the issue.  |
|  updated  |  Long  |  The timestamp in milliseconds indicating the last update of the issue. Stored as a unix timestamp at UTC. `Read-only`.  |
|  updater  |  [User](api-entity-User.html)  |  The user who last updated the issue. `Read-only`. `Can be null`.  |
|  visibility  |  [Visibility](api-entity-Visibility.html)  |  Visibility settings of the issue. They describe who is allowed to see the issue. `Can be null`.  |
|  voters  |  [IssueVoters](api-entity-IssueVoters.html)  |  Object that contains data about voters for the issue and for its duplicates. `Read-only`.  |
|  votes  |  Int  |  The sum of votes for this issue and votes for its duplicates. A reporter of a duplicate issue automatically becomes a voter for the main issue. `Read-only`.  |
|  watchers  |  [IssueWatchers](api-entity-IssueWatchers.html)  |  Object that contains data about users watching this issue or its duplicates. `Read-only`.  |
|  wikifiedDescription  |  String  |  The issue description as shown in the UI after processing wiki/Markdown markup (including HTML markup). `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

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

|  null  |  The database ID of Issue  |
| --- | --- |

### 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. If you don't set the $top value, the server limits the maximum number of returned entries.       The server returns a maximum of 42 entries for most resources that return collections. For more information, see [Pagination](api-concept-pagination.html).     |
|  query  |  String  |  Issue search query. Read more about the search syntax here: [Search Query Reference](https://www.jetbrains.com/help/youtrack/cloud/?Search-and-Command-Attributes)  |
|  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

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

#### Sample response body

```JSON
[
  {
    "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

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

```JSON
[
  {
    "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 an issue.

Required fields: `summary`, `project` (`id`).

### Required permissions

Requires permissions: Create Issue

### Request syntax

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

|  null  |  The database ID of Issue  |
| --- | --- |

### 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 summary and 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

In this example, we create an issue with a specific summary, description, and the value of the Priority custom field.

#### Sample request

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

#### Sample request body

```JSON
{
  "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

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