Get Issues List with All Values
Use Case:
Use the REST API to get a list of issues with all their custom fields.
note
Please notice that this example is valid for YouTrack 2019.1 and later versions. In the previous versions, though the principle is the same, query parameters and entity attributes may differ. Also, a number of features, like addressing an entity by its name, were introduced in 2019.1 and are not supported in the previous versions.
Summary
To get a list of issues with all their custom fields:
Use Get Issues List request:
GET /api/issues?[fields]In the
fieldsrequest parameter specify issue attributes you want to get in response including necessary attributes of itscustomFields.
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
-
To get an issue with values of all its custom fields, send a
GETrequest to the target issue. You can use either issueidReadable(for example,SP-8) or issues's entityid(for example,2-7) to reference issue.GET /api/issues/{issueID}?[fields] -
The
fieldsrequest 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$typefor 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 returnedIssueentity that contains a collection of the issue custom fields. This is the target of our how-to.
-
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- eachIssueCustomFieldcontains settings of aProjectCustomFieldin a particular issue.field- respectively, eachProjectCustomFieldcontains settings of aCustomFieldin a particular project.value- whereasCustomFieldis the most common entity,IssueCustomFieldis 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 getvalueattributes for all its types.
The final request is the following:
curl -X GET \
'https://example.myjetbrains.com/youtrack/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.myjetbrains.com/youtrack/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'