Developer Portal for YouTrack and Hub Help

Replace the Set of Values for a Custom Field

Use the REST API to replace the set of values that is available for a custom field in a specific project. In the REST API, a set of values for a custom field is represented by a bundle entity.

This operation replaces the set of values that is assigned to the project custom field. It does not edit the values inside the original set. To add a value to the set that is already assigned to the field, see Add a Value to a Set.

For details about the public REST API endpoint, see Project Custom Fields.

Summary

When you have the required entity IDs, replace the set by sending a POST request to this endpoint:

/api/admin/projects/{projectID}/customFields/{fieldID}?fields={fields}

In the request body, set the bundle attribute to an object that contains the id and $type of the replacement set.

Step-by-Step

  1. Get the ID of the project where you want to replace the set of values for a custom field. For instructions, see Get a Project ID. This example uses the project Sample Project with the entity ID 0-121.

  2. Get the list of custom fields that are attached to the target project. See, Project Custom Fields.

    curl -X GET 'https://example.youtrack.cloud/api/admin/projects/0-121/customFields?fields=id,field(name,fieldType(valueType)),bundle(id,name,$type)' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer <YouTrack_token>' \ -H 'Content-Type: application/json'

    For such request, you get a response from the server with the following body:

    [ { "bundle": { "name": "Default Priorities", "id": "86-125", "$type": "EnumBundle" }, "field": { "name": "Priority", "fieldType": { "valueType": "enum", "$type": "FieldType" }, "$type": "CustomField" }, "id": "105-1088", "$type": "EnumProjectCustomField" }, { "bundle": { "name": "Types", "id": "85-12", "$type": "EnumBundle" }, "field": { "name": "Type", "fieldType": { "valueType": "enum", "$type": "FieldType" }, "$type": "CustomField" }, "id": "105-1089", "$type": "EnumProjectCustomField" } ]

    In the response, locate the field whose set of values you want to replace. This example uses the Priority field with the entity ID 105-1088.

  3. Check the current API entity type for the set of values in the target field. The replacement set must have the same API entity type.

    Field value type

    Set of values API entity

    enum

    EnumBundle

    state

    StateBundle

    version

    VersionBundle

    ownedField

    OwnedBundle

    build

    BuildBundle

    user

    UserBundle

  4. Get the list of available sets of values for the field type. For an enum field, use the endpoint for enum sets of values. See Enum Bundles.

    curl -X GET 'https://example.youtrack.cloud/api/admin/customFieldSettings/bundles/enum?fields=id,name,values(id,name)' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer <YouTrack_token>' \ -H 'Content-Type: application/json'

    For such request, you get response from the server with the following body:

    [ { "values": [ { "name": "Show-stopper", "id": "67-0", "$type": "EnumBundleElement" }, { "name": "Critical", "id": "67-1", "$type": "EnumBundleElement" } ], "name": "Default Priorities", "id": "86-125", "$type": "EnumBundle" }, { "values": [ { "name": "Major", "id": "67-2", "$type": "EnumBundleElement" }, { "name": "Normal", "id": "67-3", "$type": "EnumBundleElement" } ], "name": "Priorities", "id": "86-126", "$type": "EnumBundle" } ]

    Locate the replacement set in the response. This example uses a set represented by an EnumBundle entity with the entity ID 86-126.

  5. Replace the set for the target project custom field with a POST request.

    curl -X POST 'https://example.youtrack.cloud/api/admin/projects/0-121/customFields/105-1088?fields=id,field(name),bundle(id,name,values(id,name),$type),hasRunningJob' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer <YouTrack_token>' \ -H 'Content-Type: application/json' \ -d '{"bundle": {"id": "86-126", "$type": "EnumBundle"}}'

    If the request is successful, the response contains the project custom field with the set that is now attached to it.

    { "bundle": { "name": "Priorities", "id": "86-126", "values": [ { "name": "Major", "id": "67-2", "$type": "EnumBundleElement" }, { "name": "Normal", "id": "67-3", "$type": "EnumBundleElement" } ], "$type": "EnumBundle" }, "field": { "name": "Priority", "$type": "CustomField" }, "hasRunningJob": false, "id": "105-1088", "$type": "EnumProjectCustomField" }

  6. Optional. Check the project custom field after the replacement.

    curl -X GET 'https://example.youtrack.cloud/api/admin/projects/0-121/customFields/105-1088?fields=id,field(name),bundle(id,name,$type),hasRunningJob' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer <YouTrack_token>' \ -H 'Content-Type: application/json'

    For such request, you get response from the server with the following body:

    { "bundle": { "name": "Priorities", "id": "86-126", "$type": "EnumBundle" }, "field": { "name": "Priority", "$type": "CustomField" }, "hasRunningJob": false, "id": "105-1088", "$type": "EnumProjectCustomField" }

    If hasRunningJob is true, wait until the background operation for the field is complete before you make more changes to this field.

As a result, the target custom field in the project uses the replacement set of values.

18 August 2026
Archive a Version ValueTags