--- title: "Edit issue" method: PUT path: "/rest/api/3/issue/{issueIdOrKey}" tags: ["Issues"] --- # Edit issue `PUT /rest/api/3/issue/{issueIdOrKey}` Edits an issue. Issue properties may be updated as part of the edit. Please note that issue transition is not supported and is ignored here. To transition an issue, please use [Transition issue](#api-rest-api-3-issue-issueIdOrKey-transitions-post). The edits to the issue's fields are defined using `update` and `fields`. The fields that can be edited are determined using [ Get edit issue metadata](#api-rest-api-3-issue-issueIdOrKey-editmeta-get). **Note:** This endpoint doesn't check screen configurations to determine if a field is editable. For more context, see the [Deprecation of override screen security](https://community.developer.atlassian.com/t/deprecation-of-override-screen-security/97153) announcement. The parent field may be set by key or ID. For standard issue types, the parent may be removed by setting `update.parent.set.none` to *true*. Note that the `description`, `environment`, and any `textarea` type custom fields (multi-line text fields) take Atlassian Document Format content. Single line custom fields (`textfield`) accept a string and don't handle Atlassian Document Format content. Connect apps having an app user with *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg), and Forge apps acting on behalf of users with *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg), can override the screen security configuration using `overrideScreenSecurity` and `overrideEditableFlag`. This operation can be accessed anonymously. **[Permissions](#permissions) required:** * *Browse projects* and *Edit issues* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in. * If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue. ## Path parameters - `issueIdOrKey` string, required ## Query parameters - `notifyUsers` boolean - `overrideScreenSecurity` boolean - `overrideEditableFlag` boolean - `returnIssue` boolean - `expand` string ## 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 `200` Returned if the request is successful and the `returnIssue` parameter is `true` - unknown ## Other responses - `204` — Returned if the request is successful. - `400` — Returned if: * the request body is missing. * the user does not have the necessary permission to edit one or more fields. * the request includes one or more fields that don't exist or aren't associated with the project and issue type. * the request includes an invalid transition. - `401` — Returned if the authentication credentials are incorrect or missing. - `403` — Returned if the user uses `overrideScreenSecurity` or `overrideEditableFlag` but doesn't have the necessary permission. - `404` — Returned if the issue is not found or the user does not have permission to view it. - `409` — Returned if the issue could not be updated due to a conflicting update. - `422` — Returned if a configuration problem prevents the issue being updated. --- [API](https://skmtc.net/atlassian/apis/the-jira-cloud-platform-rest-api-2.md) · [All operations](https://skmtc.net/atlassian/apis/the-jira-cloud-platform-rest-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/atlassian/the-jira-cloud-platform-rest-api-2/versions/5a51740d7ab3/schema)