Fields Syntax
In YouTrack REST API, when you send an HTTP request to a resource, by default, the server sends back only the database ID and $type of the resource entity. To receive an attribute in the response from server, you must specify it explicitly in the fields parameter of a request.
How to Find Available Field Names
The field names that you can use in the fields parameter match the attributes of the entity returned by the resource that you request.
To find the available field names for a specific request, open the reference page for the corresponding entity. For example, if a request returns an Issue, check the Issue entity reference. If it returns a User, check the User entity reference.
To browse the available entity reference pages, open the Entities section of the API reference.
To request nested data, use the same structure as the JSON object in the response. For example, an Issue entity has attributes named project (entity) and customFields (array of entities), so you can request nested attributes as project(name) or customFields(id,name,value(name)).
If you are not sure which attributes you need, start with a small set of top-level fields, inspect the response, and then extend the fields parameter with nested attributes.
Select Specific Issue Custom Fields
Issue custom fields, such as Priority and State, belong to the Issue.customFields collection. When you request /api/issues, include customFields(...) in fields to specify the attributes to return for each issue custom field.
Use the separate customFields query parameter to select issue custom fields by name. Repeat this parameter for each custom field that you want to include.
Each returned issue contains the requested Priority and State custom fields. If you omit the customFields parameter, YouTrack returns all available issue custom fields when you request them in fields.
Request Work Item Attributes
The /api/workItems resource returns IssueWorkItem entities. Use fields to request work item attributes such as id, text, and duration.
Configurable work item attributes belong to the work item's attributes collection. To request their IDs and values, include attributes(id,value(name)) in fields:
Request Issue Custom Fields in Work Item Responses
To include data from a work item's related issue, use the nested issue(...) expression in fields. The following request includes the related issue's Priority and State custom fields in each work item response:
Here, customFields selects entries in the related issue's issue.customFields collection. It does not select entries in the work item's attributes collection. To filter the work item list by properties of the related issues, use query.
Samples
Request without Fields Parameter
Here we use a default request without providing the fields parameter.
Request
Response body
In response, the server sends the entity ID:
Request with Fields Parameter
Here we use the fields request parameter to specify explicitly which attributes of the entity should be returned in the response body: id, login, name, and email of the current user.
Request
Response body
In response, the server sends the requested attributes:
Request with Nested Fields
For entities with nested objects, you can request attributes from child objects and collections as well. In the following example, the fields parameter requests the issue ID and summary, the project name, and selected data for custom fields.
Request
Response body
In response, the server sends only the requested top-level and nested attributes: