Create an Issue and Set Custom Fields

Last modified: 21 March 2025

Use Case

Use the REST API to create a new issue and set values for one or more custom fields.

Summary

To create an issue with a set value for a custom field, you need to preliminary obtain the following parameters:

  • The entity ID of the project, to which the new issue should belong.

  • name and $type of the custom field that you need to set.

  • name of the value that you set for the custom field.

tip

Read the Custom Fields in REST API page for more info about the custom fields in REST API.

Step-by-Step

The following procedure shows how to create a new issue and set values for a couple of issue fields. For the sample, we decided to set "Priority" and "Assignee" fields.

To create an issue and set a value for a custom field

  1. Get a list of available projects.

    curl -X GET \
'https://example.youtrack.cloud/api/admin/projects?fields=id,name,shortName' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer perm:amFuZS5kb2U=.UkVTVCBBUEk=.wcKuAok8cHmAtzjA6xlc4BrB4hleaX' \
-H 'Content-Type: application/json'

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

    [
    {
        "shortName": "GRP",
        "name": "GRA Project",
        "id": "0-7",
        "$type": "Project"
    },
    {
        "shortName": "RAP",
        "name": "Rest Api Project",
        "id": "0-2",
        "$type": "Project"
    },
    {
        "shortName": "RP",
        "name": "Rest Project",
        "id": "0-6",
        "$type": "Project"
    },
    {
        "shortName": "SP",
        "name": "Sample Project",
        "id": "0-0",
        "$type": "Project"
    },
    {
        "shortName": "SNBX",
        "name": "Sandbox",
        "id": "0-3",
        "$type": "Project"
    }
]

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

    Sample request with the filter by a project's name:

    curl -X GET \
'https://example.youtrack.cloud/api/admin/projects?fields=id,name,shortName&query=Sample+Project'
\
-H 'Accept: application/json' \
-H 'Authorization: Bearer perm:amFuZS5kb2U=.UkVTVCBBUEk=.wcKuAok8cHmAtzjA6xlc4BrB4hleaX' \
-H 'Content-Type: application/json'

    Sample request with the filter by a project's shortName:

    curl -X GET \
'https://example.youtrack.cloud/api/admin/projects?fields=id,name,shortName&query=sp'
\
-H 'Accept: application/json' \
-H 'Authorization: Bearer perm:amFuZS5kb2U=.UkVTVCBBUEk=.wcKuAok8cHmAtzjA6xlc4BrB4hleaX' \
-H 'Content-Type: application/json'

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

    [
    {
        "shortName": "SP",
        "name": "Sample Project",
        "id": "0-0",
        "$type": "Project"
    }
]

    In the response from the server, locate the id of the target project. In our sample, the required project id is 0-0.

  2. Obtain the name and $type of the custom field that you need to set. You can send a GET request to the /api/issues endpoint with query parameters:

    • fields parameter with a list of the issue attributes to return. For our case, we are particularly interested in custom fields. So, we can use the following string: 

      fields=project(name),idReadable,customFields(name,$type,value(name,login))

    • To narrow the results to issues in the target project, you can use the query parameter. For example, query=in:SP narrows the results for our particular target project.

    • Optionally, use the $top query parameter to get a limited number of issue.

    Here's the resulting request:

    curl -X GET \
  'https://example.youtrack.cloud/api/issues?fields=idReadable,id,project(id,name),summary,description,customFields(name,$type,value(name,login))&query=in:SP&$top=1' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \

    In response, server returned the following data:

    [
    {
        "idReadable": "SP-47",
        "project": {
            "name": "Sample Project",
            "id": "0-0",
            "$type": "Project"
        },
        "customFields": [
            {
                "value": {
                    "name": "Show-stopper",
                    "$type": "EnumBundleElement"
                },
                "name": "Priority",
                "$type": "SingleEnumIssueCustomField"
            },
            {
                "value": {
                    "name": "Task",
                    "$type": "EnumBundleElement"
                },
                "name": "Type",
                "$type": "SingleEnumIssueCustomField"
            },
            {
                "value": {
                    "name": "Open",
                    "$type": "StateBundleElement"
                },
                "name": "State",
                "$type": "StateIssueCustomField"
            },
            {
                "value": {
                    "login": "jane.doe",
                    "name": "Jane Doe",
                    "$type": "User"
                },
                "name": "Assignee",
                "$type": "SingleUserIssueCustomField"
            },
            {
                "value": null,
                "name": "Subsystem",
                "$type": "SingleOwnedIssueCustomField"
            },
            {
                "value": [],
                "name": "Fix versions",
                "$type": "MultiVersionIssueCustomField"
            },
            {
                "value": [],
                "name": "Affected versions",
                "$type": "MultiVersionIssueCustomField"
            },
            {
                "value": null,
                "name": "Fixed in build",
                "$type": "SingleBuildIssueCustomField"
            }
        ],
        "$type": "Issue"
    }
]

    From this response you can see the list of available fields and their types. You can also get the complete list of the available types for the issue custom fields on the page.

  3. Obtain the name of the value that you want to set for the target custom field. In general, it's enough to just know the name of the value - the way they are presented in the UI. For example, Show-stopper or Major for the Priority field, or In progress or Fixed for the State field. However, for some fields, like Fix version or Assignee, the list of available values might not be obvious. In this case, you need to get the set of values (bundle) that is used for this particular field in the target project.

  4. To create a new issue, assign it to a specific user, and set its "Priority" field to Show-stopper, send a POST request with the body that contains ID of the project, summary of the new issue, and a json object for the customFields attribute that contains:

    • The name, $type, and value of the Priority field.

    • The name, $type, and value of the Assignee field.

    Though the description attribute is not mandatory, we opted to specify it as well. Here's the resulting request:

    curl -X POST \
https://example.youtrack.cloud/api/issues \
-H 'Accept: application/json' \
-H 'Authorization: Bearer perm:amFuZS5kb2U=.UkVTVCBBUEk=.wcKuAok8cHmAtzjA6xlc4BrB4hleaX' \
-H 'Content-Type: application/json' \
-d '{
"project":{"id":"0-0"},
"summary":"REST API lets you create issues!",
"description":"Let'\''s create a new issue using YouTrack'\''s REST API.",
"customFields":[
{ "name":"Priority","$type":"SingleEnumIssueCustomField","value":{"name":"Show-stopper"}},
{ "name": "Assignee","$type": "SingleUserIssueCustomField","value": {"login":"jane.doe"}}
]
}'

    In the response, the server returns only the entity id of the created issue and its $type, because we did not specify any fields parameters in the request:

    {
    "id": "2-38",
    "$type": "Issue"
}

note

Please note that you cannot simultaneously create a new issue and add attachments to it. You can attach files only to an already existing issue.