Developer Portal for YouTrack and Hub Help

Custom Fields in REST API

This page describes the hierarchy of custom fields in YouTrack and how the CustomField, ProjectCustomField, and IssueCustomField entities differ from each other.

CustomField

CustomField is an entity that defines a common custom field which contains basic attributes like name and fieldType. The instances property contains the settings for this field in different projects.

For the complete list of the CustomField attributes, see CustomField.

The following sample shows how to get all custom fields in YouTrack. By default, YouTrack returns only the $type attribute of the requested entities. To get more information about custom fields, we explicitly provide a list of returned entity attributes in the fields parameter of the request. The $type attribute will appear in the response regardless of whether you specify it explicitly or not.

Sample Request

curl -X GET \ 'https://example.youtrack.cloud/api/admin/customFieldSettings/customFields?fields=id,name,aliases,instances(id,project(id,name))' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \ -H 'Cache-Control: no-cache' \ -H 'Content-Type: application/json'

Sample Response Body

[ ... { "name": "Priority", "aliases": null, "instances": [ { "project": { "name": "Sample Project", "id": "0-0", "$type": "Project" }, "id": "92-1", "$type": "EnumProjectCustomField" }, ... ], "id": "58-1", "$type": "CustomField" }, ... { "name": "Assignee", "aliases": "for, assigned to", "instances": [ { "project": { "name": "Sample Project", "id": "0-0", "$type": "Project" }, "id": "94-0", "$type": "UserProjectCustomField" }, ... ], "id": "58-4", "$type": "CustomField" }, ... ]

ProjectCustomField

ProjectCustomField is an entity that contains settings of a CustomField (the field attribute) in a particular project (project), such as the set of possible values (bundle), whether the field can be empty or not (canBeEmpty), and so on.

For the complete list of the ProjectCustomField attributes, see ProjectCustomField.

The following sample shows how to get all custom fields with their settings in a particular project.

Sample Request

curl -X GET \ 'https://example.youtrack.cloud/api/admin/projects/0-0/customFields?fields=id,canBeEmpty,emptyFieldText,project(id,name),field(id,name)' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \ -H 'Cache-Control: no-cache' \ -H 'Content-Type: application/json'

Sample Response Body

[ ... { "field": { "name": "Priority", "id": "58-1", "$type": "CustomField" }, "project": { "name": "Sample Project", "id": "0-0", "$type": "Project" }, "emptyFieldText": "No Priority", "canBeEmpty": false, "id": "92-1", "$type": "EnumProjectCustomField" }, ... { "field":{ "id":"58-4", "name":"Assignee", "$type":"CustomField" }, "project": { "name": "Sample Project", "id": "0-0", "$type": "Project" }, "emptyFieldText":"Unassigned", "canBeEmpty":true, "id":"94-0", "$type":"UserProjectCustomField" }, ... ]

IssueCustomField

The IssueCustomField entity contains the value (the value attribute) of a ProjectCustomField (projectCustomField) in a particular issue. The value can be a simple one (for example, string or integer), a link to an existing entity (a link to a specific user for the Assignee field), or a collection of values (the Affected versions field).

For the complete list of the IssueCustomField attributes, see IssueCustomField.

The following sample shows how to get all custom fields with their values in a particular issue.

Sample Request

curl -X GET \ 'https://example.youtrack.cloud/api/issues/2-7/customFields?fields=id,value(id,name,login,fullName),projectCustomField(id,field(id,name))' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \ -H 'Cache-Control: no-cache' \ -H 'Content-Type: application/json'

Sample Response Body

[ { "projectCustomField": { "field": { "name": "Priority", "id": "58-1", "$type": "CustomField" }, "id": "92-1", "$type": "EnumProjectCustomField" }, "value": { "name": "Major", "id": "67-2", "$type": "EnumBundleElement" }, "id": "92-1", "$type": "SingleEnumIssueCustomField" }, ... { "projectCustomField": { "field": { "name": "Assignee", "id": "58-4", "$type": "CustomField" }, "id": "94-0", "$type": "UserProjectCustomField" }, "value":{ "name": "Jane Doe", "fullName": "Jane Doe", "login": "jane.doe", "id": "1-3", "$type": "User" }, "id": "94-0", "$type": "SingleUserIssueCustomField" }, ... ]

$type Mapping for Custom Fields

The following table shows the mapping between supported issue custom fields and their corresponding $type values. You must provide the $type value in the POST request when you need to set or update a custom field in an issue.

Custom Field Type

IssueCustomField $type

ProjectCustomField $type

enum[1]

SingleEnumIssueCustomField

EnumProjectCustomField

enum[*]

MultiEnumIssueCustomField

EnumProjectCustomField

build[1]

SingleBuildIssueCustomField

BuildProjectCustomField

build[*]

MultiBuildIssueCustomField

BuildProjectCustomField

state[1]

StateIssueCustomField

StateProjectCustomField

version[1]

SingleVersionIssueCustomField

VersionProjectCustomField

version[*]

MultiVersionIssueCustomField

VersionProjectCustomField

ownedField[1]

SingleOwnedIssueCustomField

OwnedProjectCustomField

ownedField[*]

MultiOwnedIssueCustomField

OwnedProjectCustomField

user[1]

SingleUserIssueCustomField

UserProjectCustomField

user[*]

MultiUserIssueCustomField

UserProjectCustomField

group[1]

SingleGroupIssueCustomField

GroupProjectCustomField

group[*]

MultiGroupIssueCustomField

GroupProjectCustomField

integer

SimpleIssueCustomField

SimpleProjectCustomField

float

SimpleIssueCustomField

SimpleProjectCustomField

date

DateIssueCustomField

SimpleProjectCustomField

date and time

SimpleIssueCustomField

SimpleProjectCustomField

period

PeriodIssueCustomField

PeriodProjectCustomField

string

SimpleIssueCustomField

SimpleProjectCustomField

text

TextIssueCustomField

TextProjectCustomField

21 March 2025