Fields Syntax
In the YouTrack REST API, when you send an HTTP request to a resource, the server returns only the database ID and $type of the resource entity by default. To include other attributes in the response, specify them explicitly in the fields parameter of the 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.
Field Expressions
Use a comma-separated list of attribute names as the value of fields. To request nested data, follow the structure of the JSON object in the response. For nested entities and collections, put the attributes you need in parentheses after the entity or collection name. The following expressions apply to an Issue entity.
Selection | Example expression | Returned data |
|---|---|---|
Top-level attributes |
| Issue ID and summary. |
Nested entity attributes |
| Name of the issue's project. |
Nested collection attributes |
| ID and name of each issue custom field. |
Combined selections |
| Issue ID, summary, and project name. |
For example, pass the combined expression as the fields query parameter:
Start with a small set of top-level fields, inspect the response, and then extend the expression with nested attributes as needed.
Examples
The following examples start with a request without fields, then show how to select top-level and nested attributes. They also cover issue custom fields and work item data.
Request without Fields Parameter
This request omits the fields parameter.
Request
Response body
The response contains the user's database id and $type:
Request with Fields Parameter
This request uses fields to select the current user's id, login, name, and email attributes.
Request
Response body
The response contains the requested attributes and $type:
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
The response contains the requested top-level and nested attributes, along with entity $type values:
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.