Developer Portal for YouTrack and Hub Help

Operations with Specific IssueCustomField

This resource lets you work with custom fields of the issue.

Resource

/api/issues/{issueID}/customFields/{fieldID}

Returned entity

IssueCustomField. For the description of the entity attributes, see Supported Fields section.

Supported methods

IssueCustomField attributes

Represents a custom field along with its value in the particular issue.

The IssueCustomField is an abstract ancestor for all types of custom fields in issues. The actual type of the custom field depends on field settings in the particular project.

Each IssueCustomField entity, regardless of its type, has the following attributes:

  • $type: the unique type of the issue custom field. You must provide this attribute when you update the custom field in an issue.

  • id: the entity ID of the issue custom field.

  • name: the string name of the custom field.

  • projectCustomField: the reference to the settings of the custom field in the project.

  • value: the value assigned to the custom field in the issue. Depending on the type of the field, this attribute can store a single value or an array of values.

This table describes attributes of the IssueCustomField entity.

  • To receive an attribute in the response from the server, specify it explicitly in the fields request parameter.

  • To update an attribute, provide it in the body of a POST request.

Field

Type

Description

id

String

The ID of the custom field in the issue. Read-only.

name

String

The name of the custom field. Read-only.

projectCustomField

ProjectCustomField

Reference to the custom field settings for the particular project. Read-only.

value

The value assigned to the custom field in the issue. Depending on the type of the field, this attribute can store a single value or an array of values. Read-only.

Read a Specific IssueCustomField

Get a specific custom field in the issue.

Required permissions

For a public field, Read Issue permission is required. For a private field, Read Issue Private Fields is required.

Request syntax

GET /api/issues/{issueID}/customFields/{fieldID}?{fields}

{fieldID}

The entity ID of the target custom field in the issue.

Request parameters

Parameter

Type

Description

fields

String

A list of IssueCustomField attributes that should be returned in the response. If no field is specified, only the entityID is returned.

Sample 1

Sample request

https://example.youtrack.cloud/api/issues/2-7/fields/92-1?fields=id,name,value(id,name)

Sample response body

{ "value": { "name": "Major", "id": "67-2", "$type": "EnumBundleElement" }, "name": "Priority", "id": "92-1", "$type": "SingleEnumIssueCustomField" }

Sample 2

Let's read an issue custom field that is regulated by a state-machine workflow rule. Let's request the possibleEvents attribute that is specific to this type of custom field in an issue. You will need a value of this attribute if you need to update this custom field in this issue.

Sample request

https://example.youtrack.cloud/api/issues/NP-163/fields/82-11?fields=id,name,value(id,name),possibleEvents(id,presentation)

Sample response body

{ "possibleEvents": [ { "presentation": "Can't Reproduce", "id": "cannot-reproduce", "$type": "Event" }, { "presentation": "In Progress", "id": "in-progress", "$type": "Event" }, { "presentation": "Won't fix", "id": "wont-fix", "$type": "Event" } ], "value": { "name": "Open", "id": "57-19", "$type": "StateBundleElement" }, "name": "State", "id": "82-11", "$type": "StateMachineIssueCustomField" }

Update a Specific IssueCustomField

Update specific custom field in the issue.

To update a custom field in the issue, you must specify:

  1. The required value for the target custom field. You can identify the value by its name or entity ID.

  2. $type of the target issue custom field.

Required permissions

For a public field, Create Issue permission is required for the issue reporter and Update Issue permission otherwise.For a private field, Update Issue Private Fields is required.

Request syntax

POST /api/issues/{issueID}/customFields/{fieldID}?{fields}&{muteUpdateNotifications}

{fieldID}

The entity ID of the target custom field in the issue.

Request parameters

Parameter

Type

Description

fields

String

A list of IssueCustomField attributes that should be returned in the response. If no field is specified, only the entityID is returned.

muteUpdateNotifications

Boolean

Set this parameter to true if no notifications should be sent on changes made by this request. This doesn't mute notifications sent by any workflow rules. Using this parameter requires Apply Commands Silently permission in all projects affected by the request. Available since 2021.3.

Sample 1

Let's change the Priority field of the issue, and set its value to Normal. To check that the request was successful, we instruct the server to return the field's value in the response body.

Sample request

https://example.youtrack.cloud/api/issues/2-7/fields/92-1?fields=id,name,value(id,name)

Sample request body

{ "value": { "name": "Normal" } }

Sample response body

{ "value": { "name": "Normal", "id": "67-3", "$type": "EnumBundleElement" }, "name": "Priority", "id": "92-1", "$type": "SingleEnumIssueCustomField" }

Sample 2

To update an issue custom field that is regulated by a state-machine workflow rule, you'll need to pass an ID of a transition event with the request body.

Possible transition events are regulated by the state-machine rule. You can check the list of possible transitions from a particular state by making a GET request to the issue first. Check the corresponding sample above.

Sample request

https://example.youtrack.cloud/api/issues/NP-163/fields/82-11?fields=id,name,value(id,name)

Sample request body

{ "event": { "presentation": "In Progress", "id": "in-progress", "$type": "Event" }, "id": "82-11", "$type": "StateMachineIssueCustomField" }

Sample response body

{ "value": { "name": "In Progress", "id": "57-263", "$type": "StateBundleElement" }, "name": "State", "id": "82-11", "$type": "StateMachineIssueCustomField" }
Last modified: 19 September 2022