---
schema: rendered-html/v1
title: "Add Value to a Set | Developer Portal for YouTrack and Hub Documentation"
source_url: https://www.jetbrains.com/help/youtrack/devportal/api-usecase-add-value-to-bundle.html
generated_at: 2026-06-11T15:01:13.382395+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
- REST API Reference
- REST API Use Cases
- Create an Issue
- Create an Issue and Set Custom Fields
- Get Issues List with All Values
- Get Value for an Issue Custom Field
- [Add Value to a Set](api-usecase-add-value-to-bundle.html)
- Update Issue Custom Fields
- [Update a Text Field Value](jetbrains__com__help__youtrack__devportal__api-usecase-update-text-field-value.md)
- Clear Values of Custom Fields
- [Apply Commands to Issues](jetbrains__com__help__youtrack__devportal__api-usecase-commands.md)
- Tag or Untag Issues
- [Work with Issue Tags](jetbrains__com__help__youtrack__devportal__api-usecase-work-with-tags.md)
- [Attach Files to an Issue](jetbrains__com__help__youtrack__devportal__api-usecase-attach-files.md)
- [Delete an Issue Attachment](jetbrains__com__help__youtrack__devportal__api-usecase-delete-issue-attachment.md)
- [Download an Issue Attachment](jetbrains__com__help__youtrack__devportal__api-usecase-download-issue-attachment.md)
- Link Issues
- [Get Issue History](jetbrains__com__help__youtrack__devportal__api-usecase-issue-history.md)
- [Get a Database Backup](jetbrains__com__help__youtrack__devportal__api-usecase-backup.md)
- Add User to Project Team
- REST API Troubleshooting
- Color Indices List
- Hub REST API

1. YouTrack REST API
2. REST API Use Cases
3. [Add Value to a Set](#0)

# Add Value to a Set﻿

Last modified: 07 May 2026

## 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﻿

1. Get the list of all projects in your YouTrack.

   ```
   curl -X GET 'https://example.youtrack.cloud/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.youtrack.cloud/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.youtrack.cloud/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"
       }
   ]
   ```
2. 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`.
3. Get the list of all custom fields attached to the target project using the project ID you retrieved.

   ```
   curl -X GET 'https://example.youtrack.cloud/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"
       }
   ]
   ```
4. Locate the `ID` of the target custom field. This example uses the field `Fix versions` with the entity ID `82-4`.
5. 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.
6. 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.
7. 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.
8. 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.
9. Add a new value to the bundle of the target custom field with a POST request:

   ```
   curl -X POST 'https://example.youtrack.cloud/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.

- [Add Value to a Set](/help/youtrack/devportal/api-usecase-add-value-to-bundle.html)
- [Use Case](/help/youtrack/devportal/api-usecase-add-value-to-bundle.html#use-case)
- [Summary](/help/youtrack/devportal/api-usecase-add-value-to-bundle.html#summary)
- [Step-by-Step](/help/youtrack/devportal/api-usecase-add-value-to-bundle.html#step-by-step)

Get Value for an Issue Custom FieldUpdate Issue Custom Fields

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

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