Add Value to a Set

Use Case:

Use the REST API to add a new value to a set of values for a custom field in a specific project. In the REST API, the entity that represents a set of values for a custom field is called a bundle.

Summary

Before you add a new value to a bundle, you need to collect the following data:

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

When you have all necessary entity IDs, you can add a new value to the bundle by sending a POST request to this endpoint:

/api/admin/projects/{project_id}/customFields/{field_id}/bundle/values

Step-by-Step

Get the list of all projects in your YouTrack.

curl -X GET 'https://example.myjetbrains.com/youtrack/api/admin/projects?fields=id,name,shortName' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer perm:cm9vdA==.MjZGZWI=.WB02vjX0cM2ltLTJXUE3VOWHpJYYNx' \ -H 'Content-Type: application/json'

In the fields request parameter, you instruct the server to return the ID, name, and shortName attributes of each project found.

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

[ { "shortName": "NP", "name": "New Project", "id": "81-1", "$type": "Project" }, { "shortName": "T", "name": "Tasks", "id": "81-22", "$type": "Project" }, { "shortName": "TP", "name": "Test Project", "id": "81-0", "$type": "Project" } ]

You can also filter the list of projects by shortName or a name of the required project.

Here’s an example of a request with the filter by a project's name:

curl -X GET 'https://example.myjetbrains.com/youtrack/api/admin/projects?fields=id,name,shortName&query=Test+Project' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer perm:cm9vdA==.MjZGZWI=.WB02vjX0cM2ltLTJXUE3VOWHpJYYNx' \ -H 'Content-Type: application/json'

Here’s an example of a request with the filter by a project's shortName:

curl -X GET 'https://example.myjetbrains.com/youtrack/api/admin/projects?fields=id,name,shortName&query=tp' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer perm:cm9vdA==.MjZGZWI=.WB02vjX0cM2ltLTJXUE3VOWHpJYYNx' \ -H 'Content-Type: application/json'

To the sample request with the query parameter, the response body contains data only for the matching project:

[ { "shortName": "TP", "name": "Test Project", "id": "81-0", "$type": "Project" } ]
Locate the ID of the target project in the response you received. This example uses the project Test Project with the entity ID 81-0.
Get the list of all custom fields attached to the target project using the project ID you retrieved.

curl -X GET 'https://example.myjetbrains.com/youtrack/api/admin/projects/81-0/customFields?fields=id,field(name)' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer perm:cm9vdA==.MjZGZWI=.WB02vjX0cM2ltLTJXUE3VOWHpJYYNx' \ -H 'Content-Type: application/json'

In the fields request parameter, you instruct the server to return the ID and name attributes of each custom field.

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

[ { "field": { "name": "Subsystem", "$type": "CustomField" }, "id": "82-0", "$type": "OwnedProjectCustomField" }, { "field": { "name": "Type", "$type": "CustomField" }, "id": "82-2", "$type": "EnumProjectCustomField" }, { "field": { "name": "State", "$type": "CustomField" }, "id": "82-3", "$type": "StateProjectCustomField" }, { "field": { "name": "Fix versions", "$type": "CustomField" }, "id": "82-4", "$type": "VersionProjectCustomField" } ]
Locate the ID of the target custom field. This example uses the field Fix versions with the entity ID 82-4.
To form the URL for the final POST request, you need to check the attributes of the target field type. You can find the field type in the response with the list of all project custom fields you got earlier.

In this case, the field Fix versions is of VersionProjectCustomField type. Since you want to update the field bundle, you need the bundle attribute.
A bundle as an entity has its own attributes which you can check according to the bundle type.

In this case, the bundle of a VersionProjectCustomField is a VersionBundle. Since you want to update the set of its values, you need the values attribute.
Form the full request URL:

/api/admin/projects/81-0/customFields/82-4/bundle/values?fields=id,name

In the fields request parameter, you instruct the server to return the ID and the name of the value that you add.
To form a body for your POST request, you need to check the attributes of the element that you’re adding. In this case, a VersionBundle contains an array of VersionBundleElements as values, so you need to add one more VersionBundleElement to the array. The only attribute that you need to set is the name of the new value:

{ "name": "V.2.0", "$type": "VersionBundleElement" }

Notice that you must include the $type parameter in each request. For more information about $type in POST requests, check the documentation.
Add a new value to the bundle of the target custom field with a POST request:

curl -X POST 'https://example.myjetbrains.com/youtrack/api/admin/projects/81-0/customFields/82-4/bundle/values?fields=id,name' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer perm:cm9vdA==.MjZGZWI=.WB02vjX0cM2ltLTJXUE3VOWHpJYYNx' \ -H 'Content-Type: application/json' \ -d '{"name": "V.2.0", "$type": "VersionBundleElement"}'

If the request is successful, you’ll get the following response:

{ "name":"V.2.0", "id":"103-433", "$type":"VersionBundleElement" }

It contains the ID, name, and type of the added value.

As a result, you’ve added a new element to the set of values (bundle) for the Fix versions field in the Test Project project.

Following similar steps, you can also add new values to the sets of values for other field types: BuildBundle, EnumBundle, OwnedBundle, StateBundle.

Last modified: 28 October 2020