llms.txt: machine-readable documentation index. Markdown version of this page is also available.

YouTrack Developer Portal Help

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

idReadable,summary

Issue ID and summary.

Nested entity attributes

project(name)

Name of the issue's project.

Nested collection attributes

customFields(id,name)

ID and name of each issue custom field.

Combined selections

idReadable,summary,project(name)

Issue ID, summary, and project name.

For example, pass the combined expression as the fields query parameter:

curl -X GET \ 'https://example.youtrack.cloud/api/issues?fields=idReadable,summary,project(name)' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer <YouTrack_token>'

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

curl -X GET 'https://example.youtrack.cloud/api/users/me' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer <YouTrack_token>'

Response body

The response contains the user's database id and $type:

{ "id": "1-2", "$type": "User" }

Request with Fields Parameter

This request uses fields to select the current user's id, login, name, and email attributes.

Request

curl -X GET \ 'https://example.youtrack.cloud/api/users/me?fields=id,login,name,email' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer <YouTrack_token>'

Response body

The response contains the requested attributes and $type:

{ "email": "john.doe@example.com", "login": "john.doe", "name": "John Doe", "id": "1-2", "$type": "User" }

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

curl -X GET \ 'https://example.youtrack.cloud/api/issues?fields=id,idReadable,summary,project(name),customFields(id,name,value(name,login,fullName))' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer <YouTrack_token>'

Response body

The response contains the requested top-level and nested attributes, along with entity $type values:

[ { "customFields": [ { "name": "Priority", "value": { "name": "Major", "$type": "EnumBundleElement" }, "id": "92-1", "$type": "SingleEnumIssueCustomField" }, { "name": "Assignee", "value": { "login": "jane.doe", "fullName": "Jane Doe", "name": "Jane Doe", "$type": "User" }, "id": "94-0", "$type": "SingleUserIssueCustomField" } ], "project": { "name": "Sample Project", "$type": "Project" }, "summary": "REST API lets you create issues!", "idReadable": "SP-13", "id": "2-142", "$type": "Issue" } ]

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.

curl -X GET \ 'https://example.youtrack.cloud/api/issues?fields=idReadable,summary,customFields(name,value(name))&customFields=Priority&customFields=State' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer <YouTrack_token>'

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:

curl -X GET \ 'https://example.youtrack.cloud/api/workItems?fields=id,text,duration(minutes),attributes(id,value(name))' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer <YouTrack_token>'

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:

curl -X GET \ 'https://example.youtrack.cloud/api/workItems?fields=id,issue(idReadable,summary,customFields(name,value(name)))&customFields=Priority&customFields=State' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer <YouTrack_token>'

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.

10 November 2026