---
schema: rendered-html/v1
title: "Create an Issue and Set Custom Fields | Developer Portal for YouTrack and Hub Documentation"
source_url: https://www.jetbrains.com/help/youtrack/devportal/api-howto-create-issue-with-fields.html
generated_at: 2026-06-11T14:59:49.470585+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](jetbrains__com__help__youtrack__devportal__api-getting-started.md)
- REST API Reference
- REST API Use Cases
- [Create an Issue](jetbrains__com__help__youtrack__devportal__api-howto-create-issue.md)
- [Create an Issue and Set Custom Fields](api-howto-create-issue-with-fields.html)
- [Get Issues List with All Values](jetbrains__com__help__youtrack__devportal__api-howto-get-issues-with-all-values.md)
- [Get Value for an Issue Custom Field](jetbrains__com__help__youtrack__devportal__api-howto-get-value-for-specific-cf.md)
- Add Value to a Set
- [Update Issue Custom Fields](jetbrains__com__help__youtrack__devportal__api-how-to-update-custom-fields-values.md)
- Update a Text Field Value
- [Clear Values of Custom Fields](jetbrains__com__help__youtrack__devportal__api-how-to-clear-custom-fields-values.md)
- Apply Commands to Issues
- Tag or Untag Issues
- Work with Issue Tags
- Attach Files to an Issue
- Delete an Issue Attachment
- Download an Issue Attachment
- [Link Issues](jetbrains__com__help__youtrack__devportal__api-howto-link-issues.md)
- Get Issue History
- Get a Database Backup
- Add User to Project Team
- REST API Troubleshooting
- Color Indices List
- Hub REST API

1. YouTrack REST API
2. REST API Use Cases
3. [Create an Issue and Set Custom Fields](#0)

# Create an Issue and Set Custom Fields﻿

Last modified: 07 May 2026

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

- [Create an Issue and Set Custom Fields](/help/youtrack/devportal/api-howto-create-issue-with-fields.html)
- [Use Case](/help/youtrack/devportal/api-howto-create-issue-with-fields.html#use-case)
- [Summary](/help/youtrack/devportal/api-howto-create-issue-with-fields.html#summary)
- [Step-by-Step](/help/youtrack/devportal/api-howto-create-issue-with-fields.html#step-by-step)

[Create an Issue](jetbrains__com__help__youtrack__devportal__api-howto-create-issue.md)[Get Issues List with All Values](jetbrains__com__help__youtrack__devportal__api-howto-get-issues-with-all-values.md)

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

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