Create an Issue and Set Custom Fields
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.
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
-
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 aname
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
is0-0
. -
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.
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.
-
To create a new issue, assign it to a specific user, and set its "Priority" field to
Show-stopper
, send aPOST
request with the body that contains ID of the project, summary of the new issue, and a json object for thecustomFields
attribute that contains:The
name
,$type
, andvalue
of the Priority field.The
name
,$type
, andvalue
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" }