Developer Portal for YouTrack and Hub Help

Get Issues List with All Values

Use Case

Use the REST API to get a list of issues with all their custom fields.

Summary

To get a list of issues with all their custom fields:

  1. Use Get Issues List request:

    GET /api/issues?[fields]

  2. In the fields request parameter specify issue attributes you want to get in response including necessary attributes of its customFields.

Step-by-Step

We will start with a piece-by-piece description of the request to get a specific issue with its custom fields. Then, we extrapolate the principe to the issues list.

Get an Issue with Its Custom Fields

  1. To get an issue with values of all its custom fields, send a GET request to the target issue. You can use either issue idReadable (for example, SP-8) or issues's entity id (for example, 2-7) to reference issue.

    GET /api/issues/{issueID}?[fields]

    Read more about operations with an issue

  2. The fields request parameter is the comma-separated list of the returned entity (in this case - Issue) attributes to return in the server response.

    You can request any set of supported attributes of the returned entity. For an issue, see the list of supported attributes.

    In this how-to, we request the following data:

    ?fields=$type,id,summary,customFields($type,id,projectCustomField($type,id,field($type,id,name)),value($type,avatarUrl,buildLink,color(id),fullName,id,isResolved,localizedName,login,minutes,name,presentation,text))'
    • $type - the entity type. YouTrack returns the $type for all entities in the response regardless of whether you specify it in request explicitly or not.

    • id - a unique ID of the returned entity in the database.

    • summary - issue summary.

    • customFields - an attribute of the returned Issue entity that contains a collection of the issue custom fields. This is the target of our how-to.

  3. Notice the attributes we get for custom fields:

    ?customFields($type,id,projectCustomField($type,id,field($type,id,name)),value($type,avatarUrl,buildLink,color(id),fullName,id,isResolved,localizedName,login,minutes,name,presentation,text))'
    • projectCustomField - each IssueCustomField contains settings of a ProjectCustomField in a particular issue.

    • field - respectively, each ProjectCustomField contains settings of a CustomField in a particular project.

    • value - whereas CustomField is the most common entity, IssueCustomField is the most special and includes field value in a particular issue. Value can be just a simple one (string, integer,..), link to some entity (link to particular user for Assignee field) or a collection of values (Affected versions field). So, we get value attributes for all its types.

    Read more about custom fields hierarchy.

The final request is the following:

curl -X GET \ 'https://example.youtrack.cloud/api/issues/SP-8?fields=$type,id,summary,customFields($type,id,projectCustomField($type,id,field($type,id,name)),value($type,avatarUrl,buildLink,color(id),fullName,id,isResolved,localizedName,login,minutes,name,presentation,text))' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer perm:amFuZS5kb2U=.UkVTVCBBUEk=.wcKuAok8cHmAtzjA6xlc4BrB4hleaX' \ -H 'Cache-Control: no-cache' \ -H 'Content-Type: application/json'

The server response is the following:

{ "id":"2-7", "summary":"Issue from REST #1", "$type":"Issue", "customFields":[ { "id":"92-1", "$type":"SingleEnumIssueCustomField", "projectCustomField":{ "id":"92-1", "$type":"EnumProjectCustomField", "field":{ "id":"58-1", "$type":"CustomField", "name":"Priority" }, }, "value":{ "id":"67-3", "$type":"EnumBundleElement", "name":"Normal", "localizedName":null, "color":{ "id":"17", "$type":"FieldStyle" } } }, { "id":"92-3", "$type":"StateIssueCustomField", "projectCustomField":{ "id":"92-3", "$type":"StateProjectCustomField", "field":{ "id":"58-3", "$type":"CustomField", "name":"State" } }, "value":{ "id":"69-7", "$type":"StateBundleElement", "name":"Fixed", "isResolved":true, "localizedName":null, "color":{ "id":"0", "$type":"FieldStyle" } } }, { "id":"94-0", "$type":"SingleUserIssueCustomField", "projectCustomField":{ "id":"94-0", "$type":"UserProjectCustomField", "field":{ "id":"58-4", "$type":"CustomField", "name":"Assignee" } }, "value":{ "id":"1-2", "$type":"User", "name":"John Doe", "fullName":"John Doe", "login":"john.doe", "avatarUrl": "/hub/api/rest/avatar/cd939d5e-4c15-4080-98cd-0cde0cb3c19f?s=48" } }, { "id":"92-0", "$type":"SingleOwnedIssueCustomField", "projectCustomField":{ "id":"92-0", "$type":"OwnedProjectCustomField", "field":{ "id":"58-0", "$type":"CustomField", "name":"Subsystem" } }, "value":{ "id":"134-0", "$type":"OwnedBundleElement", "name":"Documentation", "color":{ "id":"12", "$type":"FieldStyle" } } }, { "id":"92-4", "$type":"MultiVersionIssueCustomField", "projectCustomField":{ "id":"92-4", "$type":"VersionProjectCustomField", "field":{ "id":"58-5", "$type":"CustomField", "name":"Fix versions" } }, "value":[ { "id":"133-19", "$type":"VersionBundleElement", "name":"2019.1", "color":{ "id":"3", "$type":"FieldStyle" } } ] }, { "id":"92-6", "$type":"SingleBuildIssueCustomField", "projectCustomField":{ "id":"92-6", "$type":"BuildProjectCustomField", "field":{ "id":"58-7", "$type":"CustomField", "name":"Fixed in build" } }, "value":{ "id":"135-0", "$type":"BuildBundleElement", "name":"48733", "buildLink":null, "color":{ "id":"0", "$type":"FieldStyle" } }, } ] }

Get Issues List with Custom Fields

To get this data for each issue, simply remove the {issueID} from the endpoint URL. For example:

curl -X GET \ 'https://example.youtrack.cloud/api/issues?fields=id,summary,customFields(id,projectCustomField(field(name)),value(name))' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer perm:amFuZS5kb2U=.UkVTVCBBUEk=.wcKuAok8cHmAtzjA6xlc4BrB4hleaX' \ -H 'Cache-Control: no-cache' \ -H 'Content-Type: application/json'
Last modified: 7 November 2024