Developer Portal for YouTrack and Hub Help

Issues

This resource lets you work with issues within the particular project.

Resource

/api/admin/projects/{projectID}/issues

Returned entity

Issue. For the description of the entity attributes, see Supported Fields section.

Supported methods

Issue attributes

Represents an issue in YouTrack.

Related Resources

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

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

The list of attachments in the issue.

comments

Array of IssueComments

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. Can be null.

customFields

Array of IssueCustomFields

The collection of custom fields that are present in the issue. Read-only.

description

String

The issue description. Can be null.

draftOwner

User

The creator of the draft if the issue is a draft. null if the issue is reported. Read-only. Can be null.

externalIssue

ExternalIssue

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

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

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

The list of comments that are pinned in the issue. Read-only.

project

Project

The project where the issue belongs. Can be null.

reporter

User

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

The list of sub-tasks of the issue. Read-only.

summary

String

The issue summary. Can be null.

tags

Array of Tags

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. Can be null.

updater

User

The user who last updated the issue. Read-only. Can be null.

visibility

Visibility

Visibility settings of the issue. They describe who is allowed to see the issue. Can be null.

voters

IssueVoters

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

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 a list of all available issues in the specific project.

  • 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/admin/projects/{projectID}/issues?{fields}&{$top}&{$skip}&{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. 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.

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

Sample request

https://example.youtrack.cloud/api/admin/projects/0-0/issues?fields=id,idReadable,summary&$skip=30&$top=5

Sample response body

[ { "idReadable": "SP-35", "summary": "Task 1", "id": "2-37", "$type": "Issue" }, { "idReadable": "SP-36", "summary": "REST API lets you create issues!", "id": "2-38", "$type": "Issue" }, { "idReadable": "SP-37", "summary": "Sprint3. Task 1", "id": "2-40", "$type": "Issue" }, { "idReadable": "SP-38", "summary": "New summary", "id": "2-42", "$type": "Issue" }, { "idReadable": "SP-39", "summary": "Huston!", "id": "2-44", "$type": "Issue" } ]

Sample 2

Sample request

https://example.youtrack.cloud/api/admin/projects/0-0/issues?fields=id,idReadable,summary,customFields(name,value(name))&customFields=type&customFields=assignee&customFields=priority

Sample response body

[ { "idReadable": "NP-117", "summary": "Poster design for the conference", "customFields": [ { "value": { "name": "Jane Doe", "$type": "User" }, "name": "Assignee", "$type": "SingleUserIssueCustomField" }, { "value": { "name": "Normal", "$type": "EnumBundleElement" }, "name": "Priority", "$type": "SingleEnumIssueCustomField" }, { "value": { "name": "Task", "$type": "EnumBundleElement" }, "name": "Type", "$type": "SingleEnumIssueCustomField" } ], "id": "99-8", "$type": "Issue" }, { "idReadable": "NP-1", "summary": "Deployment broken", "customFields": [ { "value": { "name": "John Smith", "$type": "User" }, "name": "Assignee", "$type": "SingleUserIssueCustomField" }, { "value": { "name": "Critical", "$type": "EnumBundleElement" }, "name": "Priority", "$type": "SingleEnumIssueCustomField" }, { "value": { "name": "Bug", "$type": "EnumBundleElement" }, "name": "Type", "$type": "SingleEnumIssueCustomField" } ], "id": "99-12", "$type": "Issue" } ]

Add a New Issue

Create a new issue in the specified project.

Required attributes: summary

Required permissions

Requires permissions: Create Issue

Request syntax

POST /api/admin/projects/{projectID}/issues?{fields}&{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.

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

Sample request

https://example.youtrack.cloud/api/admin/projects/0-6/issues?fields=id,idReadable,summary,description

Sample request body

{ "summary": "Sample for api/admin/projects/:id/issues endpoint", "description": "This issue is a sample for creating an issue in particular project. Using the api/admin/projects resource." }

Sample response body

{ "description": "This issue is a sample for creating an issue in particular project. Using the api/admin/projects resource.", "idReadable": "RP-3", "summary": "Sample for api/admin/projects/:id/issues endpoint", "id": "2-71", "$type": "Issue" }
Last modified: 8 February 2024