--- title: "Create issue" method: POST path: "/rest/api/2/issue" tags: ["Issues"] --- # Create issue `POST /rest/api/2/issue` Creates an issue or, where the option to create subtasks is enabled in Jira, a subtask. A transition may be applied, to move the issue or subtask to a workflow step other than the default start step, and issue properties set. The content of the issue or subtask is defined using `update` and `fields`. The fields that can be set in the issue or subtask are determined using the [ Get create issue metadata](#api-rest-api-2-issue-createmeta-get). These are the same fields that appear on the issue's create screen. Creating a subtask differs from creating an issue as follows: * `issueType` must be set to a subtask issue type (use [ Get create issue metadata](#api-rest-api-2-issue-createmeta-get) to find subtask issue types). * `parent` must contain the ID or key of the parent issue. **[Permissions](#permissions) required:** *Browse projects* and *Create issues* [project permissions](https://confluence.atlassian.com/x/yodKLg) for the project in which the issue or subtask is created. ## Query parameters - `updateHistory` boolean ## Request body - IssueUpdateDetails — Details of an issue update request. - `fields` object — List of issue screen fields to update, specifying the sub-field to update and its value for each field. This field provides a straightforward option when setting a sub-field. When multiple sub-fields or other operations are required, use `update`. Fields included in here cannot be included in `update`. - `historyMetadata` HistoryMetadata — Details of issue history metadata. - `activityDescription` string — The activity described in the history record. - `activityDescriptionKey` string — The key of the activity described in the history record. - `actor` HistoryMetadataParticipant — Details of user or system associated with a issue history metadata item. - `avatarUrl` string — The URL to an avatar for the user or system associated with a history record. - `displayName` string — The display name of the user or system associated with a history record. - `displayNameKey` string — The key of the display name of the user or system associated with a history record. - `id` string — The ID of the user or system associated with a history record. - `type` string — The type of the user or system associated with a history record. - `url` string — The URL of the user or system associated with a history record. - `cause` HistoryMetadataParticipant — Details of user or system associated with a issue history metadata item. - `avatarUrl` string — The URL to an avatar for the user or system associated with a history record. - `displayName` string — The display name of the user or system associated with a history record. - `displayNameKey` string — The key of the display name of the user or system associated with a history record. - `id` string — The ID of the user or system associated with a history record. - `type` string — The type of the user or system associated with a history record. - `url` string — The URL of the user or system associated with a history record. - `description` string — The description of the history record. - `descriptionKey` string — The description key of the history record. - `emailDescription` string — The description of the email address associated the history record. - `emailDescriptionKey` string — The description key of the email address associated the history record. - `extraData` object — Additional arbitrary information about the history record. - `generator` HistoryMetadataParticipant — Details of user or system associated with a issue history metadata item. - `avatarUrl` string — The URL to an avatar for the user or system associated with a history record. - `displayName` string — The display name of the user or system associated with a history record. - `displayNameKey` string — The key of the display name of the user or system associated with a history record. - `id` string — The ID of the user or system associated with a history record. - `type` string — The type of the user or system associated with a history record. - `url` string — The URL of the user or system associated with a history record. - `type` string — The type of the history record. - `properties` EntityProperty[] — Details of issue properties to be add or update. - `key` string — The key of the property. Required on create and update. - `value` unknown - `transition` IssueTransition — Details of an issue transition. - `expand` string — Expand options that include additional transition details in the response. - `fields` object — Details of the fields associated with the issue transition screen. Use this information to populate `fields` and `update` in a transition request. - `hasScreen` boolean — Whether there is a screen associated with the issue transition. - `id` string — The ID of the issue transition. Required when specifying a transition to undertake. - `isAvailable` boolean — Whether the transition is available to be performed. - `isConditional` boolean — Whether the issue has to meet criteria before the issue transition is applied. - `isGlobal` boolean — Whether the issue transition is global, that is, the transition is applied to issues regardless of their status. - `isInitial` boolean — Whether this is the initial issue transition for the workflow. - `looped` boolean - `name` string — The name of the issue transition. - `to` StatusDetails — A status. - `description` string — The description of the status. - `iconUrl` string — The URL of the icon used to represent the status. - `id` string — The ID of the status. - `name` string — The name of the status. - `scope` Scope — The projects the item is associated with. Indicated for items associated with [next-gen projects](https://confluence.atlassian.com/x/loMyO). - `project` ProjectDetails — Details about a project. - `avatarUrls` AvatarUrlsBean - `16x16` string, uri — The URL of the item's 16x16 pixel avatar. - `24x24` string, uri — The URL of the item's 24x24 pixel avatar. - `32x32` string, uri — The URL of the item's 32x32 pixel avatar. - `48x48` string, uri — The URL of the item's 48x48 pixel avatar. - `id` string — The ID of the project. - `key` string — The key of the project. - `name` string — The name of the project. - `projectCategory` UpdatedProjectCategory — A project category. - `description` string — The name of the project category. - `id` string — The ID of the project category. - `name` string — The description of the project category. - `self` string — The URL of the project category. - `projectTypeKey` 'software' | 'service_desk' | 'business' — The [project type](https://confluence.atlassian.com/x/GwiiLQ#Jiraapplicationsoverview-Productfeaturesandprojecttypes) of the project. - `self` string — The URL of the project details. - `simplified` boolean — Whether or not the project is simplified. - `type` 'PROJECT' | 'TEMPLATE' — The type of scope. - `self` string — The URL of the status. - `statusCategory` StatusCategory — A status category. - `colorName` string — The name of the color used to represent the status category. - `id` integer — The ID of the status category. - `key` string — The key of the status category. - `name` string — The name of the status category. - `self` string — The URL of the status category. - `update` object — A Map containing the field field name and a list of operations to perform on the issue screen field. Note that fields included in here cannot be included in `fields`. ## Response `201` Returned if the request is successful. - CreatedIssue — Details about a created issue or subtask. - `id` string — The ID of the created issue or subtask. - `key` string — The key of the created issue or subtask. - `self` string — The URL of the created issue or subtask. - `transition` NestedResponse - `errorCollection` ErrorCollection — Error messages from an operation. - `errorMessages` string[] — The list of error messages produced by this operation. For example, "input parameter 'key' must be provided" - `errors` object — The list of errors by parameter returned by the operation. For example,"projectKey": "Project keys must start with an uppercase letter, followed by one or more uppercase alphanumeric characters." - `status` integer - `status` integer - `warningCollection` WarningCollection - `warnings` string[] - `watchers` NestedResponse - `errorCollection` ErrorCollection — Error messages from an operation. - `errorMessages` string[] — The list of error messages produced by this operation. For example, "input parameter 'key' must be provided" - `errors` object — The list of errors by parameter returned by the operation. For example,"projectKey": "Project keys must start with an uppercase letter, followed by one or more uppercase alphanumeric characters." - `status` integer - `status` integer - `warningCollection` WarningCollection - `warnings` string[] ## Other responses - `400` — Returned if the request: * is missing required fields. * contains invalid field values. * contains fields that cannot be set for the issue type. * is by a user who does not have the necessary permission. * is to create a subtype in a project different that of the parent issue. * is for a subtask when the option to create subtasks is disabled. * is invalid for any other reason. - `401` — Returned if the authentication credentials are incorrect or missing. - `403` — Returned if the user does not have the necessary permission. - `422` — Returned if a configuration problem prevents the creation of the issue. --- [API](https://skmtc.net/atlassian/apis/the-jira-cloud-platform-rest-api.md) · [All operations](https://skmtc.net/atlassian/apis/the-jira-cloud-platform-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/atlassian/the-jira-cloud-platform-rest-api/versions/a26541c2f8bd/schema)