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.

Samples

Request without Fields Parameter

Here we use a default request without providing the fields parameter.

Request

          curl -X GET 'https://example.youtrack.cloud/api/users/me' \
          -H 'Accept: application/json' \
          -H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \
          -H 'Cache-Control: no-cache'
        

Response body

In response, the server sends the entity ID:

          {
            "id": "1-2"
          }
        

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

          curl -X GET \
          'https://example.youtrack.cloud/api/users/me?fields=id,login,name,email' \
          -H 'Accept: application/json' \
          -H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \
          -H 'Cache-Control: no-cache'
        

Response body

In response, the server sends the requested attributes:

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

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 perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \
          -H 'Cache-Control: no-cache'
        

Response body

In response, the server sends only the requested top-level and nested attributes:

          [
            {
              "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"
            }
          ]
        

16 April 2026