---
schema: rendered-html/v1
title: "Fields Syntax | Developer Portal for YouTrack and Hub Documentation"
source_url: https://www.jetbrains.com/help/youtrack/devportal/api-fields-syntax.html
generated_at: 2026-06-11T14:59:37.708044+00:00
---

Feedback

Thanks for your feedback!

Was this page helpful?

YesNo

Developer Portal for YouTrack and Hub

- Developer Portal
- Apps
- MCP Tools
- YouTrack Workflows
- YouTrack Import Scripts
- YouTrack Form API
- YouTrack REST API
- [Get Started with REST API](jetbrains__com__help__youtrack__devportal__api-getting-started.md)
- [Log in to YouTrack](jetbrains__com__help__youtrack__devportal__api-log-in-to-youtrack.md)
- REST API URL and Endpoints
- OpenAPI Specification (OAS)
- [Fields Syntax](api-fields-syntax.html)
- Query Syntax
- Request Headers
- Custom Fields in REST API
- Pagination
- Users, Groups, and Access Management
- Hub REST API Endpoints Deprecated in YouTrack 2026.1
- Postman Collection for the YouTrack REST API
- REST API Reference
- REST API Use Cases
- REST API Troubleshooting
- Color Indices List
- Hub REST API

1. YouTrack REST API
2. [Get Started with REST API](jetbrains__com__help__youtrack__devportal__api-getting-started.md)
3. [Fields Syntax](#0)

# Fields Syntax﻿

Last modified: 07 May 2026

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"
  }
]
```

- [Fields Syntax](/help/youtrack/devportal/api-fields-syntax.html)
- [How to Find Available Field Names](/help/youtrack/devportal/api-fields-syntax.html#find-field-names)
- [Samples](/help/youtrack/devportal/api-fields-syntax.html#samples)
- [Request without Fields Parameter](/help/youtrack/devportal/api-fields-syntax.html#sample-default-request)
- [Request with Fields Parameter](/help/youtrack/devportal/api-fields-syntax.html#sample-request-with-fields)
- [Request with Nested Fields](/help/youtrack/devportal/api-fields-syntax.html#sample-request-with-nested-fields)

OpenAPI Specification (OAS)Query Syntax

- Privacy & Security
- Terms Of Use
- Trademarks
- Legal

Copyright © 2000–2026 JetBrains s.r.o.
