A generated OIH connector for the The Jira Cloud platform REST API API (version 1001.0.0-SNAPSHOT).
Generated from: https://developer.atlassian.com/cloud/jira/platform/swagger-v3.v3.json
Generated at: 2021-10-15T09:05:27+02:00
Jira Cloud platform REST API documentation
Supported authorization schemes:
- Basic Authentication - You can access this resource via basic auth.
- OAuth2 - OAuth2 scopes for Jira
For OAuth 2.0 you need to specify OAuth Client credentials as environment variables in the connector repository:
OAUTH_CLIENT_ID- your OAuth client idOAUTH_CLIENT_SECRET- your OAuth client secret
Update the configuration for contexts of a custom field created by a Forge app.
Permissions required: Administer Jira global permission. Jira permissions are not required for the Forge app that created the custom field.
Tags: Issue custom field configuration (apps)
fieldIdOrKey- required - The ID or key of the custom field, for examplecustomfield_10000.
Updates the value of a custom field on one or more issues. Custom fields can only be updated by the Forge app that created them.
Permissions required: Only the app that created the custom field can update its values with this operation.
Tags: Issue custom field values (apps)
fieldIdOrKey- required - The ID or key of the custom field. For example,customfield_10010.generateChangelog- optional - Whether to generate a changelog for this update. Default: true.
Changes the value of an application property. For example, you can change the value of the
jira.clone.prefixfrom its default value of CLONE - to Clone - if you prefer sentence case capitalization. Editable properties are described below along with their default values.
The advanced settings below are also accessible in [Jira](https://confluence.atlassian.com/x/vYXKM).
| Key | Description | Default value |
| -- | -- | -- |
| `jira.clone.prefix` | The string of text prefixed to the title of a cloned issue. | `CLONE -` |
| `jira.date.picker.java.format` | The date format for the Java (server-side) generated dates. This must be the same as the `jira.date.picker.javascript.format` format setting. | `d/MMM/yy` |
| `jira.date.picker.javascript.format` | The date format for the JavaScript (client-side) generated dates. This must be the same as the `jira.date.picker.java.format` format setting. | `%e/%b/%y` |
| `jira.date.time.picker.java.format` | The date format for the Java (server-side) generated date times. This must be the same as the `jira.date.time.picker.javascript.format` format setting. | `dd/MMM/yy h:mm a` |
| `jira.date.time.picker.javascript.format` | The date format for the JavaScript (client-side) generated date times. This must be the same as the `jira.date.time.picker.java.format` format setting. | `%e/%b/%y %I:%M %p` |
| `jira.issue.actions.order` | The default order of actions (such as *Comments* or *Change history*) displayed on the issue view. | `asc` |
| `jira.table.cols.subtasks` | The columns to show while viewing subtask issues in a table. For example, a list of subtasks on an issue. | `issuetype, status, assignee, progress` |
| `jira.view.issue.links.sort.order` | The sort order of the list of issue links on the issue view. | `type, status, priority` |
| `jira.comment.collapsing.minimum.hidden` | The minimum number of comments required for comment collapsing to occur. A value of `0` disables comment collapsing. | `4` |
| `jira.newsletter.tip.delay.days` | The number of days before a prompt to sign up to the Jira Insiders newsletter is shown. A value of `-1` disables this feature. | `7` |
#### Look and feel ####
The settings listed below adjust the [look and feel](https://confluence.atlassian.com/x/VwCLLg).
| Key | Description | Default value |
| -- | -- | -- |
| `jira.lf.date.time` | The [ time format](https://docs.oracle.com/javase/6/docs/api/index.html?java/text/SimpleDateFormat.html). | `h:mm a` |
| `jira.lf.date.day` | The [ day format](https://docs.oracle.com/javase/6/docs/api/index.html?java/text/SimpleDateFormat.html). | `EEEE h:mm a` |
| `jira.lf.date.complete` | The [ date and time format](https://docs.oracle.com/javase/6/docs/api/index.html?java/text/SimpleDateFormat.html). | `dd/MMM/yy h:mm a` |
| `jira.lf.date.dmy` | The [ date format](https://docs.oracle.com/javase/6/docs/api/index.html?java/text/SimpleDateFormat.html). | `dd/MMM/yy` |
| `jira.date.time.picker.use.iso8061` | When enabled, sets Monday as the first day of the week in the date picker, as specified by the ISO8601 standard. | `false` |
| `jira.lf.logo.url` | The URL of the logo image file. | `/images/icon-jira-logo.png` |
| `jira.lf.logo.show.application.title` | Controls the visibility of the application title on the sidebar. | `false` |
| `jira.lf.favicon.url` | The URL of the favicon. | `/favicon.ico` |
| `jira.lf.favicon.hires.url` | The URL of the high-resolution favicon. | `/images/64jira.png` |
| `jira.lf.navigation.bgcolour` | The background color of the sidebar. | `#0747A6` |
| `jira.lf.navigation.highlightcolour` | The color of the text and logo of the sidebar. | `#DEEBFF` |
| `jira.lf.hero.button.base.bg.colour` | The background color of the hero button. | `#3b7fc4` |
| `jira.title` | The text for the application title. The application title can also be set in *General settings*. | `Jira` |
| `jira.option.globalsharing` | Whether filters and dashboards can be shared with anyone signed into Jira. | `true` |
| `xflow.product.suggestions.enabled` | Whether to expose product suggestions for other Atlassian products within Jira. | `true` |
#### Other settings ####
| Key | Description | Default value |
| -- | -- | -- |
| `jira.issuenav.criteria.autoupdate` | Whether instant updates to search criteria is active. | `true` |
*Note: Be careful when changing [application properties and advanced settings](https://confluence.atlassian.com/x/vYXKM).*
**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
Tags: Jira settings
id- required - The key of the application property to update.
Returns an application role.
Permissions required: Administer Jira global permission.
Tags: Application roles
key- required - The key of the application role. Use the Get all application roles operation to get the key for each application role.
Returns the metadata for an attachment. Note that the attachment itself is not returned.
This operation can be accessed anonymously.
Permissions required:
- Browse projects project permission for the project that the issue is in.
- If issue-level security is configured, issue-level security permission to view the issue.
Tags: Issue attachments
id- required - The ID of the attachment.
Deletes an attachment from an issue.
This operation can be accessed anonymously.
Permissions required: For the project holding the issue containing the attachment:
- Delete own attachments project permission to delete an attachment created by the calling user.
- Delete all attachments project permission to delete an attachment created by any user.
Tags: Issue attachments
id- required - The ID of the attachment.
Returns a paginated list of comments specified by a list of comment IDs.
This operation can be accessed anonymously.
Permissions required: Comments are returned where the user:
- has Browse projects project permission for the project containing the comment.
- If issue-level security is configured, issue-level security permission to view the issue.
- If the comment has visibility restrictions, belongs to the group or has the role visibility is restricted to.
Tags: Issue comments
expand- optional - Use expand to include additional information about comments in the response. This parameter accepts a comma-separated list. Expand options include:
* `renderedBody` Returns the comment body rendered in HTML.
* `properties` Returns the comment's properties.
Returns the value of a comment property.
This operation can be accessed anonymously.
Permissions required:
- Browse projects project permission for the project.
- If issue-level security is configured, issue-level security permission to view the issue.
- If the comment has visibility restrictions, belongs to the group or has the role visibility is restricted to.
Tags: Issue comment properties
commentId- required - The ID of the comment.propertyKey- required - The key of the property.
Creates or updates the value of a property for a comment. Use this resource to store custom data against a comment.
The value of the request body must be a valid, non-empty JSON blob. The maximum length is 32768 characters.
Permissions required: either of:
- Edit All Comments project permission to create or update the value of a property on any comment.
- Edit Own Comments project permission to create or update the value of a property on a comment created by the user.
Also, when the visibility of a comment is restricted to a role or group the user must be a member of that role or group.
Tags: Issue comment properties
commentId- required - The ID of the comment.propertyKey- required - The key of the property. The maximum length is 255 characters.
Deletes a comment property.
Permissions required: either of:
- Edit All Comments project permission to delete a property from any comment.
- Edit Own Comments project permission to delete a property from a comment created by the user.
Also, when the visibility of a comment is restricted to a role or group the user must be a member of that role or group.
Tags: Issue comment properties
commentId- required - The ID of the comment.propertyKey- required - The key of the property.
Creates a component. Use components to provide containers for issues within a project.
This operation can be accessed anonymously.
Permissions required: Administer projects project permission for the project in which the component is created or Administer Jira global permission.
Tags: Project components
Returns a component.
This operation can be accessed anonymously.
Permissions required: Browse projects project permission for project containing the component.
Tags: Project components
id- required - The ID of the component.
Updates a component. Any fields included in the request are overwritten. If
leadAccountIdis an empty string ("") the component lead is removed.
This operation can be accessed anonymously.
Permissions required: Administer projects project permission for the project containing the component or Administer Jira global permission.
Tags: Project components
id- required - The ID of the component.
Deletes a component.
This operation can be accessed anonymously.
Permissions required: Administer projects project permission for the project containing the component or Administer Jira global permission.
Tags: Project components
id- required - The ID of the component.moveIssuesTo- optional - The ID of the component to replace the deleted component. If this value is null no replacement is made.
Selects a time tracking provider.
Permissions required: Administer Jira global permission.
Tags: Time tracking
Sets the time tracking settings.
Permissions required: Administer Jira global permission.
Tags: Time tracking
Returns a custom field option. For example, an option in a select list.
Note that this operation only works for issue field select list options created in Jira or using operations from the Issue custom field options resource, it cannot be used with issue field select list options created by Connect apps.
This operation can be accessed anonymously.
Permissions required: The custom field option is returned as follows:
- if the user has the Administer Jira global permission.
- if the user has the Browse projects project permission for at least one project the custom field is used in, and the field is visible in at least one layout the user has permission to view.
Tags: Issue custom field options
id- required - The ID of the custom field option.
Creates a dashboard.
Permissions required: None.
Tags: Dashboards
Returns the key and value of a dashboard item property.
A dashboard item enables an app to add user-specific information to a user dashboard. Dashboard items are exposed to users as gadgets that users can add to their dashboards. For more information on how users do this, see Adding and customizing gadgets.
When an app creates a dashboard item it registers a callback to receive the dashboard item ID. The callback fires whenever the item is rendered or, where the item is configurable, the user edits the item. The app then uses this resource to store the item's content or configuration details. For more information on working with dashboard items, see Building a dashboard item for a JIRA Connect add-on and the Dashboard Item documentation.
There is no resource to set or get dashboard items.
This operation can be accessed anonymously.
Permissions required: The user must be the owner of the dashboard or have the dashboard shared with them. Note, users with the Administer Jira global permission are considered owners of the System dashboard. The System dashboard is considered to be shared with all other users, and is accessible to anonymous users when Jira's anonymous access is permitted.
Tags: Dashboards
dashboardId- required - The ID of the dashboard.itemId- required - The ID of the dashboard item.propertyKey- required - The key of the dashboard item property.
Sets the value of a dashboard item property. Use this resource in apps to store custom data against a dashboard item.
A dashboard item enables an app to add user-specific information to a user dashboard. Dashboard items are exposed to users as gadgets that users can add to their dashboards. For more information on how users do this, see Adding and customizing gadgets.
When an app creates a dashboard item it registers a callback to receive the dashboard item ID. The callback fires whenever the item is rendered or, where the item is configurable, the user edits the item. The app then uses this resource to store the item's content or configuration details. For more information on working with dashboard items, see Building a dashboard item for a JIRA Connect add-on and the Dashboard Item documentation.
There is no resource to set or get dashboard items.
The value of the request body must be a valid, non-empty JSON blob. The maximum length is 32768 characters.
This operation can be accessed anonymously.
Permissions required: The user must be the owner of the dashboard. Note, users with the Administer Jira global permission are considered owners of the System dashboard.
Tags: Dashboards
dashboardId- required - The ID of the dashboard.itemId- required - The ID of the dashboard item.propertyKey- required - The key of the dashboard item property. The maximum length is 255 characters.
Deletes a dashboard item property.
This operation can be accessed anonymously.
Permissions required: The user must be the owner of the dashboard. Note, users with the Administer Jira global permission are considered owners of the System dashboard.
Tags: Dashboards
dashboardId- required - The ID of the dashboard.itemId- required - The ID of the dashboard item.propertyKey- required - The key of the dashboard item property.
Returns a dashboard.
This operation can be accessed anonymously.
Permissions required: None.
However, to get a dashboard, the dashboard must be shared with the user or the user must own it. Note, users with the Administer Jira global permission are considered owners of the System dashboard. The System dashboard is considered to be shared with all other users.
Tags: Dashboards
id- required - The ID of the dashboard.
Updates a dashboard, replacing all the dashboard details with those provided.
Permissions required: None
The dashboard to be updated must be owned by the user.
Tags: Dashboards
id- required - The ID of the dashboard to update.
Deletes a dashboard.
Permissions required: None
The dashboard to be deleted must be owned by the user.
Tags: Dashboards
id- required - The ID of the dashboard.
Copies a dashboard. Any values provided in the
dashboardparameter replace those in the copied dashboard.
Permissions required: None
The dashboard to be copied must be owned by or shared with the user.
Tags: Dashboards
id- required
Analyses and validates Jira expressions.
As an experimental feature, this operation can also attempt to type-check the expressions.
Learn more about Jira expressions in the documentation.
Permissions required: None.
Tags: Jira expressions
check- optional - The check to perform:
* `syntax` Each expression's syntax is checked to ensure the expression can be parsed. Also, syntactic limits are validated. For example, the expression's length.
* `type` EXPERIMENTAL. Each expression is type checked and the final type of the expression inferred. Any type errors that would result in the expression failure at runtime are reported. For example, accessing properties that don't exist or passing the wrong number of arguments to functions. Also performs the syntax check.
* `complexity` EXPERIMENTAL. Determines the formulae for how many [expensive operations](https://developer.atlassian.com/cloud/jira/platform/jira-expressions/#expensive-operations) each expression may execute.
Possible values: syntax, type, complexity.
Evaluates a Jira expression and returns its value.
This resource can be used to test Jira expressions that you plan to use elsewhere, or to fetch data in a flexible way. Consult the Jira expressions documentation for more details.
The following context variables are available to Jira expressions evaluated by this resource. Their presence depends on various factors; usually you need to manually request them in the context object sent in the payload, but some of them are added automatically under certain conditions.
* `user` ([User](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#user)): The current user. Always available and equal to `null` if the request is anonymous.
* `app` ([App](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#app)): The [Connect app](https://developer.atlassian.com/cloud/jira/platform/index/#connect-apps) that made the request. Available only for authenticated requests made by Connect Apps (read more here: [Authentication for Connect apps](https://developer.atlassian.com/cloud/jira/platform/security-for-connect-apps/)).
* `issue` ([Issue](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#issue)): The current issue. Available only when the issue is provided in the request context object.
* `issues` ([List](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#list) of [Issues](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#issue)): A collection of issues matching a JQL query. Available only when JQL is provided in the request context object.
* `project` ([Project](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#project)): The current project. Available only when the project is provided in the request context object.
* `sprint` ([Sprint](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#sprint)): The current sprint. Available only when the sprint is provided in the request context object.
* `board` ([Board](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#board)): The current board. Available only when the board is provided in the request context object.
* `serviceDesk` ([ServiceDesk](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#servicedesk)): The current service desk. Available only when the service desk is provided in the request context object.
* `customerRequest` ([CustomerRequest](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#customerrequest)): The current customer request. Available only when the customer request is provided in the request context object.
This operation can be accessed anonymously.
**[Permissions](#permissions) required**: None. However, an expression may return different results for different users depending on their permissions. For example, different users may see different comments on the same issue.
Permission to access Jira Software is required to access Jira Software context variables (`board` and `sprint`) or fields (for example, `issue.sprint`).
Tags: Jira expressions
expand- optional - Use expand to include additional information in the response. This parameter acceptsmeta.complexitythat returns information about the expression complexity. For example, the number of expensive operations used by the expression and how close the expression is to reaching the complexity limit. Useful when designing and debugging your expressions.
Creates a custom field.
Permissions required: Administer Jira global permission.
Tags: Issue fields
Updates a custom field.
Permissions required: Administer Jira global permission.
Tags: Issue fields
fieldId- required - The ID of the custom field.
Creates a custom field context.
IfprojectIdsis empty, a global context is created. A global context is one that applies to all project. IfissueTypeIdsis empty, the context applies to all issue types.
Permissions required: Administer Jira global permission.
Tags: Issue custom field contexts
fieldId- required - The ID of the custom field.
Sets default for contexts of a custom field. Default are defined using these objects:
CustomFieldContextDefaultValueDate(typedatepicker) for date fields.CustomFieldContextDefaultValueDateTime(typedatetimepicker) for date-time fields.CustomFieldContextDefaultValueSingleOption(typeoption.single) for single choice select lists and radio buttons.CustomFieldContextDefaultValueMultipleOption(typeoption.multiple) for multiple choice select lists and checkboxes.CustomFieldContextDefaultValueCascadingOption(typeoption.cascading) for cascading select lists.CustomFieldContextSingleUserPickerDefaults(typesingle.user.select) for single users.CustomFieldContextDefaultValueMultiUserPicker(typemulti.user.select) for user lists.CustomFieldContextDefaultValueSingleGroupPicker(typegrouppicker.single) for single choice group picker.CustomFieldContextDefaultValueMultipleGroupPicker(typegrouppicker.multiple) for multiple choice group picker.
Only one type of default object can be included in a request. To remove a default for a context, set the default parameter to `null`.
**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
Tags: Issue custom field contexts
fieldId- required - The ID of the custom field.
Returns a paginated list of project and issue type mappings and, for each mapping, the ID of a custom field context that applies to the project and issue type.
If there is no custom field context assigned to the project then, if present, the custom field context that applies to all projects is returned if it also applies to the issue type or all issue types. If a custom field context is not found, the returned custom field context ID isnull.
Duplicate project and issue type mappings cannot be provided in the request.
The order of the returned values is the same as provided in the request.
Permissions required: Administer Jira global permission.
Tags: Issue custom field contexts
fieldId- required - The ID of the custom field.startAt- optional - The index of the first item to return in a page of results (page offset).maxResults- optional - The maximum number of items to return per page.
Updates a custom field context.
Permissions required: Administer Jira global permission.
Tags: Issue custom field contexts
fieldId- required - The ID of the custom field.contextId- required - The ID of the context.
Deletes a custom field context.
Permissions required: Administer Jira global permission.
Tags: Issue custom field contexts
fieldId- required - The ID of the custom field.contextId- required - The ID of the context.
Adds issue types to a custom field context, appending the issue types to the issue types list.
A custom field context without any issue types applies to all issue types. Adding issue types to such a custom field context would result in it applying to only the listed issue types.
If any of the issue types exists in the custom field context, the operation fails and no issue types are added.
Permissions required: Administer Jira global permission.
Tags: Issue custom field contexts
fieldId- required - The ID of the custom field.contextId- required - The ID of the context.
Removes issue types from a custom field context.
A custom field context without any issue types applies to all issue types.
Permissions required: Administer Jira global permission.
Tags: Issue custom field contexts
fieldId- required - The ID of the custom field.contextId- required - The ID of the context.
Updates the options of a custom field.
If any of the options are not found, no options are updated. Options where the values in the request match the current values aren't updated and aren't reported in the response.
Note that this operation only works for issue field select list options created in Jira or using operations from the Issue custom field options resource, it cannot be used with issue field select list options created by Connect apps.
Permissions required: Administer Jira global permission.
Tags: Issue custom field options
fieldId- required - The ID of the custom field.contextId- required - The ID of the context.
Creates options and, where the custom select field is of the type Select List (cascading), cascading options for a custom select field. The options are added to a context of the field.
The maximum number of options that can be created per request is 1000 and each field can have a maximum of 10000 options.
This operation works for custom field options created in Jira or the operations from this resource. To work with issue field select list options created for Connect apps use the Issue custom field options (apps) operations.
Permissions required: Administer Jira global permission.
Tags: Issue custom field options
fieldId- required - The ID of the custom field.contextId- required - The ID of the context.
Changes the order of custom field options or cascading options in a context.
This operation works for custom field options created in Jira or the operations from this resource. To work with issue field select list options created for Connect apps use the Issue custom field options (apps) operations.
Permissions required: Administer Jira global permission.
Tags: Issue custom field options
fieldId- required - The ID of the custom field.contextId- required - The ID of the context.
Deletes a custom field option.
Options with cascading options cannot be deleted without deleting the cascading options first.
This operation works for custom field options created in Jira or the operations from this resource. To work with issue field select list options created for Connect apps use the Issue custom field options (apps) operations.
Permissions required: Administer Jira global permission.
Tags: Issue custom field options
fieldId- required - The ID of the custom field.contextId- required - The ID of the context from which an option should be deleted.optionId- required - The ID of the option to delete.
Assigns a custom field context to projects.
If any project in the request is assigned to any context of the custom field, the operation fails.
Permissions required: Administer Jira global permission.
Tags: Issue custom field contexts
fieldId- required - The ID of the custom field.contextId- required - The ID of the context.
Removes a custom field context from projects.
A custom field context without any projects applies to all projects. Removing all projects from a custom field context would result in it applying to all projects.
If any project in the request is not assigned to the context, or the operation would result in two global contexts for the field, the operation fails.
Permissions required: Administer Jira global permission.
Tags: Issue custom field contexts
fieldId- required - The ID of the custom field.contextId- required - The ID of the context.
Creates an option for a select list issue field.
Note that this operation only works for issue field select list options added by Connect apps, it cannot be used with issue field select list options created in Jira or using operations from the Issue custom field options resource.
Permissions required: Administer Jira global permission. Jira permissions are not required for the app providing the field.
Tags: Issue custom field options (apps)
-
fieldKey- required - The field key is specified in the following format:$(app-key)__$ (field-key). For example, example-add-on__example-issue-field. To determine thefieldKeyvalue, do one of the following:
* open the app's plugin descriptor, then **app-key** is the key at the top and **field-key** is the key in the `jiraIssueFields` module. **app-key** can also be found in the app listing in the Atlassian Universal Plugin Manager.
* run [Get fields](#api-rest-api-3-field-get) and in the field details the value is returned in `key`. For example, `"key": "teams-add-on__team-issue-field"`
Returns an option from a select list issue field.
Note that this operation only works for issue field select list options added by Connect apps, it cannot be used with issue field select list options created in Jira or using operations from the Issue custom field options resource.
Permissions required: Administer Jira global permission. Jira permissions are not required for the app providing the field.
Tags: Issue custom field options (apps)
-
fieldKey- required - The field key is specified in the following format:$(app-key)__$ (field-key). For example, example-add-on__example-issue-field. To determine thefieldKeyvalue, do one of the following:
* open the app's plugin descriptor, then **app-key** is the key at the top and **field-key** is the key in the `jiraIssueFields` module. **app-key** can also be found in the app listing in the Atlassian Universal Plugin Manager.
* run [Get fields](#api-rest-api-3-field-get) and in the field details the value is returned in `key`. For example, `"key": "teams-add-on__team-issue-field"`
* `optionId` - _required_ - The ID of the option to be returned.
Updates or creates an option for a select list issue field. This operation requires that the option ID is provided when creating an option, therefore, the option ID needs to be specified as a path and body parameter. The option ID provided in the path and body must be identical.
Note that this operation only works for issue field select list options added by Connect apps, it cannot be used with issue field select list options created in Jira or using operations from the Issue custom field options resource.
Permissions required: Administer Jira global permission. Jira permissions are not required for the app providing the field.
Tags: Issue custom field options (apps)
-
fieldKey- required - The field key is specified in the following format:$(app-key)__$ (field-key). For example, example-add-on__example-issue-field. To determine thefieldKeyvalue, do one of the following:
* open the app's plugin descriptor, then **app-key** is the key at the top and **field-key** is the key in the `jiraIssueFields` module. **app-key** can also be found in the app listing in the Atlassian Universal Plugin Manager.
* run [Get fields](#api-rest-api-3-field-get) and in the field details the value is returned in `key`. For example, `"key": "teams-add-on__team-issue-field"`
* `optionId` - _required_ - The ID of the option to be updated.
Deletes an option from a select list issue field.
Note that this operation only works for issue field select list options added by Connect apps, it cannot be used with issue field select list options created in Jira or using operations from the Issue custom field options resource.
Permissions required: Administer Jira global permission. Jira permissions are not required for the app providing the field.
Tags: Issue custom field options (apps)
-
fieldKey- required - The field key is specified in the following format:$(app-key)__$ (field-key). For example, example-add-on__example-issue-field. To determine thefieldKeyvalue, do one of the following:
* open the app's plugin descriptor, then **app-key** is the key at the top and **field-key** is the key in the `jiraIssueFields` module. **app-key** can also be found in the app listing in the Atlassian Universal Plugin Manager.
* run [Get fields](#api-rest-api-3-field-get) and in the field details the value is returned in `key`. For example, `"key": "teams-add-on__team-issue-field"`
* `optionId` - _required_ - The ID of the option to be deleted.
Deselects an issue-field select-list option from all issues where it is selected. A different option can be selected to replace the deselected option. The update can also be limited to a smaller set of issues by using a JQL query.
Connect app users with admin permissions (from user permissions and app scopes) and Forge app users with themanage:jira-configurationscope can override the screen security configuration usingoverrideScreenSecurityandoverrideEditableFlag.
This is an asynchronous operation. The response object contains a link to the long-running task.
Note that this operation only works for issue field select list options added by Connect apps, it cannot be used with issue field select list options created in Jira or using operations from the Issue custom field options resource.
Permissions required: Administer Jira global permission. Jira permissions are not required for the app providing the field.
Tags: Issue custom field options (apps)
-
replaceWith- optional - The ID of the option that will replace the currently selected option.
-
jql- optional - A JQL query that specifies the issues to be updated. For example, project=10000.
-
overrideScreenSecurity- optional - Whether screen security is overridden to enable hidden fields to be edited. Available to Connect app users with admin permission and Forge app users with themanage:jira-configurationscope.
-
overrideEditableFlag- optional - Whether screen security is overridden to enable uneditable fields to be edited. Available to Connect app users with admin permission and Forge app users with themanage:jira-configurationscope.
-
fieldKey- required - The field key is specified in the following format:$(app-key)__$ (field-key). For example, example-add-on__example-issue-field. To determine thefieldKeyvalue, do one of the following:
* open the app's plugin descriptor, then **app-key** is the key at the top and **field-key** is the key in the `jiraIssueFields` module. **app-key** can also be found in the app listing in the Atlassian Universal Plugin Manager.
* run [Get fields](#api-rest-api-3-field-get) and in the field details the value is returned in `key`. For example, `"key": "teams-add-on__team-issue-field"`
* `optionId` - _required_ - The ID of the option to be deselected.
Deletes a custom field. The custom field is deleted whether it is in the trash or not. See Edit or delete a custom field for more information on trashing and deleting custom fields.
This operation is asynchronous. Follow thelocationlink in the response to determine the status of the task and use Get task to obtain subsequent updates.
Permissions required: Administer Jira global permission.
Tags: Issue fields
id- required - The ID of a custom field.
Restores a custom field from trash. See Edit or delete a custom field for more information on trashing and deleting custom fields.
Permissions required: Administer Jira global permission.
Tags: Issue fields
id- required - The ID of a custom field.
Moves a custom field to trash. See Edit or delete a custom field for more information on trashing and deleting custom fields.
Permissions required: Administer Jira global permission.
Tags: Issue fields
id- required - The ID of a custom field.
Creates a field configuration. The field configuration is created with the same field properties as the default configuration, with all the fields being optional.
This operation can only to create configurations for use in classic projects.
Permissions required: Administer Jira global permission.
Tags: Issue field configurations
Assigns a field configuration scheme to a project. If the field configuration scheme ID is
null, the operation assigns the default field configuration scheme.
Field configuration schemes can only be assigned to classic projects.
Permissions required: Administer Jira global permission.
Tags: Issue field configurations
Creates a filter. The filter is shared according to the default share scope. The filter is not selected as a favorite.
Permissions required: Permission to access Jira.
Tags: Filters
expand- optional - Use expand to include additional information about filter in the response. This parameter accepts a comma-separated list. Expand options include:
* `sharedUsers` Returns the users that the filter is shared with. This includes users that can browse projects that the filter is shared with. If you don't specify `sharedUsers`, then the `sharedUsers` object is returned but it doesn't list any users. The list of users returned is limited to 1000, to access additional users append `[start-index:end-index]` to the expand request. For example, to access the next 1000 users, use `?expand=sharedUsers[1001:2000]`.
* `subscriptions` Returns the users that are subscribed to the filter. If you don't specify `subscriptions`, the `subscriptions` object is returned but it doesn't list any subscriptions. The list of subscriptions returned is limited to 1000, to access additional subscriptions append `[start-index:end-index]` to the expand request. For example, to access the next 1000 subscriptions, use `?expand=subscriptions[1001:2000]`.
Sets the default sharing for new filters and dashboards for a user.
Permissions required: Permission to access Jira.
Tags: Filter sharing
Returns a filter.
This operation can be accessed anonymously.
Permissions required: None, however, the filter is only returned where it is:
- owned by the user.
- shared with a group that the user is a member of.
- shared with a private project that the user has Browse projects project permission for.
- shared with a public project.
- shared with the public.
Tags: Filters
id- required - The ID of the filter to return.expand- optional - Use expand to include additional information about filter in the response. This parameter accepts a comma-separated list. Expand options include:
* `sharedUsers` Returns the users that the filter is shared with. This includes users that can browse projects that the filter is shared with. If you don't specify `sharedUsers`, then the `sharedUsers` object is returned but it doesn't list any users. The list of users returned is limited to 1000, to access additional users append `[start-index:end-index]` to the expand request. For example, to access the next 1000 users, use `?expand=sharedUsers[1001:2000]`.
* `subscriptions` Returns the users that are subscribed to the filter. If you don't specify `subscriptions`, the `subscriptions` object is returned but it doesn't list any subscriptions. The list of subscriptions returned is limited to 1000, to access additional subscriptions append `[start-index:end-index]` to the expand request. For example, to access the next 1000 subscriptions, use `?expand=subscriptions[1001:2000]`.
Updates a filter. Use this operation to update a filter's name, description, JQL, or sharing.
Permissions required: Permission to access Jira, however the user must own the filter.
Tags: Filters
id- required - The ID of the filter to update.expand- optional - Use expand to include additional information about filter in the response. This parameter accepts a comma-separated list. Expand options include:
* `sharedUsers` Returns the users that the filter is shared with. This includes users that can browse projects that the filter is shared with. If you don't specify `sharedUsers`, then the `sharedUsers` object is returned but it doesn't list any users. The list of users returned is limited to 1000, to access additional users append `[start-index:end-index]` to the expand request. For example, to access the next 1000 users, use `?expand=sharedUsers[1001:2000]`.
* `subscriptions` Returns the users that are subscribed to the filter. If you don't specify `subscriptions`, the `subscriptions` object is returned but it doesn't list any subscriptions. The list of subscriptions returned is limited to 1000, to access additional subscriptions append `[start-index:end-index]` to the expand request. For example, to access the next 1000 subscriptions, use `?expand=subscriptions[1001:2000]`.
Delete a filter.
Permissions required: Permission to access Jira, however filters can only be deleted by the creator of the filter or a user with Administer Jira global permission.
Tags: Filters
id- required - The ID of the filter to delete.
Sets the columns for a filter. Only navigable fields can be set as columns. Use Get fields to get the list fields in Jira. A navigable field has
navigableset totrue.
The parameters for this resource are expressed as HTML form data. For example, in curl:
curl -X PUT -d columns=summary -d columns=description https://your-domain.atlassian.net/rest/api/3/filter/10000/columns
Permissions required: Permission to access Jira, however, columns are only set for:
- filters owned by the user.
- filters shared with a group that the user is a member of.
- filters shared with a private project that the user has Browse projects project permission for.
- filters shared with a public project.
- filters shared with the public.
Tags: Filters
id- required - The ID of the filter.
Reset the user's column configuration for the filter to the default.
Permissions required: Permission to access Jira, however, columns are only reset for:
- filters owned by the user.
- filters shared with a group that the user is a member of.
- filters shared with a private project that the user has Browse projects project permission for.
- filters shared with a public project.
- filters shared with the public.
Tags: Filters
id- required - The ID of the filter.
Add a filter as a favorite for the user.
Permissions required: Permission to access Jira, however, the user can only favorite:
- filters owned by the user.
- filters shared with a group that the user is a member of.
- filters shared with a private project that the user has Browse projects project permission for.
- filters shared with a public project.
- filters shared with the public.
Tags: Filters
id- required - The ID of the filter.expand- optional - Use expand to include additional information about filter in the response. This parameter accepts a comma-separated list. Expand options include:
* `sharedUsers` Returns the users that the filter is shared with. This includes users that can browse projects that the filter is shared with. If you don't specify `sharedUsers`, then the `sharedUsers` object is returned but it doesn't list any users. The list of users returned is limited to 1000, to access additional users append `[start-index:end-index]` to the expand request. For example, to access the next 1000 users, use `?expand=sharedUsers[1001:2000]`.
* `subscriptions` Returns the users that are subscribed to the filter. If you don't specify `subscriptions`, the `subscriptions` object is returned but it doesn't list any subscriptions. The list of subscriptions returned is limited to 1000, to access additional subscriptions append `[start-index:end-index]` to the expand request. For example, to access the next 1000 subscriptions, use `?expand=subscriptions[1001:2000]`.
Removes a filter as a favorite for the user. Note that this operation only removes filters visible to the user from the user's favorites list. For example, if the user favorites a public filter that is subsequently made private (and is therefore no longer visible on their favorites list) they cannot remove it from their favorites list.
Permissions required: Permission to access Jira.
Tags: Filters
id- required - The ID of the filter.expand- optional - Use expand to include additional information about filter in the response. This parameter accepts a comma-separated list. Expand options include:
* `sharedUsers` Returns the users that the filter is shared with. This includes users that can browse projects that the filter is shared with. If you don't specify `sharedUsers`, then the `sharedUsers` object is returned but it doesn't list any users. The list of users returned is limited to 1000, to access additional users append `[start-index:end-index]` to the expand request. For example, to access the next 1000 users, use `?expand=sharedUsers[1001:2000]`.
* `subscriptions` Returns the users that are subscribed to the filter. If you don't specify `subscriptions`, the `subscriptions` object is returned but it doesn't list any subscriptions. The list of subscriptions returned is limited to 1000, to access additional subscriptions append `[start-index:end-index]` to the expand request. For example, to access the next 1000 subscriptions, use `?expand=subscriptions[1001:2000]`.
Add a share permissions to a filter. If you add a global share permission (one for all logged-in users or the public) it will overwrite all share permissions for the filter.
Be aware that this operation uses different objects for updating share permissions compared to Update filter.
Permissions required: Share dashboards and filters global permission and the user must own the filter.
Tags: Filter sharing
id- required - The ID of the filter.
Returns a share permission for a filter. A filter can be shared with groups, projects, all logged-in users, or the public. Sharing with all logged-in users or the public is known as a global share permission.
This operation can be accessed anonymously.
Permissions required: None, however, a share permission is only returned for:
- filters owned by the user.
- filters shared with a group that the user is a member of.
- filters shared with a private project that the user has Browse projects project permission for.
- filters shared with a public project.
- filters shared with the public.
Tags: Filter sharing
id- required - The ID of the filter.permissionId- required - The ID of the share permission.
Deletes a share permission from a filter.
Permissions required: Permission to access Jira and the user must own the filter.
Tags: Filter sharing
id- required - The ID of the filter.permissionId- required - The ID of the share permission.
Creates a group.
Permissions required: Site administration (that is, member of the site-admin group).
Tags: Groups
Deletes a group.
Permissions required: Site administration (that is, member of the site-admin strategic group).
Tags: Groups
groupname- required - The name of the group.swapGroup- optional - The group to transfer restrictions to. Only comments and worklogs are transferred. If restrictions are not transferred, comments and worklogs are inaccessible after the deletion.
Adds a user to a group.
Permissions required: Site administration (that is, member of the site-admin group).
Tags: Groups
groupname- required - The name of the group (case sensitive).
Removes a user from a group.
Permissions required: Site administration (that is, member of the site-admin group).
Tags: Groups
groupname- required - The name of the group.username- optional - This parameter is no longer available. See the deprecation notice for details.accountId- required - The account ID of the user, which uniquely identifies the user across all Atlassian products. For example, 5b10ac8d82e05b22cc7d4ef5.
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 usingupdateandfields. The fields that can be set in the issue or subtask are determined using the Get create issue metadata. These are the same fields that appear on the issue's create screen. Note that thedescription,environment, and anytextareatype 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.
Creating a subtask differs from creating an issue as follows:
issueTypemust be set to a subtask issue type (use Get create issue metadata to find subtask issue types).parentmust contain the ID or key of the parent issue.
In a next-gen project any issue may be made a child providing that the parent and child are members of the same project. In a classic project the parent field is only valid for subtasks.
**[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.
Tags: Issues
updateHistory- optional - Whether the project in which the issue is created is added to the user's Recently viewed project list, as shown under Projects in Jira. When provided, the issue type and request type are added to the user's history for a project. These values are then used to provide defaults on the issue create screen.
Creates issues and, where the option to create subtasks is enabled in Jira, subtasks. Transitions may be applied, to move the issues or subtasks to a workflow step other than the default start step, and issue properties set.
The content of each issue or subtask is defined usingupdateandfields. The fields that can be set in the issue or subtask are determined using the Get create issue metadata. These are the same fields that appear on the issues' create screens. Note that thedescription,environment, and anytextareatype 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.
Creating a subtask differs from creating an issue as follows:
issueTypemust be set to a subtask issue type (use Get create issue metadata to find subtask issue types).parentthe 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 each issue or subtask is created.
Tags: Issues
Sets the values of entity properties on issues. It can set up to 10 entity properties on up to 10,000 issues.
The value of the request body must be a valid, non-empty JSON. The maximum length of single issue property value is 32768 characters. This operation can be accessed anonymously.
This operation is:
- transactional, either all properties are updated in all eligible issues or, when errors occur, no properties are updated.
- asynchronous. Follow the
locationlink in the response to determine the status of the task and use Get task to obtain subsequent updates.
**[Permissions](#permissions) required:**
* *Browse projects* and *Edit issues* [project permissions](https://confluence.atlassian.com/x/yodKLg) for the project containing the issue.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
Tags: Issue properties
Sets a property value on multiple issues.
The value set can be a constant or determined by a Jira expression. Expressions must be computable with constant complexity when applied to a set of issues. Expressions must also comply with the restrictions that apply to all Jira expressions.
The issues to be updated can be specified by a filter.
The filter identifies issues eligible for update using these criteria:
entityIdsOnly issues from this list are eligible.currentValueOnly issues with the property set to this value are eligible.hasProperty:
- If true, only issues with the property are eligible.
- If false, only issues without the property are eligible.
If more than one criteria is specified, they are joined with the logical *AND*: only issues that satisfy all criteria are eligible.
If an invalid combination of criteria is provided, an error is returned. For example, specifying a `currentValue` and `hasProperty` as *false* would not match any issues (because without the property the property cannot have a value).
The filter is optional. Without the filter all the issues visible to the user and where the user has the EDIT\_ISSUES permission for the issue are considered eligible.
This operation is:
* transactional, either all eligible issues are updated or, when errors occur, none are updated.
* [asynchronous](#async). Follow the `location` link in the response to determine the status of the task and use [Get task](#api-rest-api-3-task-taskId-get) to obtain subsequent updates.
**[Permissions](#permissions) required:**
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for each project containing issues.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
* *Edit issues* [project permission](https://confluence.atlassian.com/x/yodKLg) for each issue.
Tags: Issue properties
propertyKey- required - The key of the property. The maximum length is 255 characters.
Deletes a property value from multiple issues. The issues to be updated can be specified by filter criteria.
The criteria the filter used to identify eligible issues are:
entityIdsOnly issues from this list are eligible.currentValueOnly issues with the property set to this value are eligible.
If both criteria is specified, they are joined with the logical *AND*: only issues that satisfy both criteria are considered eligible.
If no filter criteria are specified, all the issues visible to the user and where the user has the EDIT\_ISSUES permission for the issue are considered eligible.
This operation is:
* transactional, either the property is deleted from all eligible issues or, when errors occur, no properties are deleted.
* [asynchronous](#async). Follow the `location` link in the response to determine the status of the task and use [Get task](#api-rest-api-3-task-taskId-get) to obtain subsequent updates.
**[Permissions](#permissions) required:**
* *Browse projects* [ project permission](https://confluence.atlassian.com/x/yodKLg) for each project containing issues.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
* *Edit issues* [project permission](https://confluence.atlassian.com/x/yodKLg) for each issue.
Tags: Issue properties
propertyKey- required - The key of the property.
Returns the details for an issue.
The issue is identified by its ID or key, however, if the identifier doesn't match an issue, a case-insensitive search and check for moved issues is performed. If a matching issue is found its details are returned, a 302 or other redirect is not returned. The issue key returned in the response is the key of the issue found.
This operation can be accessed anonymously.
Permissions required:
- Browse projects project permission for the project that the issue is in.
- If issue-level security is configured, issue-level security permission to view the issue.
Tags: Issues
issueIdOrKey- required - The ID or key of the issue.fields- optional - A list of fields to return for the issue. This parameter accepts a comma-separated list. Use it to retrieve a subset of fields. Allowed values:
* `*all` Returns all fields.
* `*navigable` Returns navigable fields.
* Any issue field, prefixed with a minus to exclude.
Examples:
* `summary,comment` Returns only the summary and comments fields.
* `-description` Returns all (default) fields except description.
* `*navigable,-comment` Returns all navigable fields except comment.
This parameter may be specified multiple times. For example, `fields=field1,field2& fields=field3`.
Note: All fields are returned by default. This differs from [Search for issues using JQL (GET)](#api-rest-api-3-search-get) and [Search for issues using JQL (POST)](#api-rest-api-3-search-post) where the default is all navigable fields.
* `fieldsByKeys` - _optional_ - Whether fields in `fields` are referenced by keys rather than IDs. This parameter is useful where fields have been added by a connect app and a field's key may differ from its ID.
* `expand` - _optional_ - Use [expand](#expansion) to include additional information about the issues in the response. This parameter accepts a comma-separated list. Expand options include:
* `renderedFields` Returns field values rendered in HTML format.
* `names` Returns the display name of each field.
* `schema` Returns the schema describing a field type.
* `transitions` Returns all possible transitions for the issue.
* `editmeta` Returns information about how each field can be edited.
* `changelog` Returns a list of recent updates to an issue, sorted by date, starting from the most recent.
* `versionedRepresentations` Returns a JSON array for each version of a field's value, with the highest number representing the most recent version. Note: When included in the request, the `fields` parameter is ignored.
* `properties` - _optional_ - A list of issue properties to return for the issue. This parameter accepts a comma-separated list. Allowed values:
* `*all` Returns all issue properties.
* Any issue property key, prefixed with a minus to exclude.
Examples:
* `*all` Returns all properties.
* `*all,-prop1` Returns all properties except `prop1`.
* `prop1,prop2` Returns `prop1` and `prop2` properties.
This parameter may be specified multiple times. For example, `properties=prop1,prop2& properties=prop3`.
* `updateHistory` - _optional_ - Whether the project in which the issue is created is added to the user's **Recently viewed** project list, as shown under **Projects** in Jira. This also populates the [JQL issues search](#api-rest-api-3-search-get) `lastViewed` field.
Edits an issue. A transition may be applied and issue properties updated as part of the edit.
The edits to the issue's fields are defined usingupdateandfields. The fields that can be edited are determined using Get edit issue metadata.
The parent field may be set by key or ID. For standard issue types, the parent may be removed by settingupdate.parent.set.noneto true. Note that thedescription,environment, and anytextareatype 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 app users with admin permission (from user permissions and app scopes) and Forge app users with themanage:jira-configurationscope can override the screen security configuration usingoverrideScreenSecurityandoverrideEditableFlag.
This operation can be accessed anonymously.
Permissions required:
- Browse projects and Edit issues project permission for the project that the issue is in.
- If issue-level security is configured, issue-level security permission to view the issue.
Tags: Issues
issueIdOrKey- required - The ID or key of the issue.notifyUsers- optional - Whether a notification email about the issue update is sent to all watchers. To disable the notification, administer Jira or administer project permissions are required. If the user doesn't have the necessary permission the request is ignored.overrideScreenSecurity- optional - Whether screen security is overridden to enable hidden fields to be edited. Available to Connect app users with admin permission and Forge app users with themanage:jira-configurationscope.overrideEditableFlag- optional - Whether screen security is overridden to enable uneditable fields to be edited. Available to Connect app users with admin permission and Forge app users with themanage:jira-configurationscope.
Deletes an issue.
An issue cannot be deleted if it has one or more subtasks. To delete an issue with subtasks, setdeleteSubtasks. This causes the issue's subtasks to be deleted with the issue.
This operation can be accessed anonymously.
Permissions required:
- Browse projects and Delete issues project permission for the project containing the issue.
- If issue-level security is configured, issue-level security permission to view the issue.
Tags: Issues
issueIdOrKey- required - The ID or key of the issue.deleteSubtasks- optional - Whether the issue's subtasks are deleted when the issue is deleted.
Possible values: true, false.
Assigns an issue to a user. Use this operation when the calling user does not have the Edit Issues permission but has the Assign issue permission for the project that the issue is in.
IfnameoraccountIdis set to:
"-1", the issue is assigned to the default assignee for the project.null, the issue is set to unassigned.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse Projects* and *Assign 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.
Tags: Issues
issueIdOrKey- required - The ID or key of the issue to be assigned.
Adds one or more attachments to an issue. Attachments are posted as multipart/form-data (RFC 1867).
Note that:
- The request must have a
X-Atlassian-Token: no-checkheader, if not it is blocked. See Special headers for more information.- The name of the multipart/form-data parameter that contains the attachments must be
file.
The following examples upload a file called *myfile.txt* to the issue *TEST-123*:
#### curl ####
curl --location --request POST 'https://your-domain.atlassian.net/rest/api/3/issue/TEST-123/attachments'
-u 'email@example.com:'
-H 'X-Atlassian-Token: no-check'
--form 'file=@"myfile.txt"'
#### Node.js ####
// This code sample uses the 'node-fetch' and 'form-data' libraries:
// https://www.npmjs.com/package/node-fetch
// https://www.npmjs.com/package/form-data
const fetch = require('node-fetch');
const FormData = require('form-data');
const fs = require('fs');
const filePath = 'myfile.txt';
const form = new FormData();
const stats = fs.statSync(filePath);
const fileSizeInBytes = stats.size;
const fileStream = fs.createReadStream(filePath);
form.append('file', fileStream, {knownLength: fileSizeInBytes});
fetch('https://your-domain.atlassian.net/rest/api/3/issue/TEST-123/attachments', {
method: 'POST',
body: form,
headers: {
'Authorization': `Basic ${Buffer.from(
'email@example.com:'
).toString('base64')}`,
'Accept': 'application/json',
'X-Atlassian-Token': 'no-check'
}
})
.then(response => {
console.log(
`Response: ${response.status} ${response.statusText}`
);
return response.text();
})
.then(text => console.log(text))
.catch(err => console.error(err));
#### Java ####
// This code sample uses the 'Unirest' library:
// http://unirest.io/java.html
HttpResponse response = Unirest.post("https://your-domain.atlassian.net/rest/api/2/issue/{issueIdOrKey}/attachments")
.basicAuth("email@example.com", "")
.header("Accept", "application/json")
.header("X-Atlassian-Token", "no-check")
.field("file", new File("myfile.txt"))
.asJson();
System.out.println(response.getBody());
#### Python ####
# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth
import json
url = "https://your-domain.atlassian.net/rest/api/2/issue/{issueIdOrKey}/attachments"
auth = HTTPBasicAuth("email@example.com", "")
headers = {
"Accept": "application/json",
"X-Atlassian-Token": "no-check"
}
response = requests.request(
"POST",
url,
headers = headers,
auth = auth,
files = {
"file": ("myfile.txt", open("myfile.txt","rb"), "application-type")
}
)
print(json.dumps(json.loads(response.text), sort_keys=True, indent=4, separators=(",", ": ")))
#### PHP ####
// This code sample uses the 'Unirest' library:
// http://unirest.io/php.html
Unirest\Request::auth('email@example.com', '');
$headers = array(
'Accept' => 'application/json',
'X-Atlassian-Token' => 'no-check'
);
$parameters = array(
'file' => File::add('myfile.txt')
);
$response = Unirest\Request::post(
'https://your-domain.atlassian.net/rest/api/2/issue/{issueIdOrKey}/attachments',
$headers,
$parameters
);
var_dump($response)
#### Forge ####
// This sample uses Atlassian Forge and the `form-data` library.
// https://developer.atlassian.com/platform/forge/
// https://www.npmjs.com/package/form-data
import api from "@forge/api";
import FormData from "form-data";
const form = new FormData();
form.append('file', fileStream, {knownLength: fileSizeInBytes});
const response = await api.asApp().requestJira('/rest/api/2/issue/{issueIdOrKey}/attachments', {
method: 'POST',
body: form,
headers: {
'Accept': 'application/json',
'X-Atlassian-Token': 'no-check'
}
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());
Tip: Use a client library. Many client libraries have classes for handling multipart POST operations. For example, in Java, the Apache HTTP Components library provides a [MultiPartEntity](http://hc.apache.org/httpcomponents-client-ga/httpmime/apidocs/org/apache/http/entity/mime/MultipartEntity.html) class for multipart POST operations.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse Projects* and *Create attachments* [ 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.
Tags: Issue attachments
issueIdOrKey- required - The ID or key of the issue that attachments are added to.
Returns changelogs for an issue specified by a list of changelog IDs.
This operation can be accessed anonymously.
Permissions required:
- Browse projects project permission for the project that the issue is in.
- If issue-level security is configured, issue-level security permission to view the issue.
Tags: Issues
issueIdOrKey- required - The ID or key of the issue.
Adds a comment to an issue.
This operation can be accessed anonymously.
Permissions required:
- Browse projects and Add comments project permission for the project that the issue containing the comment is in.
- If issue-level security is configured, issue-level security permission to view the issue.
Tags: Issue comments
issueIdOrKey- required - The ID or key of the issue.expand- optional - Use expand to include additional information about comments in the response. This parameter acceptsrenderedBody, which returns the comment body rendered in HTML.
Returns a comment.
This operation can be accessed anonymously.
Permissions required:
- Browse projects project permission for the project containing the comment.
- If issue-level security is configured, issue-level security permission to view the issue.
- If the comment has visibility restrictions, the user belongs to the group or has the role visibility is restricted to.
Tags: Issue comments
issueIdOrKey- required - The ID or key of the issue.id- required - The ID of the comment.expand- optional - Use expand to include additional information about comments in the response. This parameter acceptsrenderedBody, which returns the comment body rendered in HTML.
Updates a comment.
This operation can be accessed anonymously.
Permissions required:
- Browse projects project permission for the project that the issue containing the comment is in.
- If issue-level security is configured, issue-level security permission to view the issue.
- Edit all comments project permission to update any comment or Edit own comments to update comment created by the user.
- If the comment has visibility restrictions, the user belongs to the group or has the role visibility is restricted to.
Tags: Issue comments
issueIdOrKey- required - The ID or key of the issue.id- required - The ID of the comment.expand- optional - Use expand to include additional information about comments in the response. This parameter acceptsrenderedBody, which returns the comment body rendered in HTML.
Deletes a comment.
Permissions required:
- Browse projects project permission for the project that the issue containing the comment is in.
- If issue-level security is configured, issue-level security permission to view the issue.
- Delete all comments project permission to delete any comment or Delete own comments to delete comment created by the user,
- If the comment has visibility restrictions, the user belongs to the group or has the role visibility is restricted to.
Tags: Issue comments
issueIdOrKey- required - The ID or key of the issue.id- required - The ID of the comment.
Creates an email notification for an issue and adds it to the mail queue.
Permissions required:
- Browse Projects project permission for the project that the issue is in.
- If issue-level security is configured, issue-level security permission to view the issue.
Tags: Issues
issueIdOrKey- required - ID or key of the issue that the notification is sent for.
Returns the key and value of an issue's property.
This operation can be accessed anonymously.
Permissions required:
- Browse projects project permission for the project containing the issue.
- If issue-level security is configured, issue-level security permission to view the issue.
Tags: Issue properties
issueIdOrKey- required - The key or ID of the issue.propertyKey- required - The key of the property.
Sets the value of an issue's property. Use this resource to store custom data against an issue.
The value of the request body must be a valid, non-empty JSON blob. The maximum length is 32768 characters.
This operation can be accessed anonymously.
Permissions required:
- Browse projects and Edit issues project permissions for the project containing the issue.
- If issue-level security is configured, issue-level security permission to view the issue.
Tags: Issue properties
issueIdOrKey- required - The ID or key of the issue.propertyKey- required - The key of the issue property. The maximum length is 255 characters.
Deletes an issue's property.
This operation can be accessed anonymously.
Permissions required:
- Browse projects and Edit issues project permissions for the project containing the issue.
- If issue-level security is configured, issue-level security permission to view the issue.
Tags: Issue properties
issueIdOrKey- required - The key or ID of the issue.propertyKey- required - The key of the property.
Creates or updates a remote issue link for an issue.
If aglobalIdis provided and a remote issue link with that global ID is found it is updated. Any fields without values in the request are set to null. Otherwise, the remote issue link is created.
This operation requires issue linking to be active.
This operation can be accessed anonymously.
Permissions required:
- Browse projects and Link issues project permission for the project that the issue is in.
- If issue-level security is configured, issue-level security permission to view the issue.
Tags: Issue remote links
issueIdOrKey- required - The ID or key of the issue.
Deletes the remote issue link from the issue using the link's global ID. Where the global ID includes reserved URL characters these must be escaped in the request. For example, pass
system=http://www.mycompany.com/support&id=1assystem%3Dhttp%3A%2F%2Fwww.mycompany.com%2Fsupport%26id%3D1.
This operation requires issue linking to be active.
This operation can be accessed anonymously.
Permissions required:
- Browse projects and Link issues project permission for the project that the issue is in.
- If issue-level security is implemented, issue-level security permission to view the issue.
Tags: Issue remote links
issueIdOrKey- required - The ID or key of the issue.globalId- required - The global ID of a remote issue link.
Returns a remote issue link for an issue.
This operation requires issue linking to be active.
This operation can be accessed anonymously.
Permissions required:
- Browse projects project permission for the project that the issue is in.
- If issue-level security is configured, issue-level security permission to view the issue.
Tags: Issue remote links
issueIdOrKey- required - The ID or key of the issue.linkId- required - The ID of the remote issue link.
Updates a remote issue link for an issue.
Note: Fields without values in the request are set to null.
This operation requires issue linking to be active.
This operation can be accessed anonymously.
Permissions required:
- Browse projects and Link issues project permission for the project that the issue is in.
- If issue-level security is configured, issue-level security permission to view the issue.
Tags: Issue remote links
issueIdOrKey- required - The ID or key of the issue.linkId- required - The ID of the remote issue link.
Deletes a remote issue link from an issue.
This operation requires issue linking to be active.
This operation can be accessed anonymously.
Permissions required:
- Browse projects, Edit issues, and Link issues project permission for the project that the issue is in.
- If issue-level security is configured, issue-level security permission to view the issue.
Tags: Issue remote links
issueIdOrKey- required - The ID or key of the issue.linkId- required - The ID of a remote issue link.
Performs an issue transition and, if the transition has a screen, updates the fields from the transition screen.
sortByCategory To update the fields on the transition screen, specify the fields in thefieldsorupdateparameters in the request body. Get details about the fields using Get transitions with thetransitions.fieldsexpand.
This operation can be accessed anonymously.
Permissions required:
- Browse projects and Transition issues project permission for the project that the issue is in.
- If issue-level security is configured, issue-level security permission to view the issue.
Tags: Issues
issueIdOrKey- required - The ID or key of the issue.
Adds the user's vote to an issue. This is the equivalent of the user clicking Vote on an issue in Jira.
This operation requires the Allow users to vote on issues option to be ON. This option is set in General configuration for Jira. See Configuring Jira application options for details.
Permissions required:
- Browse projects project permission for the project that the issue is in.
- If issue-level security is configured, issue-level security permission to view the issue.
Tags: Issue votes
issueIdOrKey- required - The ID or key of the issue.
Deletes a user's vote from an issue. This is the equivalent of the user clicking Unvote on an issue in Jira.
This operation requires the Allow users to vote on issues option to be ON. This option is set in General configuration for Jira. See Configuring Jira application options for details.
Permissions required:
- Browse projects project permission for the project that the issue is in.
- If issue-level security is configured, issue-level security permission to view the issue.
Tags: Issue votes
issueIdOrKey- required - The ID or key of the issue.
Adds a user as a watcher of an issue by passing the account ID of the user. For example,
"5b10ac8d82e05b22cc7d4ef5". If no user is specified the calling user is added.
This operation requires the Allow users to watch issues option to be ON. This option is set in General configuration for Jira. See Configuring Jira application options for details.
Permissions required:
- Browse projects project permission for the project that the issue is in.
- If issue-level security is configured, issue-level security permission to view the issue.
- To add users other than themselves to the watchlist, Manage watcher list project permission for the project that the issue is in.
Tags: Issue watchers
issueIdOrKey- required - The ID or key of the issue.
Deletes a user as a watcher of an issue.
This operation requires the Allow users to watch issues option to be ON. This option is set in General configuration for Jira. See Configuring Jira application options for details.
Permissions required:
- Browse projects project permission for the project that the issue is in.
- If issue-level security is configured, issue-level security permission to view the issue.
- To remove users other than themselves from the watchlist, Manage watcher list project permission for the project that the issue is in.
Tags: Issue watchers
issueIdOrKey- required - The ID or key of the issue.username- optional - This parameter is no longer available. See the deprecation notice for details.accountId- optional - The account ID of the user, which uniquely identifies the user across all Atlassian products. For example, 5b10ac8d82e05b22cc7d4ef5. Required.
Adds a worklog to an issue.
Time tracking must be enabled in Jira, otherwise this operation returns an error. For more information, see Configuring time tracking.
This operation can be accessed anonymously.
Permissions required:
- Browse projects and Work on issues project permission for the project that the issue is in.
- If issue-level security is configured, issue-level security permission to view the issue.
Tags: Issue worklogs
issueIdOrKey- required - The ID or key the issue.notifyUsers- optional - Whether users watching the issue are notified by email.adjustEstimate- optional - Defines how to update the issue's time estimate, the options are:
* `new` Sets the estimate to a specific value, defined in `newEstimate`.
* `leave` Leaves the estimate unchanged.
* `manual` Reduces the estimate by amount specified in `reduceBy`.
* `auto` Reduces the estimate by the value of `timeSpent` in the worklog.
Possible values: new, leave, manual, auto. * `newEstimate` - _optional_ - The value to set as the issue's remaining time estimate, as days (\#d), hours (\#h), or minutes (\#m or \#). For example, *2d*. Required when `adjustEstimate` is `new`.
* `reduceBy` - _optional_ - The amount to reduce the issue's remaining estimate by, as days (\#d), hours (\#h), or minutes (\#m). For example, *2d*. Required when `adjustEstimate` is `manual`.
* `expand` - _optional_ - Use [expand](#expansion) to include additional information about work logs in the response. This parameter accepts `properties`, which returns worklog properties.
* `overrideEditableFlag` - _optional_ - Whether the worklog entry should be added to the issue even if the issue is not editable, because jira.issue.editable set to false or missing. For example, the issue is closed. Connect app users with admin permission and Forge app users with the `manage:jira-configuration` scope can use this flag.
Returns a worklog.
Time tracking must be enabled in Jira, otherwise this operation returns an error. For more information, see Configuring time tracking.
This operation can be accessed anonymously.
Permissions required:
- Browse projects project permission for the project that the issue is in.
- If issue-level security is configured, issue-level security permission to view the issue.
- If the worklog has visibility restrictions, belongs to the group or has the role visibility is restricted to.
Tags: Issue worklogs
issueIdOrKey- required - The ID or key of the issue.id- required - The ID of the worklog.expand- optional - Use expand to include additional information about work logs in the response. This parameter accepts
`properties`, which returns worklog properties.
Updates a worklog.
Time tracking must be enabled in Jira, otherwise this operation returns an error. For more information, see Configuring time tracking.
This operation can be accessed anonymously.
Permissions required:
- Browse projects project permission for the project that the issue is in.
- If issue-level security is configured, issue-level security permission to view the issue.
- Edit all worklogs project permission to update any worklog or Edit own worklogs to update worklogs created by the user.
- If the worklog has visibility restrictions, belongs to the group or has the role visibility is restricted to.
Tags: Issue worklogs
issueIdOrKey- required - The ID or key the issue.id- required - The ID of the worklog.notifyUsers- optional - Whether users watching the issue are notified by email.adjustEstimate- optional - Defines how to update the issue's time estimate, the options are:
* `new` Sets the estimate to a specific value, defined in `newEstimate`.
* `leave` Leaves the estimate unchanged.
* `auto` Updates the estimate by the difference between the original and updated value of `timeSpent` or `timeSpentSeconds`.
Possible values: new, leave, manual, auto. * `newEstimate` - _optional_ - The value to set as the issue's remaining time estimate, as days (\#d), hours (\#h), or minutes (\#m or \#). For example, *2d*. Required when `adjustEstimate` is `new`.
* `expand` - _optional_ - Use [expand](#expansion) to include additional information about worklogs in the response. This parameter accepts `properties`, which returns worklog properties.
* `overrideEditableFlag` - _optional_ - Whether the worklog should be added to the issue even if the issue is not editable. For example, because the issue is closed. Connect app users with admin permission and Forge app users with the `manage:jira-configuration` scope can use this flag.
Deletes a worklog from an issue.
Time tracking must be enabled in Jira, otherwise this operation returns an error. For more information, see Configuring time tracking.
This operation can be accessed anonymously.
Permissions required:
- Browse projects project permission for the project that the issue is in.
- If issue-level security is configured, issue-level security permission to view the issue.
- Delete all worklogs project permission to delete any worklog or Delete own worklogs to delete worklogs created by the user,
- If the worklog has visibility restrictions, belongs to the group or has the role visibility is restricted to.
Tags: Issue worklogs
issueIdOrKey- required - The ID or key of the issue.id- required - The ID of the worklog.notifyUsers- optional - Whether users watching the issue are notified by email.adjustEstimate- optional - Defines how to update the issue's time estimate, the options are:
* `new` Sets the estimate to a specific value, defined in `newEstimate`.
* `leave` Leaves the estimate unchanged.
* `manual` Increases the estimate by amount specified in `increaseBy`.
* `auto` Reduces the estimate by the value of `timeSpent` in the worklog.
Possible values: new, leave, manual, auto. * `newEstimate` - _optional_ - The value to set as the issue's remaining time estimate, as days (\#d), hours (\#h), or minutes (\#m or \#). For example, *2d*. Required when `adjustEstimate` is `new`.
* `increaseBy` - _optional_ - The amount to increase the issue's remaining estimate by, as days (\#d), hours (\#h), or minutes (\#m or \#). For example, *2d*. Required when `adjustEstimate` is `manual`.
* `overrideEditableFlag` - _optional_ - Whether the work log entry should be added to the issue even if the issue is not editable, because jira.issue.editable set to false or missing. For example, the issue is closed. Connect app users with admin permission and Forge app users with the `manage:jira-configuration` scope can use this flag.
Returns the value of a worklog property.
This operation can be accessed anonymously.
Permissions required:
- Browse projects project permission for the project that the issue is in.
- If issue-level security is configured, issue-level security permission to view the issue.
- If the worklog has visibility restrictions, belongs to the group or has the role visibility is restricted to.
Tags: Issue worklog properties
issueIdOrKey- required - The ID or key of the issue.worklogId- required - The ID of the worklog.propertyKey- required - The key of the property.
Sets the value of a worklog property. Use this operation to store custom data against the worklog.
The value of the request body must be a valid, non-empty JSON blob. The maximum length is 32768 characters.
This operation can be accessed anonymously.
Permissions required:
- Browse projects project permission for the project that the issue is in.
- If issue-level security is configured, issue-level security permission to view the issue.
- Edit all worklogs project permission to update any worklog or Edit own worklogs to update worklogs created by the user.
- If the worklog has visibility restrictions, belongs to the group or has the role visibility is restricted to.
Tags: Issue worklog properties
issueIdOrKey- required - The ID or key of the issue.worklogId- required - The ID of the worklog.propertyKey- required - The key of the issue property. The maximum length is 255 characters.
Deletes a worklog property.
This operation can be accessed anonymously.
Permissions required:
- Browse projects project permission for the project that the issue is in.
- If issue-level security is configured, issue-level security permission to view the issue.
- If the worklog has visibility restrictions, belongs to the group or has the role visibility is restricted to.
Tags: Issue worklog properties
issueIdOrKey- required - The ID or key of the issue.worklogId- required - The ID of the worklog.propertyKey- required - The key of the property.
Creates a link between two issues. Use this operation to indicate a relationship between two issues and optionally add a comment to the from (outward) issue. To use this resource the site must have Issue Linking enabled.
This resource returns nothing on the creation of an issue link. To obtain the ID of the issue link, usehttps://your-domain.atlassian.net/rest/api/3/issue/[linked issue key]?fields=issuelinks.
If the link request duplicates a link, the response indicates that the issue link was created. If the request included a comment, the comment is added.
This operation can be accessed anonymously.
Permissions required:
- Browse project project permission for all the projects containing the issues to be linked,
- Link issues project permission on the project containing the from (outward) issue,
- If issue-level security is configured, issue-level security permission to view the issue.
- If the comment has visibility restrictions, belongs to the group or has the role visibility is restricted to.
Tags: Issue links
Returns an issue link.
This operation can be accessed anonymously.
Permissions required:
- Browse project project permission for all the projects containing the linked issues.
- If issue-level security is configured, permission to view both of the issues.
Tags: Issue links
linkId- required - The ID of the issue link.
Deletes an issue link.
This operation can be accessed anonymously.
Permissions required:
- Browse project project permission for all the projects containing the issues in the link.
- Link issues project permission for at least one of the projects containing issues in the link.
- If issue-level security is configured, permission to view both of the issues.
Tags: Issue links
linkId- required - The ID of the issue link.
Creates an issue link type. Use this operation to create descriptions of the reasons why issues are linked. The issue link type consists of a name and descriptions for a link's inward and outward relationships.
To use this operation, the site must have issue linking enabled.
Permissions required: Administer Jira global permission.
Tags: Issue link types
Returns an issue link type.
To use this operation, the site must have issue linking enabled.
This operation can be accessed anonymously.
Permissions required: Browse projects project permission for a project in the site.
Tags: Issue link types
issueLinkTypeId- required - The ID of the issue link type.
Updates an issue link type.
To use this operation, the site must have issue linking enabled.
Permissions required: Administer Jira global permission.
Tags: Issue link types
issueLinkTypeId- required - The ID of the issue link type.
Deletes an issue link type.
To use this operation, the site must have issue linking enabled.
Permissions required: Administer Jira global permission.
Tags: Issue link types
issueLinkTypeId- required - The ID of the issue link type.
Returns an issue security scheme along with its security levels.
Permissions required:
- Administer Jira global permission.
- Administer Projects project permission for a project that uses the requested issue security scheme.
Tags: Issue security schemes
id- required - The ID of the issue security scheme. Use the Get issue security schemes operation to get a list of issue security scheme IDs.
Creates an issue type and adds it to the default issue type scheme.
Permissions required: Administer Jira global permission.
Tags: Issue types
Returns an issue type.
This operation can be accessed anonymously.
Permissions required: Browse projects project permission in a project the issue type is associated with or Administer Jira global permission.
Tags: Issue types
id- required - The ID of the issue type.
Updates the issue type.
Permissions required: Administer Jira global permission.
Tags: Issue types
id- required - The ID of the issue type.
Deletes the issue type. If the issue type is in use, all uses are updated with the alternative issue type (
alternativeIssueTypeId). A list of alternative issue types are obtained from the Get alternative issue types resource.
Permissions required: Administer Jira global permission.
Tags: Issue types
id- required - The ID of the issue type.alternativeIssueTypeId- optional - The ID of the replacement issue type.
Loads an avatar for the issue type.
Specify the avatar's local file location in the body of the request. Also, include the following headers:
X-Atlassian-Token: no-checkTo prevent XSRF protection blocking the request, for more information see Special Headers.Content-Type: image/image typeValid image types are JPEG, GIF, or PNG.
For example:
`curl --request POST \ --user email@example.com: \ --header 'X-Atlassian-Token: no-check' \ --header 'Content-Type: image/< image_type>' \ --data-binary "<@/path/to/file/with/your/avatar>" \ --url 'https://your-domain.atlassian.net/rest/api/3/issuetype/{issueTypeId}'This`
The avatar is cropped to a square. If no crop parameters are specified, the square originates at the top left of the image. The length of the square's sides is set to the smaller of the height or width of the image.
The cropped image is then used to create avatars of 16x16, 24x24, 32x32, and 48x48 in size.
After creating the avatar, use [ Update issue type](#api-rest-api-3-issuetype-id-put) to set it as the issue type's displayed avatar.
**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
Tags: Issue types
id- required - The ID of the issue type.x- optional - The X coordinate of the top-left corner of the crop region.y- optional - The Y coordinate of the top-left corner of the crop region.size- required - The length of each side of the crop region.
Returns the key and value of the issue type property.
This operation can be accessed anonymously.
Permissions required:
- Administer Jira global permission to get the details of any issue type.
- Browse projects project permission to get the details of any issue types associated with the projects the user has permission to browse.
Tags: Issue type properties
issueTypeId- required - The ID of the issue type.propertyKey- required - The key of the property. Use Get issue type property keys to get a list of all issue type property keys.
Creates or updates the value of the issue type property. Use this resource to store and update data against an issue type.
The value of the request body must be a valid, non-empty JSON blob. The maximum length is 32768 characters.
Permissions required: Administer Jira global permission.
Tags: Issue type properties
issueTypeId- required - The ID of the issue type.propertyKey- required - The key of the issue type property. The maximum length is 255 characters.
Deletes the issue type property.
Permissions required: Administer Jira global permission.
Tags: Issue type properties
issueTypeId- required - The ID of the issue type.propertyKey- required - The key of the property. Use Get issue type property keys to get a list of all issue type property keys.
Creates an issue type scheme.
Permissions required: Administer Jira global permission.
Tags: Issue type schemes
Assigns an issue type scheme to a project.
If any issues in the project are assigned issue types not present in the new scheme, the operation will fail. To complete the assignment those issues must be updated to use issue types in the new scheme.
Issue type schemes can only be assigned to classic projects.
Permissions required: Administer Jira global permission.
Tags: Issue type schemes
Updates an issue type scheme.
Permissions required: Administer Jira global permission.
Tags: Issue type schemes
issueTypeSchemeId- required - The ID of the issue type scheme.
Deletes an issue type scheme.
Only issue type schemes used in classic projects can be deleted.
Any projects assigned to the scheme are reassigned to the default issue type scheme.
Permissions required: Administer Jira global permission.
Tags: Issue type schemes
issueTypeSchemeId- required - The ID of the issue type scheme.
Adds issue types to an issue type scheme.
The added issue types are appended to the issue types list.
If any of the issue types exist in the issue type scheme, the operation fails and no issue types are added.
Permissions required: Administer Jira global permission.
Tags: Issue type schemes
issueTypeSchemeId- required - The ID of the issue type scheme.
Changes the order of issue types in an issue type scheme.
The request body parameters must meet the following requirements:
- all of the issue types must belong to the issue type scheme.
- either
afterorpositionmust be provided.- the issue type in
aftermust not be in the issue type list.
**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
Tags: Issue type schemes
issueTypeSchemeId- required - The ID of the issue type scheme.
Removes an issue type from an issue type scheme.
This operation cannot remove:
- any issue type used by issues.
- any issue types from the default issue type scheme.
- the last standard issue type from an issue type scheme.
**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
Tags: Issue type schemes
issueTypeSchemeId- required - The ID of the issue type scheme.issueTypeId- required - The ID of the issue type.
Creates an issue type screen scheme.
Permissions required: Administer Jira global permission.
Tags: Issue type screen schemes
Assigns an issue type screen scheme to a project.
Issue type screen schemes can only be assigned to classic projects.
Permissions required: Administer Jira global permission.
Tags: Issue type screen schemes
Updates an issue type screen scheme.
Permissions required: Administer Jira global permission.
Tags: Issue type screen schemes
issueTypeScreenSchemeId- required - The ID of the issue type screen scheme.
Deletes an issue type screen scheme.
Permissions required: Administer Jira global permission.
Tags: Issue type screen schemes
issueTypeScreenSchemeId- required - The ID of the issue type screen scheme.
Appends issue type to screen scheme mappings to an issue type screen scheme.
Permissions required: Administer Jira global permission.
Tags: Issue type screen schemes
issueTypeScreenSchemeId- required - The ID of the issue type screen scheme.
Updates the default screen scheme of an issue type screen scheme. The default screen scheme is used for all unmapped issue types.
Permissions required: Administer Jira global permission.
Tags: Issue type screen schemes
issueTypeScreenSchemeId- required - The ID of the issue type screen scheme.
Removes issue type to screen scheme mappings from an issue type screen scheme.
Permissions required: Administer Jira global permission.
Tags: Issue type screen schemes
issueTypeScreenSchemeId- required - The ID of the issue type screen scheme.
Returns reference data for JQL searches. This is a downloadable version of the documentation provided in Advanced searching - fields reference and Advanced searching - functions reference, along with a list of JQL-reserved words. Use this information to assist with the programmatic creation of JQL queries or the validation of queries built in a custom query builder.
This operation can filter the custom fields returned by project. Invalid project IDs inprojectIdsare ignored. System fields are always returned.
It can also return the collapsed field for custom fields. Collapsed fields enable searches to be performed across all fields with the same name and of the same field type. For example, the collapsed fieldComponent - Component[Dropdown]enables dropdown fieldsComponent - cf[10061]andComponent - cf[10062]to be searched simultaneously.
Permissions required: None.
Tags: JQL
Checks whether one or more issues would be returned by one or more JQL queries.
Permissions required: None, however, issues are only matched against JQL queries where the user has:
- Browse projects project permission for the project that the issue is in.
- If issue-level security is configured, issue-level security permission to view the issue.
Tags: Issue search
Parses and validates JQL queries.
Validation is performed in context of the current user.
This operation can be accessed anonymously.
Permissions required: None.
Tags: JQL
validation- optional - How to validate the JQL query and treat the validation results. Validation options include:
* `strict` Returns all errors. If validation fails, the query structure is not returned.
* `warn` Returns all errors. If validation fails but the JQL query is correctly formed, the query structure is returned.
* `none` No validation is performed. If JQL query is correctly formed, the query structure is returned.
Possible values: strict, warn, none.
Converts one or more JQL queries with user identifiers (username or user key) to equivalent JQL queries with account IDs.
You may wish to use this operation if your system stores JQL queries and you want to make them GDPR-compliant. For more information about GDPR-related changes, see the migration guide.
Permissions required: Permission to access Jira.
Tags: JQL
Creates a preference for the user or updates a preference's value by sending a plain text string. For example,
false. An arbitrary preference can be created with the value containing up to 255 characters. In addition, the following keys define system preferences that can be set or created:
- user.notifications.mimetype The mime type used in notifications sent to the user. Defaults to
html.- user.notify.own.changes Whether the user gets notified of their own changes. Defaults to
false.- user.default.share.private Whether new filters are set to private. Defaults to
true.- user.keyboard.shortcuts.disabled Whether keyboard shortcuts are disabled. Defaults to
false.- user.autowatch.disabled Whether the user automatically watches issues they create or add a comment to. By default, not set: the user takes the instance autowatch setting.
Note that these keys are deprecated:
* *jira.user.locale* The locale of the user. By default, not set. The user takes the instance locale.
* *jira.user.timezone* The time zone of the user. By default, not set. The user takes the instance timezone.
Use [ Update a user profile](https://developer.atlassian.com/cloud/admin/user-management/rest/#api-users-account-id-manage-profile-patch) from the user management REST API to manage timezone and locale instead.
**[Permissions](#permissions) required:** Permission to access Jira.
Tags: Myself
key- required - The key of the preference. The maximum length is 255 characters.
Deletes a preference of the user, which restores the default value of system defined settings.
Note that these keys are deprecated:
- jira.user.locale The locale of the user. By default, not set. The user takes the instance locale.
- jira.user.timezone The time zone of the user. By default, not set. The user takes the instance timezone.
Use [ Update a user profile](https://developer.atlassian.com/cloud/admin/user-management/rest/#api-users-account-id-manage-profile-patch) from the user management REST API to manage timezone and locale instead.
**[Permissions](#permissions) required:** Permission to access Jira.
Tags: Myself
key- required - The key of the preference.
Deprecated, use Update a user profile from the user management REST API instead.
Sets the locale of the user. The locale must be one supported by the instance of Jira.
Permissions required: Permission to access Jira.
Tags: Myself
Deprecated, use Update a user profile from the user management REST API instead.
Deletes the locale of the user, which restores the default setting.
Permissions required: Permission to access Jira.
Tags: Myself
Returns a notification scheme, including the list of events and the recipients who will receive notifications for those events.
Permissions required: Permission to access Jira, however the user must have permission to administer at least one project associated with the notification scheme.
Tags: Issue notification schemes
id- required - The ID of the notification scheme. Use Get notification schemes paginated to get a list of notification scheme IDs.expand- optional - Use expand to include additional information in the response. This parameter accepts a comma-separated list. Expand options include:
* `all` Returns all expandable information.
* `field` Returns information about any custom fields assigned to receive an event.
* `group` Returns information about any groups assigned to receive an event.
* `notificationSchemeEvents` Returns a list of event associations. This list is returned for all expandable information.
* `projectRole` Returns information about any project roles assigned to receive an event.
* `user` Returns information about any users assigned to receive an event.
Returns:
- for a list of global permissions, the global permissions granted to a user.
- for a list of project permissions and lists of projects and issues, for each project permission a list of the projects and issues a user can access or manipulate.
If no account ID is provided, the operation returns details for the logged in user.
Note that:
* Invalid project and issue IDs are ignored.
* A maximum of 1000 projects and 1000 issues can be checked.
* Null values in `globalPermissions`, `projectPermissions`, `projectPermissions.projects`, and `projectPermissions.issues` are ignored.
* Empty strings in `projectPermissions.permissions` are ignored.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg) to check the permissions for other users, otherwise none. However, Connect apps can make a call from the app server to the product to obtain permission details for any user, without admin permission. This Connect app ability doesn't apply to calls made using AP.request() in a browser.
Tags: Permissions
Returns all the projects where the user is granted a list of project permissions.
This operation can be accessed anonymously.
Permissions required: None.
Tags: Permissions
Creates a new permission scheme. You can create a permission scheme with or without defining a set of permission grants.
Permissions required: Administer Jira global permission.
Tags: Permission schemes
expand- optional - Use expand to include additional information in the response. This parameter accepts a comma-separated list. Note that permissions are always included when you specify any value. Expand options include:
* `all` Returns all expandable information.
* `field` Returns information about the custom field granted the permission.
* `group` Returns information about the group that is granted the permission.
* `permissions` Returns all permission grants for each permission scheme.
* `projectRole` Returns information about the project role granted the permission.
* `user` Returns information about the user who is granted the permission.
Returns a permission scheme.
Permissions required: Permission to access Jira.
Tags: Permission schemes
schemeId- required - The ID of the permission scheme to return.expand- optional - Use expand to include additional information in the response. This parameter accepts a comma-separated list. Note that permissions are included when you specify any value. Expand options include:
* `all` Returns all expandable information.
* `field` Returns information about the custom field granted the permission.
* `group` Returns information about the group that is granted the permission.
* `permissions` Returns all permission grants for each permission scheme.
* `projectRole` Returns information about the project role granted the permission.
* `user` Returns information about the user who is granted the permission.
Updates a permission scheme. Below are some important things to note when using this resource:
- If a permissions list is present in the request, then it is set in the permission scheme, overwriting all existing grants.
- If you want to update only the name and description, then do not send a permissions list in the request.
- Sending an empty list will remove all permission grants from the permission scheme.
If you want to add or delete a permission grant instead of updating the whole list, see [Create permission grant](#api-rest-api-3-permissionscheme-schemeId-permission-post) or [Delete permission scheme entity](#api-rest-api-3-permissionscheme-schemeId-permission-permissionId-delete).
See [About permission schemes and grants](../api-group-permission-schemes/#about-permission-schemes-and-grants) for more details.
**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
Tags: Permission schemes
schemeId- required - The ID of the permission scheme to update.expand- optional - Use expand to include additional information in the response. This parameter accepts a comma-separated list. Note that permissions are always included when you specify any value. Expand options include:
* `all` Returns all expandable information.
* `field` Returns information about the custom field granted the permission.
* `group` Returns information about the group that is granted the permission.
* `permissions` Returns all permission grants for each permission scheme.
* `projectRole` Returns information about the project role granted the permission.
* `user` Returns information about the user who is granted the permission.
Deletes a permission scheme.
Permissions required: Administer Jira global permission.
Tags: Permission schemes
schemeId- required - The ID of the permission scheme being deleted.
Creates a permission grant in a permission scheme.
Permissions required: Administer Jira global permission.
Tags: Permission schemes
schemeId- required - The ID of the permission scheme in which to create a new permission grant.expand- optional - Use expand to include additional information in the response. This parameter accepts a comma-separated list. Note that permissions are always included when you specify any value. Expand options include:
* `permissions` Returns all permission grants for each permission scheme.
* `user` Returns information about the user who is granted the permission.
* `group` Returns information about the group that is granted the permission.
* `projectRole` Returns information about the project role granted the permission.
* `field` Returns information about the custom field granted the permission.
* `all` Returns all expandable information.
Returns a permission grant.
Permissions required: Permission to access Jira.
Tags: Permission schemes
schemeId- required - The ID of the permission scheme.permissionId- required - The ID of the permission grant.expand- optional - Use expand to include additional information in the response. This parameter accepts a comma-separated list. Note that permissions are always included when you specify any value. Expand options include:
* `all` Returns all expandable information.
* `field` Returns information about the custom field granted the permission.
* `group` Returns information about the group that is granted the permission.
* `permissions` Returns all permission grants for each permission scheme.
* `projectRole` Returns information about the project role granted the permission.
* `user` Returns information about the user who is granted the permission.
Deletes a permission grant from a permission scheme. See About permission schemes and grants for more details.
Permissions required: Administer Jira global permission.
Tags: Permission schemes
schemeId- required - The ID of the permission scheme to delete the permission grant from.permissionId- required - The ID of the permission grant to delete.
Returns an issue priority.
Permissions required: Permission to access Jira.
Tags: Issue priorities
id- required - The ID of the issue priority.
Creates a project based on a project type template, as shown in the following table:
| Project Type Key | Project Template Key |
|--|--|
|business|com.atlassian.jira-core-project-templates:jira-core-simplified-content-management,com.atlassian.jira-core-project-templates:jira-core-simplified-document-approval,com.atlassian.jira-core-project-templates:jira-core-simplified-lead-tracking,com.atlassian.jira-core-project-templates:jira-core-simplified-process-control,com.atlassian.jira-core-project-templates:jira-core-simplified-procurement,com.atlassian.jira-core-project-templates:jira-core-simplified-project-management,com.atlassian.jira-core-project-templates:jira-core-simplified-recruitment,com.atlassian.jira-core-project-templates:jira-core-simplified-task-tracking|
|service_desk|com.atlassian.servicedesk:simplified-it-service-management,com.atlassian.servicedesk:simplified-general-service-desk,com.atlassian.servicedesk:simplified-internal-service-desk,com.atlassian.servicedesk:simplified-external-service-desk,com.atlassian.servicedesk:simplified-hr-service-desk,com.atlassian.servicedesk:simplified-facilities-service-desk,com.atlassian.servicedesk:simplified-legal-service-desk|
|software|com.pyxis.greenhopper.jira:gh-simplified-agility-kanban,com.pyxis.greenhopper.jira:gh-simplified-agility-scrum,com.pyxis.greenhopper.jira:gh-simplified-basic,com.pyxis.greenhopper.jira:gh-simplified-kanban-classic,com.pyxis.greenhopper.jira:gh-simplified-scrum-classic|
The project types are available according to the installed Jira features as follows:
- Jira Core, the default, enables
businessprojects.- Jira Service Management enables
service_deskprojects.- Jira Software enables
softwareprojects.
To determine which features are installed, go to **Jira settings** > **Apps** > **Manage apps** and review the System Apps list. To add Jira Software or Jira Service Management into a JIRA instance, use **Jira settings** > **Apps** > **Finding new apps**. For more information, see [ Managing add-ons](https://confluence.atlassian.com/x/S31NLg).
**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
Tags: Projects
Returns a project type.
This operation can be accessed anonymously.
Permissions required: None.
Tags: Project types
projectTypeKey- required - The key of the project type.
Possible values: software, service_desk, business, product_discovery.
Returns the project details for a project.
This operation can be accessed anonymously.
Permissions required: Browse projects project permission for the project.
Tags: Projects
projectIdOrKey- required - The project ID or project key (case sensitive).expand- optional - Use expand to include additional information in the response. This parameter accepts a comma-separated list. Note that the project description, issue types, and project lead are included in all responses by default. Expand options include:
* `description` The project description.
* `issueTypes` The issue types associated with the project.
* `lead` The project lead.
* `projectKeys` All project keys associated with the project.
* `issueTypeHierarchy` The project issue type hierarchy.
* `properties` - _optional_ - A list of project properties to return for the project. This parameter accepts a comma-separated list.
Updates the project details of a project.
All parameters are optional in the body of the request.
Permissions required: Administer Jira global permission.
Tags: Projects
projectIdOrKey- required - The project ID or project key (case sensitive).expand- optional - Use expand to include additional information in the response. This parameter accepts a comma-separated list. Note that the project description, issue types, and project lead are included in all responses by default. Expand options include:
* `description` The project description.
* `issueTypes` The issue types associated with the project.
* `lead` The project lead.
* `projectKeys` All project keys associated with the project.
Deletes a project.
You can't delete a project if it's archived. To delete an archived project, restore the project and then delete it. To restore a project, use the Jira UI.
Permissions required: Administer Jira global permission.
Tags: Projects
projectIdOrKey- required - The project ID or project key (case sensitive).enableUndo- optional - Whether this project is placed in the Jira recycle bin where it will be available for restoration.
Archives a project. You can't delete a project if it's archived. To delete an archived project, restore the project and then delete it. To restore a project, use the Jira UI.
Permissions required: Administer Jira global permission.
Tags: Projects
projectIdOrKey- required - The project ID or project key (case sensitive).
Sets the avatar displayed for a project.
Use Load project avatar to store avatars against the project, before using this operation to set the displayed avatar.
Permissions required: Administer projects project permission.
Tags: Project avatars
projectIdOrKey- required - The ID or (case-sensitive) key of the project.
Deletes a custom avatar from a project. Note that system avatars cannot be deleted.
Permissions required: Administer projects project permission.
Tags: Project avatars
projectIdOrKey- required - The project ID or (case-sensitive) key.id- required - The ID of the avatar.
Loads an avatar for a project.
Specify the avatar's local file location in the body of the request. Also, include the following headers:
X-Atlassian-Token: no-checkTo prevent XSRF protection blocking the request, for more information see Special Headers.Content-Type: image/image typeValid image types are JPEG, GIF, or PNG.
For example:
`curl --request POST `
`--user email@example.com: `
`--header 'X-Atlassian-Token: no-check' `
`--header 'Content-Type: image/< image_type>' `
`--data-binary "<@/path/to/file/with/your/avatar>" `
`--url 'https://your-domain.atlassian.net/rest/api/3/project/{projectIdOrKey}/avatar2'`
The avatar is cropped to a square. If no crop parameters are specified, the square originates at the top left of the image. The length of the square's sides is set to the smaller of the height or width of the image.
The cropped image is then used to create avatars of 16x16, 24x24, 32x32, and 48x48 in size.
After creating the avatar use [Set project avatar](#api-rest-api-3-project-projectIdOrKey-avatar-put) to set it as the project's displayed avatar.
**[Permissions](#permissions) required:** *Administer projects* [project permission](https://confluence.atlassian.com/x/yodKLg).
Tags: Project avatars
projectIdOrKey- required - The ID or (case-sensitive) key of the project.x- optional - The X coordinate of the top-left corner of the crop region.y- optional - The Y coordinate of the top-left corner of the crop region.size- optional - The length of each side of the crop region.
Deletes a project asynchronously.
This operation is:
- transactional, that is, if part of the delete fails the project is not deleted.
- asynchronous. Follow the
locationlink in the response to determine the status of the task and use Get task to obtain subsequent updates.
**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
Tags: Projects
projectIdOrKey- required - The project ID or project key (case sensitive).
Returns the value of a project property.
This operation can be accessed anonymously.
Permissions required: Browse Projects project permission for the project containing the property.
Tags: Project properties
projectIdOrKey- required - The project ID or project key (case sensitive).propertyKey- required - The project property key. Use Get project property keys to get a list of all project property keys.
Sets the value of the project property. You can use project properties to store custom data against the project.
The value of the request body must be a valid, non-empty JSON blob. The maximum length is 32768 characters.
This operation can be accessed anonymously.
Permissions required: Administer Jira global permission or Administer Projects project permission for the project in which the property is created.
Tags: Project properties
projectIdOrKey- required - The project ID or project key (case sensitive).propertyKey- required - The key of the project property. The maximum length is 255 characters.
Deletes the property from a project.
This operation can be accessed anonymously.
Permissions required: Administer Jira global permission or Administer Projects project permission for the project containing the property.
Tags: Project properties
projectIdOrKey- required - The project ID or project key (case sensitive).propertyKey- required - The project property key. Use Get project property keys to get a list of all project property keys.
Restores a project from the Jira recycle bin.
Permissions required: Administer Jira global permission.
Tags: Projects
projectIdOrKey- required - The project ID or project key (case sensitive).
Returns a project role's details and actors associated with the project. The list of actors is sorted by display name.
To check whether a user belongs to a role based on their group memberships, use Get user with thegroupsexpand parameter selected. Then check whether the user keys and groups match with the actors returned for the project.
This operation can be accessed anonymously.
Permissions required: Administer Projects project permission for the project or Administer Jira global permission.
Tags: Project roles
projectIdOrKey- required - The project ID or project key (case sensitive).id- required - The ID of the project role. Use Get all project roles to get a list of project role IDs.
Sets the actors for a project role for a project, replacing all existing actors.
To add actors to the project without overwriting the existing list, use Add actors to project role.
Permissions required: Administer Projects project permission for the project or Administer Jira global permission.
Tags: Project role actors
projectIdOrKey- required - The project ID or project key (case sensitive).id- required - The ID of the project role. Use Get all project roles to get a list of project role IDs.
Adds actors to a project role for the project.
To replace all actors for the project, use Set actors for project role.
This operation can be accessed anonymously.
Permissions required: Administer Projects project permission for the project or Administer Jira global permission.
Tags: Project role actors
projectIdOrKey- required - The project ID or project key (case sensitive).id- required - The ID of the project role. Use Get all project roles to get a list of project role IDs.
Deletes actors from a project role for the project.
To remove default actors from the project role, use Delete default actors from project role.
This operation can be accessed anonymously.
Permissions required: Administer Projects project permission for the project or Administer Jira global permission.
Tags: Project role actors
projectIdOrKey- required - The project ID or project key (case sensitive).id- required - The ID of the project role. Use Get all project roles to get a list of project role IDs.user- optional - The user account ID of the user to remove from the project role.group- optional - The name of the group to remove from the project role.
Deprecated, this feature is no longer supported and no alternatives are available, see Convert project to a different template or type. Updates a project type. The project type can be updated for classic projects only, project type cannot be updated for next-gen projects.
Permissions required: Administer Jira global permission.
Tags: Projects
projectIdOrKey- required - The project ID or project key (case sensitive).newProjectTypeKey- required - The key of the new project type.
Possible values: software, service_desk, business.
Sets the project's sender email address.
IfemailAddressis an empty string, the default email address is restored.
Permissions required: Browse projects project permission for the project.
Tags: Project email
projectId- required - The project ID.
Assigns a permission scheme with a project. See Managing project permissions for more information about permission schemes.
Permissions required: Administer Jira global permission
Tags: Project permission schemes
projectKeyOrId- required - The project ID or project key (case sensitive).expand- optional - Use expand to include additional information in the response. This parameter accepts a comma-separated list. Note that permissions are included when you specify any value. Expand options include:
* `all` Returns all expandable information.
* `field` Returns information about the custom field granted the permission.
* `group` Returns information about the group that is granted the permission.
* `permissions` Returns all permission grants for each permission scheme.
* `projectRole` Returns information about the project role granted the permission.
* `user` Returns information about the user who is granted the permission.
Creates a project category.
Permissions required: Administer Jira global permission.
Tags: Project categories
Returns a project category.
Permissions required: Permission to access Jira.
Tags: Project categories
id- required - The ID of the project category.
Updates a project category.
Permissions required: Administer Jira global permission.
Tags: Project categories
id- required
Deletes a project category.
Permissions required: Administer Jira global permission.
Tags: Project categories
id- required - ID of the project category to delete.
Returns an issue resolution value.
Permissions required: Permission to access Jira.
Tags: Issue resolutions
id- required - The ID of the issue resolution value.
Creates a new project role with no default actors. You can use the Add default actors to project role operation to add default actors to the project role after creating it.
Note that although a new project role is available to all projects upon creation, any default actors that are associated with the project role are not added to projects that existed prior to the role being created.<
Permissions required: Administer Jira global permission.
Tags: Project roles
Gets the project role details and the default actors associated with the role. The list of default actors is sorted by display name.
Permissions required: Administer Jira global permission.
Tags: Project roles
id- required - The ID of the project role. Use Get all project roles to get a list of project role IDs.
Updates the project role's name and description. You must include both a name and a description in the request.
Permissions required: Administer Jira global permission.
Tags: Project roles
id- required - The ID of the project role. Use Get all project roles to get a list of project role IDs.
Updates either the project role's name or its description.
You cannot update both the name and description at the same time using this operation. If you send a request with a name and a description only the name is updated.
Permissions required: Administer Jira global permission.
Tags: Project roles
id- required - The ID of the project role. Use Get all project roles to get a list of project role IDs.
Deletes a project role. You must specify a replacement project role if you wish to delete a project role that is in use.
Permissions required: Administer Jira global permission.
Tags: Project roles
id- required - The ID of the project role to delete. Use Get all project roles to get a list of project role IDs.swap- optional - The ID of the project role that will replace the one being deleted.
Adds default actors to a role. You may add groups or users, but you cannot add groups and users in the same request.
Changing a project role's default actors does not affect project role members for projects already created.
Permissions required: Administer Jira global permission.
Tags: Project role actors
id- required - The ID of the project role. Use Get all project roles to get a list of project role IDs.
Deletes the default actors from a project role. You may delete a group or user, but you cannot delete a group and a user in the same request.
Changing a project role's default actors does not affect project role members for projects already created.
Permissions required: Administer Jira global permission.
Tags: Project role actors
id- required - The ID of the project role. Use Get all project roles to get a list of project role IDs.user- optional - The user account ID of the user to remove as a default actor.group- optional - The group name of the group to be removed as a default actor.
Creates a screen with a default field tab.
Permissions required: Administer Jira global permission.
Tags: Screens
Adds a field to the default tab of the default screen.
Permissions required: Administer Jira global permission.
Tags: Screens
fieldId- required - The ID of the field.
Updates a screen. Only screens used in classic projects can be updated.
Permissions required: Administer Jira global permission.
Tags: Screens
screenId- required - The ID of the screen.
Deletes a screen. A screen cannot be deleted if it is used in a screen scheme, workflow, or workflow draft.
Only screens used in classic projects can be deleted.
Tags: Screens
screenId- required - The ID of the screen.
Creates a tab for a screen.
Permissions required: Administer Jira global permission.
Tags: Screen tabs
screenId- required - The ID of the screen.
Updates the name of a screen tab.
Permissions required: Administer Jira global permission.
Tags: Screen tabs
screenId- required - The ID of the screen.tabId- required - The ID of the screen tab.
Deletes a screen tab.
Permissions required: Administer Jira global permission.
Tags: Screen tabs
screenId- required - The ID of the screen.tabId- required - The ID of the screen tab.
Adds a field to a screen tab.
Permissions required: Administer Jira global permission.
Tags: Screen tab fields
screenId- required - The ID of the screen.tabId- required - The ID of the screen tab.
Removes a field from a screen tab.
Permissions required: Administer Jira global permission.
Tags: Screen tab fields
screenId- required - The ID of the screen.tabId- required - The ID of the screen tab.id- required - The ID of the field.
Moves a screen tab field.
Ifafterandpositionare provided in the request,positionis ignored.
Permissions required: Administer Jira global permission.
Tags: Screen tab fields
screenId- required - The ID of the screen.tabId- required - The ID of the screen tab.id- required - The ID of the field.
Moves a screen tab.
Permissions required: Administer Jira global permission.
Tags: Screen tabs
screenId- required - The ID of the screen.tabId- required - The ID of the screen tab.pos- required - The position of tab. The base index is 0.
Creates a screen scheme.
Permissions required: Administer Jira global permission.
Tags: Screen schemes
Updates a screen scheme. Only screen schemes used in classic projects can be updated.
Permissions required: Administer Jira global permission.
Tags: Screen schemes
screenSchemeId- required - The ID of the screen scheme.
Deletes a screen scheme. A screen scheme cannot be deleted if it is used in an issue type screen scheme.
Only screens schemes used in classic projects can be deleted.
Permissions required: Administer Jira global permission.
Tags: Screen schemes
screenSchemeId- required - The ID of the screen scheme.
Searches for issues using JQL.
There is a GET version of this resource that can be used for smaller JQL query expressions.
This operation can be accessed anonymously.
Permissions required: Issues are included in the response where the user has:
- Browse projects project permission for the project containing the issue.
- If issue-level security is configured, issue-level security permission to view the issue.
Tags: Issue search
Returns details of an issue security level.
Use Get issue security scheme to obtain the IDs of issue security levels associated with the issue security scheme.
This operation can be accessed anonymously.
Permissions required: None.
Tags: Issue security level
id- required - The ID of the issue security level.
Sets the default issue navigator columns.
Thecolumnsparameter accepts a navigable field value and is expressed as HTML form data. To specify multiple columns, pass multiplecolumnsparameters. For example, in curl:
curl -X PUT -d columns=summary -d columns=description https://your-domain.atlassian.net/rest/api/3/settings/columns
If no column details are sent, then all default columns are removed.
A navigable field is one that can be used as a column on the issue navigator. Find details of navigable issue columns using Get fields.
Permissions required: Administer Jira global permission.
Tags: Issue navigator settings
Returns a status. The status must be associated with a workflow to be returned.
If a name is used on more than one status, only the status found first is returned. Therefore, identifying the status by its ID may be preferable.
This operation can be accessed anonymously.
Permissions required: None.
Tags: Workflow statuses
idOrName- required - The ID or name of the status.
Returns a status category. Status categories provided a mechanism for categorizing statuses.
Permissions required: Permission to access Jira.
Tags: Workflow status categories
idOrKey- required - The ID or key of the status category.
Returns the status of a long-running asynchronous task.
When a task has finished, this operation returns the JSON blob applicable to the task. See the documentation of the operation that created the task for details. Task details are not permanently retained. As of September 2019, details are retained for 14 days although this period may change without notice.
Permissions required: either of:
- Administer Jira global permission.
- Creator of the task.
Tags: Tasks
taskId- required - The ID of the task.
Cancels a task.
Permissions required: either of:
- Administer Jira global permission.
- Creator of the task.
Tags: Tasks
taskId- required - The ID of the task.
Returns the system and custom avatars for a project or issue type.
This operation can be accessed anonymously.
Permissions required:
- for custom project avatars, Browse projects project permission for the project the avatar belongs to.
- for custom issue type avatars, Browse projects project permission for at least one project the issue type is used in.
- for system avatars, none.
Tags: Avatars
type- required - The avatar type.
Possible values: project, issuetype.entityId- required - The ID of the item the avatar is associated with.
Loads a custom avatar for a project or issue type.
Specify the avatar's local file location in the body of the request. Also, include the following headers:
X-Atlassian-Token: no-checkTo prevent XSRF protection blocking the request, for more information see Special Headers.Content-Type: image/image typeValid image types are JPEG, GIF, or PNG.
For example:
`curl --request POST `
`--user email@example.com: `
`--header 'X-Atlassian-Token: no-check' `
`--header 'Content-Type: image/< image_type>' `
`--data-binary "<@/path/to/file/with/your/avatar>" `
`--url 'https://your-domain.atlassian.net/rest/api/3/universal_avatar/type/{type}/owner/{entityId}'`
The avatar is cropped to a square. If no crop parameters are specified, the square originates at the top left of the image. The length of the square's sides is set to the smaller of the height or width of the image.
The cropped image is then used to create avatars of 16x16, 24x24, 32x32, and 48x48 in size.
After creating the avatar use:
* [Update issue type](#api-rest-api-3-issuetype-id-put) to set it as the issue type's displayed avatar.
* [Set project avatar](#api-rest-api-3-project-projectIdOrKey-avatar-put) to set it as the project's displayed avatar.
**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
Tags: Avatars
type- required - The avatar type.
Possible values: project, issuetype.entityId- required - The ID of the item the avatar is associated with.x- optional - The X coordinate of the top-left corner of the crop region.y- optional - The Y coordinate of the top-left corner of the crop region.size- required - The length of each side of the crop region.
Deletes an avatar from a project or issue type.
Permissions required: Administer Jira global permission.
Tags: Avatars
type- required - The avatar type.
Possible values: project, issuetype.owningObjectId- required - The ID of the item the avatar is associated with.id- required - The ID of the avatar.
Returns the default project or issue type avatar image.
This operation can be accessed anonymously.
Permissions required: None.
Tags: Avatars
type- required - The icon type of the avatar.
Possible values: issuetype, project.size- optional - The size of the avatar image. If not provided the default size is returned.
Possible values: xsmall, small, medium, large, xlarge.format- optional - The format to return the avatar image in. If not provided the original content format is returned.
Possible values: png.
Returns a project or issue type avatar image by ID.
This operation can be accessed anonymously.
Permissions required:
- For system avatars, none.
- For custom project avatars, Browse projects project permission for the project the avatar belongs to.
- For custom issue type avatars, Browse projects project permission for at least one project the issue type is used in.
Tags: Avatars
type- required - The icon type of the avatar.
Possible values: issuetype, project.id- required - The ID of the avatar.size- optional - The size of the avatar image. If not provided the default size is returned.
Possible values: xsmall, small, medium, large, xlarge.format- optional - The format to return the avatar image in. If not provided the original content format is returned.
Possible values: png.
Returns the avatar image for a project or issue type.
This operation can be accessed anonymously.
Permissions required:
- For system avatars, none.
- For custom project avatars, Browse projects project permission for the project the avatar belongs to.
- For custom issue type avatars, Browse projects project permission for at least one project the issue type is used in.
Tags: Avatars
type- required - The icon type of the avatar.
Possible values: issuetype, project.entityId- required - The ID of the project or issue type the avatar belongs to.size- optional - The size of the avatar image. If not provided the default size is returned.
Possible values: xsmall, small, medium, large, xlarge.format- optional - The format to return the avatar image in. If not provided the original content format is returned.
Possible values: png.
Creates a user. This resource is retained for legacy compatibility. As soon as a more suitable alternative is available this resource will be deprecated.
If the user exists and has access to Jira, the operation returns a 201 status. If the user exists but does not have access to Jira, the operation returns a 400 status.
Permissions required: Administer Jira global permission.
Tags: Users
Deletes a user.
Permissions required: Site administration (that is, membership of the site-admin group).
Tags: Users
accountId- required - The account ID of the user, which uniquely identifies the user across all Atlassian products. For example, 5b10ac8d82e05b22cc7d4ef5.username- optional - This parameter is no longer available. See the deprecation notice for details.key- optional - This parameter is no longer available. See the deprecation notice for details.
Sets the default issue table columns for the user. If an account ID is not passed, the calling user's default columns are set. If no column details are sent, then all default columns are removed.
The parameters for this resource are expressed as HTML form data. For example, in curl:
curl -X PUT -d columns=summary -d columns=description https://your-domain.atlassian.net/rest/api/3/user/columns?accountId=5b10ac8d82e05b22cc7d4ef5'
Permissions required:
- Administer Jira global permission, to set the columns on any user.
- Permission to access Jira, to set the calling user's columns.
Tags: Users
accountId- optional - The account ID of the user, which uniquely identifies the user across all Atlassian products. For example, 5b10ac8d82e05b22cc7d4ef5.
Resets the default issue table columns for the user to the system default. If
accountIdis not passed, the calling user's default columns are reset.
Permissions required:
- Administer Jira global permission, to set the columns on any user.
- Permission to access Jira, to set the calling user's columns.
Tags: Users
accountId- optional - The account ID of the user, which uniquely identifies the user across all Atlassian products. For example, 5b10ac8d82e05b22cc7d4ef5.username- optional - This parameter is no longer available. See the deprecation notice for details.
Returns the value of a user's property. If no property key is provided Get user property keys is called.
Note: This operation does not access the user properties created and maintained in Jira.
Permissions required:
- Administer Jira global permission, to get a property from any user.
- Access to Jira, to get a property from the calling user's record.
Tags: User properties
accountId- optional - The account ID of the user, which uniquely identifies the user across all Atlassian products. For example, 5b10ac8d82e05b22cc7d4ef5.userKey- optional - This parameter is no longer available and will be removed from the documentation soon. See the deprecation notice for details.username- optional - This parameter is no longer available and will be removed from the documentation soon. See the deprecation notice for details.propertyKey- required - The key of the user's property.
Sets the value of a user's property. Use this resource to store custom data against a user.
Note: This operation does not access the user properties created and maintained in Jira.
Permissions required:
- Administer Jira global permission, to set a property on any user.
- Access to Jira, to set a property on the calling user's record.
Tags: User properties
accountId- optional - The account ID of the user, which uniquely identifies the user across all Atlassian products. For example, 5b10ac8d82e05b22cc7d4ef5.userKey- optional - This parameter is no longer available and will be removed from the documentation soon. See the deprecation notice for details.username- optional - This parameter is no longer available and will be removed from the documentation soon. See the deprecation notice for details.propertyKey- required - The key of the user's property. The maximum length is 255 characters.
Deletes a property from a user.
Note: This operation does not access the user properties created and maintained in Jira.
Permissions required:
- Administer Jira global permission, to delete a property from any user.
- Access to Jira, to delete a property from the calling user's record.
Tags: User properties
accountId- optional - The account ID of the user, which uniquely identifies the user across all Atlassian products. For example, 5b10ac8d82e05b22cc7d4ef5.userKey- optional - This parameter is no longer available and will be removed from the documentation soon. See the deprecation notice for details.username- optional - This parameter is no longer available and will be removed from the documentation soon. See the deprecation notice for details.propertyKey- required - The key of the user's property.
Creates a project version.
This operation can be accessed anonymously.
Permissions required: Administer Jira global permission or Administer Projects project permission for the project the version is added to.
Tags: Project versions
Returns a project version.
This operation can be accessed anonymously.
Permissions required: Browse projects project permission for the project containing the version.
Tags: Project versions
id- required - The ID of the version.expand- optional - Use expand to include additional information about version in the response. This parameter accepts a comma-separated list. Expand options include:
* `operations` Returns the list of operations available for this version.
* `issuesstatus` Returns the count of issues in this version for each of the status categories *to do*, *in progress*, *done*, and *unmapped*. The *unmapped* property represents the number of issues with a status other than *to do*, *in progress*, and *done*.
Updates a project version.
This operation can be accessed anonymously.
Permissions required: Administer Jira global permission or Administer Projects project permission for the project that contains the version.
Tags: Project versions
id- required - The ID of the version.
Deletes a project version.
Deprecated, use Delete and replace version that supports swapping version values in custom fields, in addition to the swapping forfixVersionandaffectedVersionprovided in this resource.
Alternative versions can be provided to update issues that use the deleted version infixVersionoraffectedVersion. If alternatives are not provided, occurrences offixVersionandaffectedVersionthat contain the deleted version are cleared.
This operation can be accessed anonymously.
Permissions required: Administer Jira global permission or Administer Projects project permission for the project that contains the version.
Tags: Project versions
id- required - The ID of the version.moveFixIssuesTo- optional - The ID of the version to updatefixVersionto when the field contains the deleted version. The replacement version must be in the same project as the version being deleted and cannot be the version being deleted.moveAffectedIssuesTo- optional - The ID of the version to updateaffectedVersionto when the field contains the deleted version. The replacement version must be in the same project as the version being deleted and cannot be the version being deleted.
Merges two project versions. The merge is completed by deleting the version specified in
idand replacing any occurrences of its ID infixVersionwith the version ID specified inmoveIssuesTo.
Consider using Delete and replace version instead. This resource supports swapping version values infixVersion,affectedVersion, and custom fields.
This operation can be accessed anonymously.
Permissions required: Administer Jira global permission or Administer Projects project permission for the project that contains the version.
Tags: Project versions
id- required - The ID of the version to delete.moveIssuesTo- required - The ID of the version to merge into.
Modifies the version's sequence within the project, which affects the display order of the versions in Jira.
This operation can be accessed anonymously.
Permissions required: Browse projects project permission for the project that contains the version.
Tags: Project versions
id- required - The ID of the version to be moved.
Deletes a project version.
Alternative versions can be provided to update issues that use the deleted version infixVersion,affectedVersion, or any version picker custom fields. If alternatives are not provided, occurrences offixVersion,affectedVersion, and any version picker custom field, that contain the deleted version, are cleared. Any replacement version must be in the same project as the version being deleted and cannot be the version being deleted.
This operation can be accessed anonymously.
Permissions required: Administer Jira global permission or Administer Projects project permission for the project that contains the version.
Tags: Project versions
id- required - The ID of the version.
Registers webhooks.
Permissions required: Only Connect and OAuth 2.0 apps can use this operation.
Tags: Webhooks
Removes webhooks by ID. Only webhooks registered by the calling app are removed. If webhooks created by other apps are specified, they are ignored.
Permissions required: Only Connect and OAuth 2.0 apps can use this operation.
Tags: Webhooks
Webhooks registered through the REST API expire after 30 days. Call this resource periodically to keep them alive.
Unrecognized webhook IDs (those that are not found or belong to other apps) are ignored.
Permissions required: Only Connect and OAuth 2.0 apps can use this operation.
Tags: Webhooks
Creates a workflow. You can define transition rules using the shapes detailed in the following sections. If no transitional rules are specified the default system transition rules are used.
Conditions enable workflow rules that govern whether a transition can execute.
##### Always false condition #####
A condition that always fails.
{
"type": "AlwaysFalseCondition"
}
##### Block transition until approval #####
A condition that blocks issue transition if there is a pending approval.
{
"type": "BlockInProgressApprovalCondition"
}
##### Compare number custom field condition #####
A condition that allows transition if a comparison between a number custom field and a value is true.
{
"type": "CompareNumberCFCondition",
"configuration": {
"comparator": "=",
"fieldId": "customfield_10029",
"fieldValue": 2
}
}
* `comparator` One of the supported comparator: `=`, `>`, and `<`.
* `fieldId` The custom numeric field ID. Allowed field types:
* `com.atlassian.jira.plugin.system.customfieldtypes:float`
* `com.pyxis.greenhopper.jira:jsw-story-points`
* `fieldValue` The value for comparison.
##### Hide from user condition #####
A condition that hides a transition from users. The transition can only be triggered from a workflow function or REST API operation.
{
"type": "RemoteOnlyCondition"
}
##### Only assignee condition #####
A condition that allows only the assignee to execute a transition.
{
"type": "AllowOnlyAssignee"
}
##### Only Bamboo notifications workflow condition #####
A condition that makes the transition available only to Bamboo build notifications.
{
"type": "OnlyBambooNotificationsCondition"
}
##### Only reporter condition #####
A condition that allows only the reporter to execute a transition.
{
"type": "AllowOnlyReporter"
}
##### Permission condition #####
A condition that allows only users with a permission to execute a transition.
{
"type": "PermissionCondition",
"configuration": {
"permissionKey": "BROWSE_PROJECTS"
}
}
* `permissionKey` The permission required to perform the transition. Allowed values: [built-in](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-permission-schemes/#built-in-permissions) or app defined permissions.
##### Previous status condition #####
A condition that allows a transition based on whether an issue has or has not transitioned through a status.
{
"type": "PreviousStatusCondition",
"configuration": {
"ignoreLoopTransitions": true,
"includeCurrentStatus": true,
"mostRecentStatusOnly": true,
"reverseCondition": true,
"previousStatus": {
"id": "5"
}
}
}
By default this condition allows the transition if the status, as defined by its ID in the `previousStatus` object, matches any previous issue status, unless:
* `ignoreLoopTransitions` is `true`, then loop transitions (from and to the same status) are ignored.
* `includeCurrentStatus` is `true`, then the current issue status is also checked.
* `mostRecentStatusOnly` is `true`, then only the issue's preceding status (the one immediately before the current status) is checked.
* `reverseCondition` is `true`, then the status must not be present.
##### Separation of duties condition #####
A condition that prevents a user to perform the transition, if the user has already performed a transition on the issue.
{
"type": "SeparationOfDutiesCondition",
"configuration": {
"fromStatus": {
"id": "5"
},
"toStatus": {
"id": "6"
}
}
}
* `fromStatus` OPTIONAL. An object containing the ID of the source status of the transition that is blocked. If omitted any transition to `toStatus` is blocked.
* `toStatus` An object containing the ID of the target status of the transition that is blocked.
##### Subtask blocking condition #####
A condition that blocks transition on a parent issue if any of its subtasks are in any of one or more statuses.
{
"type": "SubTaskBlockingCondition",
"configuration": {
"statuses": [
{
"id": "1"
},
{
"id": "3"
}
]
}
}
* `statuses` A list of objects containing status IDs.
##### User is in any group condition #####
A condition that allows users belonging to any group from a list of groups to execute a transition.
{
"type": "UserInAnyGroupCondition",
"configuration": {
"groups": [
"administrators",
"atlassian-addons-admin"
]
}
}
* `groups` A list of group names.
##### User is in any project role condition #####
A condition that allows only users with at least one project roles from a list of project roles to execute a transition.
{
"type": "InAnyProjectRoleCondition",
"configuration": {
"projectRoles": [
{
"id": "10002"
},
{
"id": "10003"
},
{
"id": "10012"
},
{
"id": "10013"
}
]
}
}
* `projectRoles` A list of objects containing project role IDs.
##### User is in custom field condition #####
A condition that allows only users listed in a given custom field to execute the transition.
{
"type": "UserIsInCustomFieldCondition",
"configuration": {
"allowUserInField": false,
"fieldId": "customfield_10010"
}
}
* `allowUserInField` If `true` only a user who is listed in `fieldId` can perform the transition, otherwise, only a user who is not listed in `fieldId` can perform the transition.
* `fieldId` The ID of the field containing the list of users.
##### User is in group condition #####
A condition that allows users belonging to a group to execute a transition.
{
"type": "UserInGroupCondition",
"configuration": {
"group": "administrators",
}
}
* `group` The name of the group.
##### User is in group custom field condition #####
A condition that allows users belonging to a group specified in a custom field to execute a transition.
{
"type": "InGroupCFCondition",
"configuration": {
"fieldId": "customfield_10012",
}
}
* `fieldId` The ID of the field. Allowed field types:
* `com.atlassian.jira.plugin.system.customfieldtypes:multigrouppicker`
* `com.atlassian.jira.plugin.system.customfieldtypes:grouppicker`
* `com.atlassian.jira.plugin.system.customfieldtypes:select`
* `com.atlassian.jira.plugin.system.customfieldtypes:multiselect`
* `com.atlassian.jira.plugin.system.customfieldtypes:radiobuttons`
* `com.atlassian.jira.plugin.system.customfieldtypes:multicheckboxes`
* `com.pyxis.greenhopper.jira:gh-epic-status`
##### User is in project role condition #####
A condition that allows users with a project role to execute a transition.
{
"type": "InProjectRoleCondition",
"configuration": {
"projectRole": {
"id": "10002"
}
}
}
* `projectRole` An object containing the ID of a project role.
##### Value field condition #####
A conditions that allows a transition to execute if the value of a field is equal to a constant value or simply set.
{
"type": "ValueFieldCondition",
"configuration": {
"fieldId": "assignee",
"fieldValue": "qm:6e1ecee6-8e64-4db6-8c85-916bb3275f51:54b56885-2bd2-4381-8239-78263442520f",
"comparisonType": "NUMBER",
"comparator": "="
}
}
* `fieldId` The ID of a field used in the comparison.
* `fieldValue` The expected value of the field.
* `comparisonType` The type of the comparison. Allowed values: `STRING`, `NUMBER`, `DATE`, `DATE_WITHOUT_TIME`, or `OPTIONID`.
* `comparator` One of the supported comparator: `>`, `>=`, `=`, `<=`, `<`, `!=`.
**Notes:**
* If you choose the comparison type `STRING`, only `=` and `!=` are valid options.
* You may leave `fieldValue` empty when comparison type is `!=` to indicate that a value is required in the field.
* For date fields without time format values as `yyyy-MM-dd`, and for those with time as `yyyy-MM-dd HH:mm`. For example, for July 16 2021 use `2021-07-16`, for 8:05 AM use `2021-07-16 08:05`, and for 4 PM: `2021-07-16 16:00`.
#### Validators ####
Validators check that any input made to the transition is valid before the transition is performed.
##### Date field validator #####
A validator that compares two dates.
{
"type": "DateFieldValidator",
"configuration": {
"comparator": ">",
"date1": "updated",
"date2": "created",
"expression": "1d",
"includeTime": true
}
}
* `comparator` One of the supported comparator: `>`, `>=`, `=`, `<=`, `<`, or `!=`.
* `date1` The date field to validate. Allowed field types:
* `com.atlassian.jira.plugin.system.customfieldtypes:datepicker`
* `com.atlassian.jira.plugin.system.customfieldtypes:datetime`
* `com.atlassian.jpo:jpo-custom-field-baseline-end`
* `com.atlassian.jpo:jpo-custom-field-baseline-start`
* `duedate`
* `created`
* `updated`
* `Resolved`
* `date2` The second date field. Required, if `expression` is not passed. Allowed field types:
* `com.atlassian.jira.plugin.system.customfieldtypes:datepicker`
* `com.atlassian.jira.plugin.system.customfieldtypes:datetime`
* `com.atlassian.jpo:jpo-custom-field-baseline-end`
* `com.atlassian.jpo:jpo-custom-field-baseline-start`
* `duedate`
* `created`
* `updated`
* `Resolved`
* `expression` An expression specifying an offset. Required, if `date2` is not passed. Offsets are built with a number, with `-` as prefix for the past, and one of these time units: `d` for day, `w` for week, `m` for month, or `y` for year. For example, -2d means two days into the past and 1w means one week into the future. The `now` keyword enables a comparison with the current date.
* `includeTime` If `true`, then the time part of the data is included for the comparison. If the field doesn't have a time part, 00:00:00 is used.
##### Windows date validator #####
A validator that checks that a date falls on or after a reference date and before or on the reference date plus a number of days.
{
"type": "WindowsDateValidator",
"configuration": {
"date1": "customfield_10009",
"date2": "created",
"windowsDays": 5
}
}
* `date1` The date field to validate. Allowed field types:
* `com.atlassian.jira.plugin.system.customfieldtypes:datepicker`
* `com.atlassian.jira.plugin.system.customfieldtypes:datetime`
* `com.atlassian.jpo:jpo-custom-field-baseline-end`
* `com.atlassian.jpo:jpo-custom-field-baseline-start`
* `duedate`
* `created`
* `updated`
* `Resolved`
* `date2` The reference date. Allowed field types:
* `com.atlassian.jira.plugin.system.customfieldtypes:datepicker`
* `com.atlassian.jira.plugin.system.customfieldtypes:datetime`
* `com.atlassian.jpo:jpo-custom-field-baseline-end`
* `com.atlassian.jpo:jpo-custom-field-baseline-start`
* `duedate`
* `created`
* `updated`
* `Resolved`
* `windowsDays` A positive integer indicating a number of days.
##### Field required validator #####
A validator that checks fields are not empty. By default, if a field is not included in the current context it's ignored and not validated.
{
"type": "FieldRequiredValidator",
"configuration": {
"ignoreContext": true,
"errorMessage": "Hey",
"fieldIds": [
"versions",
"customfield_10037",
"customfield_10003"
]
}
}
* `ignoreContext` If `true`, then the context is ignored and all the fields are validated.
* `errorMessage` OPTIONAL. The error message displayed when one or more fields are empty. A default error message is shown if an error message is not provided.
* `fieldIds` The list of fields to validate.
##### Field changed validator #####
A validator that checks that a field value is changed. However, this validation can be ignored for users from a list of groups.
{
"type": "FieldChangedValidator",
"configuration": {
"fieldId": "comment",
"errorMessage": "Hey",
"exemptedGroups": [
"administrators",
"atlassian-addons-admin"
]
}
}
* `fieldId` The ID of a field.
* `errorMessage` OPTIONAL. The error message displayed if the field is not changed. A default error message is shown if the error message is not provided.
* `exemptedGroups` OPTIONAL. The list of groups.
##### Field has single value validator #####
A validator that checks that a multi-select field has only one value. Optionally, the validation can ignore values copied from subtasks.
{
"type": "FieldHasSingleValueValidator",
"configuration": {
"fieldId": "attachment,
"excludeSubtasks": true
}
}
* `fieldId` The ID of a field.
* `excludeSubtasks` If `true`, then values copied from subtasks are ignored.
##### Parent status validator #####
A validator that checks the status of the parent issue of a subtask. If the issue is not a subtask, no validation is performed.
{
"type": "ParentStatusValidator",
"configuration": {
"parentStatuses": [
{
"id":"1"
},
{
"id":"2"
}
]
}
}
* `parentStatus` The list of required parent issue statuses.
##### Permission validator #####
A validator that checks the user has a permission.
{
"type": "PermissionValidator",
"configuration": {
"permissionKey": "ADMINISTER_PROJECTS"
}
}
* `permissionKey` The permission required to perform the transition. Allowed values: [built-in](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-permission-schemes/#built-in-permissions) or app defined permissions.
##### Previous status validator #####
A validator that checks if the issue has held a status.
{
"type": "PreviousStatusValidator",
"configuration": {
"mostRecentStatusOnly": false,
"previousStatus": {
"id": "15"
}
}
}
* `mostRecentStatusOnly` If `true`, then only the issue's preceding status (the one immediately before the current status) is checked.
* `previousStatus` An object containing the ID of an issue status.
##### Regular expression validator #####
A validator that checks the content of a field against a regular expression.
{
"type": "RegexpFieldValidator",
"configuration": {
"regExp": "[0-9]",
"fieldId": "customfield_10029"
}
}
* `regExp`A regular expression.
* `fieldId` The ID of a field. Allowed field types:
* `com.atlassian.jira.plugin.system.customfieldtypes:select`
* `com.atlassian.jira.plugin.system.customfieldtypes:multiselect`
* `com.atlassian.jira.plugin.system.customfieldtypes:radiobuttons`
* `com.atlassian.jira.plugin.system.customfieldtypes:multicheckboxes`
* `com.atlassian.jira.plugin.system.customfieldtypes:textarea`
* `com.atlassian.jira.plugin.system.customfieldtypes:textfield`
* `com.atlassian.jira.plugin.system.customfieldtypes:url`
* `com.atlassian.jira.plugin.system.customfieldtypes:float`
* `com.pyxis.greenhopper.jira:jsw-story-points`
* `com.pyxis.greenhopper.jira:gh-epic-status`
* `description`
* `summary`
##### User permission validator #####
A validator that checks if a user has a permission. Obsolete. You may encounter this validator when getting transition rules and can pass it when updating or creating rules, for example, when you want to duplicate the rules from a workflow on a new workflow.
{
"type": "UserPermissionValidator",
"configuration": {
"permissionKey": "BROWSE_PROJECTS",
"nullAllowed": false,
"username": "TestUser"
}
}
* `permissionKey` The permission to be validated. Allowed values: [built-in](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-permission-schemes/#built-in-permissions) or app defined permissions.
* `nullAllowed` If `true`, allows the transition when `username` is empty.
* `username` The username to validate against the `permissionKey`.
#### Post functions ####
Post functions carry out any additional processing required after a Jira workflow transition is executed.
##### Fire issue event function #####
A post function that fires an event that is processed by the listeners.
{
"type": "FireIssueEventFunction",
"configuration": {
"event": {
"id":"1"
}
}
}
**Note:** If provided, this post function overrides the default `FireIssueEventFunction`. Can be included once in a transition.
* `event` An object containing the ID of the issue event.
##### Update issue status #####
A post function that sets issue status to the linked status of the destination workflow status.
{
"type": "UpdateIssueStatusFunction"
}
**Note:** This post function is a default function in global and directed transitions. It can only be added to the initial transition and can only be added once.
##### Create comment #####
A post function that adds a comment entered during the transition to an issue.
{
"type": "CreateCommentFunction"
}
**Note:** This post function is a default function in global and directed transitions. It can only be added to the initial transition and can only be added once.
##### Store issue #####
A post function that stores updates to an issue.
{
"type": "IssueStoreFunction"
}
**Note:** This post function can only be added to the initial transition and can only be added once.
##### Assign to current user function #####
A post function that assigns the issue to the current user if the current user has the `ASSIGNABLE_USER` permission.
{
"type": "AssignToCurrentUserFunction"
}
**Note:** This post function can be included once in a transition.
##### Assign to lead function #####
A post function that assigns the issue to the project or component lead developer.
{
"type": "AssignToLeadFunction"
}
**Note:** This post function can be included once in a transition.
##### Assign to reporter function #####
A post function that assigns the issue to the reporter.
{
"type": "AssignToReporterFunction"
}
**Note:** This post function can be included once in a transition.
##### Clear field value function #####
A post function that clears the value from a field.
{
"type": "ClearFieldValuePostFunction",
"configuration": {
"fieldId": "assignee"
}
}
* `fieldId` The ID of the field.
##### Copy value from other field function #####
A post function that copies the value of one field to another, either within an issue or from parent to subtask.
{
"type": "CopyValueFromOtherFieldPostFunction",
"configuration": {
"sourceFieldId": "assignee",
"destinationFieldId": "creator",
"copyType": "same"
}
}
* `sourceFieldId` The ID of the source field.
* `destinationFieldId` The ID of the destination field.
* `copyType` Use `same` to copy the value from a field inside the issue, or `parent` to copy the value from the parent issue.
##### Create Crucible review workflow function #####
A post function that creates a Crucible review for all unreviewed code for the issue.
{
"type": "CreateCrucibleReviewWorkflowFunction"
}
**Note:** This post function can be included once in a transition.
##### Set issue security level based on user's project role function #####
A post function that sets the issue's security level if the current user has a project role.
{
"type": "SetIssueSecurityFromRoleFunction",
"configuration": {
"projectRole": {
"id":"10002"
},
"issueSecurityLevel": {
"id":"10000"
}
}
}
* `projectRole` An object containing the ID of the project role.
* `issueSecurityLevel` OPTIONAL. The object containing the ID of the security level. If not passed, then the security level is set to `none`.
##### Trigger a webhook function #####
A post function that triggers a webhook.
{
"type": "TriggerWebhookFunction",
"configuration": {
"webhook": {
"id": "1"
}
}
}
* `webhook` An object containing the ID of the webhook listener to trigger.
##### Update issue custom field function #####
A post function that updates the content of an issue custom field.
{
"type": "UpdateIssueCustomFieldPostFunction",
"configuration": {
"mode": "append",
"fieldId": "customfield_10003",
"fieldValue": "yikes"
}
}
* `mode` Use `replace` to override the field content with `fieldValue` or `append` to add `fieldValue` to the end of the field content.
* `fieldId` The ID of the field.
* `fieldValue` The update content.
##### Update issue field function #####
A post function that updates a simple issue field.
{
"type": "UpdateIssueFieldFunction",
"configuration": {
"fieldId": "assignee",
"fieldValue": "5f0c277e70b8a90025a00776",
}
}
* `fieldId` The ID of the field. Allowed field types:
* `assignee`
* `description`
* `environment`
* `priority`
* `resolution`
* `summary`
* `timeoriginalestimate`
* `timeestimate`
* `timespent`
* `fieldValue` The update value.
* If the `fieldId` is `assignee`, the `fieldValue` should be one of these values:
* an account ID.
* `automatic`.
* a blank string, which sets the value to `unassigned`.
#### Connect rules ####
Connect rules are conditions, validators, and post functions of a transition that are registered by Connect apps. To create a rule registered by the app, the app must be enabled and the rule's module must exist.
{
"type": "appKey__moduleKey",
"configuration": {
"value":"{\"isValid\":\"true\"}"
}
}
* `type` A Connect rule key in a form of `appKey__moduleKey`.
* `value` The stringified JSON configuration of a Connect rule.
**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
Tags: Workflows
Updates configuration of workflow transition rules. The following rule types are supported:
Only rules created by the calling Connect app can be updated.
To assist with app migration, this operation can be used to:
* Disable a rule.
* Add a `tag`. Use this to filter rules in the [Get workflow transition rule configurations](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-workflow-transition-rules/#api-rest-api-3-workflow-rule-config-get).
Rules are enabled if the `disabled` parameter is not provided.
**[Permissions](#permissions) required:** Only Connect apps can use this operation.
Tags: Workflow transition rules
Deletes workflow transition rules from one or more workflows. These rule types are supported:
Only rules created by the calling Connect app can be deleted.
**[Permissions](#permissions) required:** Only Connect apps can use this operation.
Tags: Workflow transition rules
Updates a workflow transition by changing the property value. Trying to update a property that does not exist results in a new property being added to the transition. Transition properties are used to change the behavior of a transition. For more information, see Transition properties and Workflow properties.
Permissions required: Administer Jira global permission.
Tags: Workflow transition properties
transitionId- required - The ID of the transition. To get the ID, view the workflow in text mode in the Jira admin settings. The ID is shown next to the transition.key- required - The key of the property being updated, also known as the name of the property. Set this to the same value as thekeydefined in the request body.workflowName- required - The name of the workflow that the transition belongs to.workflowMode- optional - The workflow status. Set tolivefor inactive workflows ordraftfor draft workflows. Active workflows cannot be edited.
Possible values: live, draft.
Adds a property to a workflow transition. Transition properties are used to change the behavior of a transition. For more information, see Transition properties and Workflow properties.
Permissions required: Administer Jira global permission.
Tags: Workflow transition properties
transitionId- required - The ID of the transition. To get the ID, view the workflow in text mode in the Jira admin settings. The ID is shown next to the transition.key- required - The key of the property being added, also known as the name of the property. Set this to the same value as thekeydefined in the request body.workflowName- required - The name of the workflow that the transition belongs to.workflowMode- optional - The workflow status. Set to live for inactive workflows or draft for draft workflows. Active workflows cannot be edited.
Possible values: live, draft.
Deletes a property from a workflow transition. Transition properties are used to change the behavior of a transition. For more information, see Transition properties and Workflow properties.
Permissions required: Administer Jira global permission.
Tags: Workflow transition properties
transitionId- required - The ID of the transition. To get the ID, view the workflow in text mode in the Jira admin settings. The ID is shown next to the transition.key- required - The name of the transition property to delete, also known as the name of the property.workflowName- required - The name of the workflow that the transition belongs to.workflowMode- optional - The workflow status. Set tolivefor inactive workflows ordraftfor draft workflows. Active workflows cannot be edited.
Possible values: live, draft.
Deletes a workflow.
The workflow cannot be deleted if it is:
- an active workflow.
- a system workflow.
- associated with any workflow scheme.
- associated with any draft workflow scheme.
**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
Tags: Workflows
entityId- required - The entity ID of the workflow.
Creates a workflow scheme.
Permissions required: Administer Jira global permission.
Tags: Workflow schemes
Assigns a workflow scheme to a project. This operation is performed only when there are no issues in the project.
Workflow schemes can only be assigned to classic projects.
Permissions required: Administer Jira global permission.
Tags: Workflow scheme project associations
Returns a workflow scheme.
Permissions required: Administer Jira global permission.
Tags: Workflow schemes
id- required - The ID of the workflow scheme. Find this ID by editing the desired workflow scheme in Jira. The ID is shown in the URL asschemeId. For example, schemeId=10301.returnDraftIfExists- optional - Returns the workflow scheme's draft rather than scheme itself, if set to true. If the workflow scheme does not have a draft, then the workflow scheme is returned.
Updates a workflow scheme, including the name, default workflow, issue type to project mappings, and more. If the workflow scheme is active (that is, being used by at least one project), then a draft workflow scheme is created or updated instead, provided that
updateDraftIfNeededis set totrue.
Permissions required: Administer Jira global permission.
Tags: Workflow schemes
id- required - The ID of the workflow scheme. Find this ID by editing the desired workflow scheme in Jira. The ID is shown in the URL asschemeId. For example, schemeId=10301.
Deletes a workflow scheme. Note that a workflow scheme cannot be deleted if it is active (that is, being used by at least one project).
Permissions required: Administer Jira global permission.
Tags: Workflow schemes
id- required - The ID of the workflow scheme. Find this ID by editing the desired workflow scheme in Jira. The ID is shown in the URL asschemeId. For example, schemeId=10301.
Create a draft workflow scheme from an active workflow scheme, by copying the active workflow scheme. Note that an active workflow scheme can only have one draft workflow scheme.
Permissions required: Administer Jira global permission.
Tags: Workflow scheme drafts
id- required - The ID of the active workflow scheme that the draft is created from.
Sets the default workflow for a workflow scheme.
Note that active workflow schemes cannot be edited. If the workflow scheme is active, setupdateDraftIfNeededtotruein the request object and a draft workflow scheme is created or updated with the new default workflow. The draft workflow scheme can be published in Jira.
Permissions required: Administer Jira global permission.
Tags: Workflow schemes
id- required - The ID of the workflow scheme.
Resets the default workflow for a workflow scheme. That is, the default workflow is set to Jira's system workflow (the jira workflow).
Note that active workflow schemes cannot be edited. If the workflow scheme is active, setupdateDraftIfNeededtotrueand a draft workflow scheme is created or updated with the default workflow reset. The draft workflow scheme can be published in Jira.
Permissions required: Administer Jira global permission.
Tags: Workflow schemes
id- required - The ID of the workflow scheme.updateDraftIfNeeded- optional - Set to true to create or update the draft of a workflow scheme and delete the mapping from the draft, when the workflow scheme cannot be edited. Defaults tofalse.
Updates a draft workflow scheme. If a draft workflow scheme does not exist for the active workflow scheme, then a draft is created. Note that an active workflow scheme can only have one draft workflow scheme.
Permissions required: Administer Jira global permission.
Tags: Workflow scheme drafts
id- required - The ID of the active workflow scheme that the draft was created from.
Deletes a draft workflow scheme.
Permissions required: Administer Jira global permission.
Tags: Workflow scheme drafts
id- required - The ID of the active workflow scheme that the draft was created from.
Sets the default workflow for a workflow scheme's draft.
Permissions required: Administer Jira global permission.
Tags: Workflow scheme drafts
id- required - The ID of the workflow scheme that the draft belongs to.
Resets the default workflow for a workflow scheme's draft. That is, the default workflow is set to Jira's system workflow (the jira workflow).
Permissions required: Administer Jira global permission.
Tags: Workflow scheme drafts
id- required - The ID of the workflow scheme that the draft belongs to.
Returns the issue type-workflow mapping for an issue type in a workflow scheme's draft.
Permissions required: Administer Jira global permission.
Tags: Workflow scheme drafts
id- required - The ID of the workflow scheme that the draft belongs to.issueType- required - The ID of the issue type.
Sets the workflow for an issue type in a workflow scheme's draft.
Permissions required: Administer Jira global permission.
Tags: Workflow scheme drafts
id- required - The ID of the workflow scheme that the draft belongs to.issueType- required - The ID of the issue type.
Deletes the issue type-workflow mapping for an issue type in a workflow scheme's draft.
Permissions required: Administer Jira global permission.
Tags: Workflow scheme drafts
id- required - The ID of the workflow scheme that the draft belongs to.issueType- required - The ID of the issue type.
Publishes a draft workflow scheme.
Where the draft workflow includes new workflow statuses for an issue type, mappings are provided to update issues with the original workflow status to the new workflow status.
This operation is asynchronous. Follow thelocationlink in the response to determine the status of the task and use Get task to obtain updates.
Permissions required: Administer Jira global permission.
Tags: Workflow scheme drafts
id- required - The ID of the workflow scheme that the draft belongs to.validateOnly- optional - Whether the request only performs a validation.
Sets the issue types for a workflow in a workflow scheme's draft. The workflow can also be set as the default workflow for the draft workflow scheme. Unmapped issues types are mapped to the default workflow.
Permissions required: Administer Jira global permission.
Tags: Workflow scheme drafts
id- required - The ID of the workflow scheme that the draft belongs to.workflowName- required - The name of the workflow.
Deletes the workflow-issue type mapping for a workflow in a workflow scheme's draft.
Permissions required: Administer Jira global permission.
Tags: Workflow scheme drafts
id- required - The ID of the workflow scheme that the draft belongs to.workflowName- required - The name of the workflow.
Returns the issue type-workflow mapping for an issue type in a workflow scheme.
Permissions required: Administer Jira global permission.
Tags: Workflow schemes
id- required - The ID of the workflow scheme.issueType- required - The ID of the issue type.returnDraftIfExists- optional - Returns the mapping from the workflow scheme's draft rather than the workflow scheme, if set to true. If no draft exists, the mapping from the workflow scheme is returned.
Sets the workflow for an issue type in a workflow scheme.
Note that active workflow schemes cannot be edited. If the workflow scheme is active, setupdateDraftIfNeededtotruein the request body and a draft workflow scheme is created or updated with the new issue type-workflow mapping. The draft workflow scheme can be published in Jira.
Permissions required: Administer Jira global permission.
Tags: Workflow schemes
id- required - The ID of the workflow scheme.issueType- required - The ID of the issue type.
Deletes the issue type-workflow mapping for an issue type in a workflow scheme.
Note that active workflow schemes cannot be edited. If the workflow scheme is active, setupdateDraftIfNeededtotrueand a draft workflow scheme is created or updated with the issue type-workflow mapping deleted. The draft workflow scheme can be published in Jira.
Permissions required: Administer Jira global permission.
Tags: Workflow schemes
id- required - The ID of the workflow scheme.issueType- required - The ID of the issue type.updateDraftIfNeeded- optional - Set to true to create or update the draft of a workflow scheme and update the mapping in the draft, when the workflow scheme cannot be edited. Defaults tofalse.
Sets the issue types for a workflow in a workflow scheme. The workflow can also be set as the default workflow for the workflow scheme. Unmapped issues types are mapped to the default workflow.
Note that active workflow schemes cannot be edited. If the workflow scheme is active, setupdateDraftIfNeededtotruein the request body and a draft workflow scheme is created or updated with the new workflow-issue types mappings. The draft workflow scheme can be published in Jira.
Permissions required: Administer Jira global permission.
Tags: Workflow schemes
id- required - The ID of the workflow scheme.workflowName- required - The name of the workflow.
Deletes the workflow-issue type mapping for a workflow in a workflow scheme.
Note that active workflow schemes cannot be edited. If the workflow scheme is active, setupdateDraftIfNeededtotrueand a draft workflow scheme is created or updated with the workflow-issue type mapping deleted. The draft workflow scheme can be published in Jira.
Permissions required: Administer Jira global permission.
Tags: Workflow schemes
id- required - The ID of the workflow scheme.workflowName- required - The name of the workflow.updateDraftIfNeeded- optional - Set to true to create or update the draft of a workflow scheme and delete the mapping from the draft, when the workflow scheme cannot be edited. Defaults tofalse.
Returns worklog details for a list of worklog IDs.
The returned list of worklogs is limited to 1000 items.
Permissions required: Permission to access Jira, however, worklogs are only returned where either of the following is true:
- the worklog is set as Viewable by All Users.
- the user is a member of a project role or group with permission to view the worklog.
Tags: Issue worklogs
expand- optional - Use expand to include additional information about worklogs in the response. This parameter acceptspropertiesthat returns the properties of each worklog.
Returns the key and value of an app's property.
Permissions required: Only a Connect app whose key matchesaddonKeycan make this request.
Tags: App properties
addonKey- required - The key of the app, as defined in its descriptor.propertyKey- required - The key of the property.
Sets the value of an app's property. Use this resource to store custom data for your app.
The value of the request body must be a valid, non-empty JSON blob. The maximum length is 32768 characters.
Permissions required: Only a Connect app whose key matchesaddonKeycan make this request.
Tags: App properties
addonKey- required - The key of the app, as defined in its descriptor.propertyKey- required - The key of the property.
Deletes an app's property.
Permissions required: Only a Connect app whose key matchesaddonKeycan make this request.
Tags: App properties
addonKey- required - The key of the app, as defined in its descriptor.propertyKey- required - The key of the property.
Registers a list of modules.
Permissions required: Only Connect apps can make this request.
Tags: Dynamic modules
Remove all or a list of modules registered by the calling app.
Permissions required: Only Connect apps can make this request.
Tags: Dynamic modules
moduleKey- optional - The key of the module to remove. To include multiple module keys, provide multiple copies of this parameter.
For example,moduleKey=dynamic-attachment-entity-property&moduleKey=dynamic-select-field.
Nonexistent keys are ignored.
Updates the value of a custom field added by Connect apps on one or more issues.
The values of up to 200 custom fields can be updated.
Permissions required: Only Connect apps can make this request.
Tags: App migration
Atlassian-Transfer-Id- required - The ID of the transfer.Atlassian-Account-Id- required - The Atlassian account ID of the impersonated user. This user must be a member of the site admin group.
Updates the values of multiple entity properties for an object, up to 50 updates per request. This operation is for use by Connect apps during app migration.
Tags: App migration
Atlassian-Transfer-Id- required - The app migration transfer ID.Atlassian-Account-Id- required - The Atlassian account ID of the impersonated user. This user must be a member of the site admin group.entityType- required - The type indicating the object that contains the entity properties.
Possible values: IssueProperty, CommentProperty, DashboardItemProperty, IssueTypeProperty, ProjectProperty, UserProperty, WorklogProperty, BoardProperty, SprintProperty.
Returns configurations for workflow transition rules migrated from server to cloud and owned by the calling Connect app.
Tags: App migration
Atlassian-Transfer-Id- required - The app migration transfer ID.
: jira-component
All files of this connector are licensed under the Apache 2.0 License. For details see the file LICENSE on the toplevel directory.