Get a Value for an Issue Custom Field

Get the list of issues in a target project. Also, let's request the list of available custom fields with their names.

            curl -X GET 'https://example.youtrack.cloud/api/issues?query=in:SP&fields=id,idReadable,summary,customFields(id,projectCustomField(field(name)))' \
            -H 'Accept: application/json' \
            -H 'Authorization: Bearer <YouTrack_token>'
        

The query request parameter lets us filter the list of issues by the target project, in the sample the projects shortName is `SP`.

In the fields request parameter, we instruct the server to return the following attributes for each issue found:

id and idReadable - both database entity ID and an ID of the issue in the project, respectively.
summary - issue's summary may help to identify the target issue.
customFields - a list of custom fields for each issue. To help us identify the target custom field, we also request the name of each field which is defined through the project custom field and its "prototype" - the generic custom field.

In the response to this request, the server returns the following data:

            [
              {
                "summary": "Issue from REST #1",
                "idReadable": "SP-8",
                "customFields": [
                  {
                    "projectCustomField": {
                      "field": {
                        "name": "Priority",
                        "$type": "CustomField"
                      },
                      "$type": "EnumProjectCustomField"
                    },
                    "id": "92-1",
                    "$type": "SingleEnumIssueCustomField"
                  },
                  {
                    "projectCustomField": {
                      "field": {
                        "name": "Type",
                        "$type": "CustomField"
                      },
                      "$type": "EnumProjectCustomField"
                    },
                    "id": "92-2",
                    "$type": "SingleEnumIssueCustomField"
                  },
                  {
                    "projectCustomField": {
                      "field": {
                        "name": "State",
                        "$type": "CustomField"
                      },
                      "$type": "StateProjectCustomField"
                    },
                    "id": "92-3",
                    "$type": "StateIssueCustomField"
                  },
                  {
                    "projectCustomField": {
                      "field": {
                        "name": "Assignee",
                        "$type": "CustomField"
                      },
                      "$type": "UserProjectCustomField"
                    },
                    "id": "94-0",
                    "$type": "SingleUserIssueCustomField"
                  },
                  {
                    "projectCustomField": {
                      "field": {
                        "name": "Subsystem",
                        "$type": "CustomField"
                      },
                      "$type": "OwnedProjectCustomField"
                    },
                    "id": "92-0",
                    "$type": "SingleOwnedIssueCustomField"
                  },
                  {
                    "projectCustomField": {
                      "field": {
                        "name": "Fix versions",
                        "$type": "CustomField"
                      },
                      "$type": "VersionProjectCustomField"
                    },
                    "id": "92-4",
                    "$type": "MultiVersionIssueCustomField"
                  },
                  {
                    "projectCustomField": {
                      "field": {
                        "name": "Affected versions",
                        "$type": "CustomField"
                      },
                      "$type": "VersionProjectCustomField"
                    },
                    "id": "92-5",
                    "$type": "MultiVersionIssueCustomField"
                  },
                  {
                    "projectCustomField": {
                      "field": {
                        "name": "Fixed in build",
                        "$type": "CustomField"
                      },
                      "$type": "BuildProjectCustomField"
                    },
                    "id": "92-6",
                    "$type": "SingleBuildIssueCustomField"
                  }
                ],
                "id": "2-7",
                "$type": "Issue"
              },
              {
                "summary": "Sprint 3. Task 2",
                "idReadable": "SP-38",
                "customFields": [
                  ...
                ],
                "id": "2-42",
                "$type": "Issue"
              },
              {
                "summary": "Sprint3. Task 1",
                "idReadable": "SP-37",
                "customFields": [
                  ...
                ],
                "id": "2-40",
                "$type": "Issue"
              },
              ...
            ]
        

Locate the ID of the target issue. For the sample, let's take the issue SP-8 with the entity id 2-7.

Locate the ID of a target custom field. Let's get the current State of the issue. In the sample, the ID of the State field is 92-3.

Form a list of attributes that you want to get for the State field.

A list of supported attributes for a custom field depends entirely on its type.

A State field has $type of StateIssueCustomField. It binds a project custom field of the type StateProjectCustomField and a value. A StateProjectCustomField uses a bundle of values of the type StateBundle. And a StateBundle stores values of the type StateBundleElement. Thus, to form a list of attributes that we want to get for the current value of the State field, we need to check the JSON schema and see what attributes the StateBundleElement entity contains.

For the sample, we picked these:

Attribute	Description
`name`	The name of the value. It represents the actual State that users see in UI: Open, In Progress, Fixed, and so on.
`localizedName`	If the server does not use the default locale, this attribute stores the name of the value in the selected locale.
`isResolved`	Indicates if the value - the state - is considered as resolved.
`id`	The entity ID of the value.

To verify that we get the correct field in the sample, we also request the name of the field and its ID.

So, when we put together all the attributes that we want to receive from the server, the request parameter fields looks as follows:

            fields=id,projectCustomField(id,field(name)),value(id,isResolved,localizedName,name)
        

Now that we collected all the data that is required for the request, this is the resulting request for the field value:

            curl -X GET \
            'https://example.youtrack.cloud/api/issues/SP-8/customFields/92-3?fields=id,projectCustomField(id,field(id,name)),value(id,isResolved,localizedName,name)' \
            -H 'Accept: application/json' \
            -H 'Authorization: Bearer <YouTrack_token>'
        

For this request, the server returns the following response body:

            {
                "projectCustomField": {
                    "field": {
                        "name": "State",
                        "id": "58-3",
                        "$type": "CustomField"
                    },
                    "id": "92-3",
                    "$type": "StateProjectCustomField"
                },
                "value": {
                    "isResolved": true,
                    "localizedName": null,
                    "name": "Fixed",
                    "id": "69-7",
                    "$type": "StateBundleElement"
                },
                "id": "92-3",
                "$type": "StateIssueCustomField"
            }
        

If the target custom field stores a string value, request value without nested attributes. String fields use SimpleIssueCustomField, and their value is returned as a JSON string.

            curl -X GET \
            'https://example.youtrack.cloud/api/issues/SP-8/customFields/92-7?fields=id,projectCustomField(id,field(id,name)),value' \
            -H 'Accept: application/json' \
            -H 'Authorization: Bearer <YouTrack_token>'
        

For a string field, the response body looks like this:

            {
                "projectCustomField": {
                    "field": {
                        "name": "Requester email",
                        "id": "58-7",
                        "$type": "CustomField"
                    },
                    "id": "92-7",
                    "$type": "SimpleProjectCustomField"
                },
                "value": "test@example.com",
                "id": "92-7",
                "$type": "SimpleIssueCustomField"
            }
        

Developer Portal for YouTrack and Hub Help

Summary

Additional Information

Step-by-Step