Atlassian Jira Workflow API
The Atlassian Jira Workflow API enables managing workflows, transitions, and workflow rules within Jira.
OpenAPI Specification
components:
schemas:
PageBeanWorkflowTransitionRules:
additionalProperties: false
description: A page of items.
properties:
isLast:
description: Whether this is the last page.
readOnly: true
type: boolean
maxResults:
description: The maximum number of items that could be returned.
format: int32
readOnly: true
type: integer
nextPage:
description: If there is another page of results, the URL of the next page.
format: uri
readOnly: true
type: string
self:
description: The URL of the page.
format: uri
readOnly: true
type: string
startAt:
description: The index of the first item returned.
format: int64
readOnly: true
type: integer
total:
description: The number of items returned.
format: int64
readOnly: true
type: integer
values:
description: The list of items.
items:
$ref: '#/components/schemas/WorkflowTransitionRules'
readOnly: true
type: array
type: object
WorkflowTransitionRulesUpdateErrors:
additionalProperties: false
description: >-
Details of any errors encountered while updating workflow transition
rules.
properties:
updateResults:
description: A list of workflows.
items:
$ref: '#/components/schemas/WorkflowTransitionRulesUpdateErrorDetails'
type: array
required:
- updateResults
type: object
PageBeanWorkflow:
additionalProperties: false
description: A page of items.
properties:
isLast:
description: Whether this is the last page.
readOnly: true
type: boolean
maxResults:
description: The maximum number of items that could be returned.
format: int32
readOnly: true
type: integer
nextPage:
description: If there is another page of results, the URL of the next page.
format: uri
readOnly: true
type: string
self:
description: The URL of the page.
format: uri
readOnly: true
type: string
startAt:
description: The index of the first item returned.
format: int64
readOnly: true
type: integer
total:
description: The number of items returned.
format: int64
readOnly: true
type: integer
values:
description: The list of items.
items:
$ref: '#/components/schemas/Workflow'
readOnly: true
type: array
type: object
WorkflowTransitionProperty:
additionalProperties: true
description: Details about the server Jira is running on.
properties:
id:
description: The ID of the transition property.
readOnly: true
type: string
key:
description: >-
The key of the transition property. Also known as the name of the
transition property.
readOnly: true
type: string
value:
description: The value of the transition property.
type: string
required:
- value
type: object
externalDocs:
description: Find out more about Atlassian products and services.
url: http://www.atlassian.com
info:
contact:
email: [email protected]
description: Needs description.
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
termsOfService: http://atlassian.com/terms/
title: 'Atlassian rest/api/3/workflow/'
version: 1001.0.0-SNAPSHOT-67b5c6e5f3598d7ec1649016d026468ab2838a77
openapi: 3.0.1
paths:
/rest/api/3/workflow/rule/config:
get:
deprecated: false
description: >-
Returns a [paginated](#pagination) list of workflows with transition
rules. The workflows can be filtered to return only those containing
workflow transition rules:<br><br> * of one or more transition rule
types, such as [workflow post
functions](https://developer.atlassian.com/cloud/jira/platform/modules/workflow-post-function/).<br>
* matching one or more transition rule keys.<br><br>Only workflows
containing transition rules created by the calling
[Connect](https://developer.atlassian.com/cloud/jira/platform/index/#connect-apps)
or
[Forge](https://developer.atlassian.com/cloud/jira/platform/index/#forge-apps)
app are returned.<br><br>Due to server-side optimizations, workflows
with an empty list of rules may be returned; these workflows can be
ignored.<br><br>**[Permissions](#permissions) required:** Only
[Connect](https://developer.atlassian.com/cloud/jira/platform/index/#connect-apps)
or
[Forge](https://developer.atlassian.com/cloud/jira/platform/index/#forge-apps)
apps can use this operation.
operationId: atlassianGetworkflowtransitionruleconfigurations
parameters:
- description: >-
The index of the first item to return in a page of results (page
offset).
in: query
name: startAt
schema:
default: 0
format: int64
type: integer
- description: The maximum number of items to return per page.
in: query
name: maxResults
schema:
default: 10
format: int32
maximum: 50
type: integer
- description: The types of the transition rules to return.
in: query
name: types
required: true
schema:
items:
default: ''
enum:
- postfunction
- condition
- validator
type: string
type: array
uniqueItems: true
- description: >-
The transition rule class keys, as defined in the Connect or the
Forge app descriptor, of the transition rules to return.
in: query
name: keys
schema:
items:
default: ''
type: string
type: array
uniqueItems: true
- description: The list of workflow names to filter by.
in: query
name: workflowNames
schema:
items:
default: ''
maxLength: 50
type: string
maxLength: 50
type: array
uniqueItems: true
- description: The list of `tags` to filter by.
in: query
name: withTags
schema:
items:
default: ''
maxLength: 20
type: string
maxLength: 20
type: array
uniqueItems: true
- description: >-
Whether draft or published workflows are returned. If not provided,
both workflow types are returned.
in: query
name: draft
schema:
type: boolean
- description: >-
Use [expand](#expansion) to include additional information in the
response. This parameter accepts `transition`, which, for each rule,
returns information about the transition the rule is assigned to.
in: query
name: expand
schema:
type: string
responses:
'200':
content:
application/json:
example: >-
{"isLast":true,"maxResults":10,"startAt":0,"total":1,"values":[{"workflowId":{"name":"My
Workflow
name","draft":false},"postFunctions":[{"id":"b4d6cbdc-59f5-11e9-8647-d663bd873d93","key":"postfunction-key","configuration":{"value":"{
\"color\": \"red\" }","disabled":false,"tag":"Sample
tag"},"transition":{"id":1,"name":"Open"}}],"conditions":[{"id":"d663bd873d93-59f5-11e9-8647-b4d6cbdc","key":"condition-key","configuration":{"value":"{
\"size\": \"medium\" }","disabled":false,"tag":"Another
tag"},"transition":{"id":1,"name":"Open"}}],"validators":[{"id":"11e9-59f5-b4d6cbdc-8647-d663bd873d93","key":"validator-key","configuration":{"value":"\"{
\\\"shape\\\": \\\"square\\\"
}\"","disabled":false},"transition":{"id":1,"name":"Open"}}]}]}
schema:
$ref: '#/components/schemas/PageBeanWorkflowTransitionRules'
description: Returned if the request is successful.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the request is invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the caller is not a Connect or Forge app.
'404':
description: Returned if any transition rule type is not supported.
'503':
description: >-
Returned if we encounter a problem while trying to access the
required data.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Get Workflow Transition Rule Configurations
tags:
- Workflow Transition Rules
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-configuration
state: Current
- scheme: OAuth2
scopes:
- read:workflow:jira
state: Beta
x-atlassian-connect-scope: READ
put:
deprecated: false
description: >-
Updates configuration of workflow transition rules. The following rule
types are supported:<br><br> * [post
functions](https://developer.atlassian.com/cloud/jira/platform/modules/workflow-post-function/)<br>
* [conditions](https://developer.atlassian.com/cloud/jira/platform/modules/workflow-condition/)<br>
* [validators](https://developer.atlassian.com/cloud/jira/platform/modules/workflow-validator/)<br><br>Only
rules created by the calling
[Connect](https://developer.atlassian.com/cloud/jira/platform/index/#connect-apps)
or
[Forge](https://developer.atlassian.com/cloud/jira/platform/index/#forge-apps)
app can be updated.<br><br>To assist with app migration, this operation
can be used to:<br><br> * Disable a rule.<br> * 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).<br><br>Rules
are enabled if the `disabled` parameter is not
provided.<br><br>**[Permissions](#permissions) required:** Only
[Connect](https://developer.atlassian.com/cloud/jira/platform/index/#connect-apps)
or
[Forge](https://developer.atlassian.com/cloud/jira/platform/index/#forge-apps)
apps can use this operation.
operationId: atlassianUpdateworkflowtransitionruleconfigurations
parameters: []
requestBody:
content:
application/json:
example:
workflows:
- conditions:
- configuration:
disabled: false
tag: Another tag
value: '{ "size": "medium" }'
id: d663bd873d93-59f5-11e9-8647-b4d6cbdc
postFunctions:
- configuration:
disabled: false
tag: Sample tag
value: '{ "color": "red" }'
id: b4d6cbdc-59f5-11e9-8647-d663bd873d93
validators:
- configuration:
disabled: false
value: '{ "shape": "square" }'
id: 11e9-59f5-b4d6cbdc-8647-d663bd873d93
workflowId:
draft: false
name: My Workflow name
schema:
$ref: '#/components/schemas/WorkflowTransitionRulesUpdate'
required: true
responses:
'200':
content:
application/json:
example: >-
{"updateResults":[{"workflowId":{"name":"Workflow with one rule
not
updated","draft":false},"ruleUpdateErrors":{"example-rule-id":["The
rule with this id does not exist:
example-rule-id"]},"updateErrors":[]},{"workflowId":{"name":"Workflow
with all rules successfully
updated","draft":true},"ruleUpdateErrors":{},"updateErrors":[]},{"workflowId":{"name":"Non-existing
workflow","draft":false},"ruleUpdateErrors":{},"updateErrors":["Workflow
not found: WorkflowIdBean{name=Non-existing workflow,
draft=false}"]}]}
schema:
$ref: '#/components/schemas/WorkflowTransitionRulesUpdateErrors'
description: Returned if the request is successful.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the request is invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the caller is not a Connect or Forge app.
'503':
description: >-
Returned if we encounter a problem while trying to access the
required data.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Update Workflow Transition Rule Configurations
tags:
- Workflow Transition Rules
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-configuration
state: Current
- scheme: OAuth2
scopes:
- write:workflow:jira
state: Beta
x-atlassian-connect-scope: ADMIN
/rest/api/3/workflow/rule/config/delete:
put:
deprecated: false
description: >-
Deletes workflow transition rules from one or more workflows. These rule
types are supported:<br><br> * [post
functions](https://developer.atlassian.com/cloud/jira/platform/modules/workflow-post-function/)<br>
* [conditions](https://developer.atlassian.com/cloud/jira/platform/modules/workflow-condition/)<br>
* [validators](https://developer.atlassian.com/cloud/jira/platform/modules/workflow-validator/)<br><br>Only
rules created by the calling Connect app can be
deleted.<br><br>**[Permissions](#permissions) required:** Only Connect
apps can use this operation.
operationId: atlassianDeleteworkflowtransitionruleconfigurations
parameters: []
requestBody:
content:
application/json:
example:
workflows:
- workflowId:
draft: false
name: Internal support workflow
workflowRuleIds:
- b4d6cbdc-59f5-11e9-8647-d663bd873d93
- d663bd873d93-59f5-11e9-8647-b4d6cbdc
- 11e9-59f5-b4d6cbdc-8647-d663bd873d93
schema:
$ref: '#/components/schemas/WorkflowsWithTransitionRulesDetails'
required: true
responses:
'200':
content:
application/json:
example: >-
{"updateResults":[{"workflowId":{"name":"Workflow with one rule
not
updated","draft":false},"ruleUpdateErrors":{"example-rule-id":["The
rule with this id does not exist:
example-rule-id"]},"updateErrors":[]},{"workflowId":{"name":"Workflow
with all rules successfully
updated","draft":true},"ruleUpdateErrors":{},"updateErrors":[]},{"workflowId":{"name":"Non-existing
workflow","draft":false},"ruleUpdateErrors":{},"updateErrors":["Workflow
not found: WorkflowIdBean{name=Non-existing workflow,
draft=false}"]}]}
schema:
$ref: '#/components/schemas/WorkflowTransitionRulesUpdateErrors'
description: Returned if the request is successful.
'400':
content:
application/json:
example: >-
{"errorMessages":["Jira Administration permission is required to
access workflow
configuration."],"errors":{},"httpStatusCode":{"empty":false,"present":true}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the request is invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the caller is not a Connect app.
security:
- basicAuth: []
summary: Atlassian Delete Workflow Transition Rule Configurations
tags:
- Workflow Transition Rules
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/workflow/search:
get:
deprecated: false
description: >-
Returns a [paginated](#pagination) list of published classic workflows.
When workflow names are specified, details of those workflows are
returned. Otherwise, all published classic workflows are
returned.<br><br>This operation does not return next-gen
workflows.<br><br>**[Permissions](#permissions) required:** *Administer
Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianGetworkflowspaginated
parameters:
- description: >-
The index of the first item to return in a page of results (page
offset).
in: query
name: startAt
schema:
default: 0
format: int64
type: integer
- description: The maximum number of items to return per page.
in: query
name: maxResults
schema:
default: 50
format: int32
type: integer
- description: >-
The name of a workflow to return. To include multiple workflows,
provide an ampersand-separated list. For example,
`workflowName=name1&workflowName=name2`.
in: query
name: workflowName
schema:
items:
default: ''
type: string
type: array
uniqueItems: true
- description: >-
Use [expand](#expansion) to include additional information in the
response. This parameter accepts a comma-separated list. Expand
options include:
* `transitions` For each workflow, returns information about the transitions inside the workflow.
* `transitions.rules` For each workflow transition, returns information about its rules. Transitions are included automatically if this expand is requested.
* `transitions.properties` For each workflow transition, returns information about its properties. Transitions are included automatically if this expand is requested.
* `statuses` For each workflow, returns information about the statuses inside the workflow.
* `statuses.properties` For each workflow status, returns information about its properties. Statuses are included automatically if this expand is requested.
* `default` For each workflow, returns information about whether this is the default workflow.
* `schemes` For each workflow, returns information about the workflow schemes the workflow is assigned to.
* `projects` For each workflow, returns information about the projects the workflow is assigned to, through workflow schemes.
* `hasDraftWorkflow` For each workflow, returns information about whether the workflow has a draft version.
* `operations` For each workflow, returns information about the actions that can be undertaken on the workflow.
in: query
name: expand
schema:
type: string
- description: >-
String used to perform a case-insensitive partial match with
workflow name.
in: query
name: queryString
schema:
type: string
- description: |-
[Order](#ordering) the results by a field:
* `name` Sorts by workflow name.
* `created` Sorts by create time.
* `updated` Sorts by update time.
in: query
name: orderBy
schema:
enum:
- name
- '-name'
- +name
- created
- '-created'
- +created
- updated
- +updated
- '-updated'
type: string
- description: Filters active and inactive workflows.
in: query
name: isActive
schema:
type: boolean
responses:
'200':
content:
application/json:
example: >-
{"isLast":false,"maxResults":1,"startAt":0,"total":5,"values":[{"id":{"name":"SCRUM
Workflow","entityId":"5ed312c5-f7a6-4a78-a1f6-8ff7f307d063"},"description":"A
workflow used for Software projects in the SCRUM
methodology","transitions":[{"id":"5","name":"In
Progress","description":"Start working on the
issue.","from":["10","13"],"to":"14","type":"directed","screen":{"id":"10000","name":"Issue
screen"},"rules":{"conditionsTree":{"nodeType":"compound","operator":"AND","conditions":[{"nodeType":"simple","type":"PermissionCondition","configuration":{"permissionKey":"WORK_ON_ISSUES"}},{"nodeType":"simple","type":"PermissionCondition","configuration":{"permissionKey":"RESOLVE_ISSUES"}}]},"validators":[{"type":"FieldRequiredValidator","configuration":{"errorMessage":"A
custom error
message","fields":["description","assignee"],"ignoreContext":true}}],"postFunctions":[{"type":"UpdateIssueStatusFunction"},{"type":"GenerateChangeHistoryFunction"},{"type":"FireIssueEventFunction"}]},"properties":{"jira.fieldscreen.id":1}}],"statuses":[{"id":"3","name":"In
Progress","properties":{"issueEditable":false,"jira.issue.editable":"false"}}],"isDefault":false,"schemes":[{"id":"10001","name":"Test
Workflow
Scheme"}],"projects":[{"avatarUrls":{"16x16":"secure/projectavatar?size=xsmall&pid=10000","24x24":"secure/projectavatar?size=small&pid=10000","32x32":"secure/projectavatar?size=medium&pid=10000","48x48":"secure/projectavatar?size=large&pid=10000"},"id":"10000","key":"EX","name":"Example","projectCategory":{"description":"Project
category description","id":"10000","name":"A project
category"},"projectTypeKey":"ProjectTypeKey{key='software'}","self":"project/EX","simplified":false}],"hasDraftWorkflow":true,"operations":{"canEdit":true,"canDelete":false},"created":"2018-12-10T16:30:15.000+0000","updated":"2018-12-11T11:45:13.000+0000"}]}
schema:
$ref: '#/components/schemas/PageBeanWorkflow'
description: Returned if the request is successful.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access
workflows."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the user does not have the necessary permission.
security:
- basicAuth: []
- OAuth2:
- manage:jira-project
summary: Atlassian Get Workflows Paginated
tags:
- Workflows
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-project
state: Current
- scheme: OAuth2
scopes:
- read:group:jira
- read:issue-security-level:jira
- read:project-role:jira
- read:screen:jira
- read:status:jira
- read:user:jira
- read:workflow:jira
- read:webhook:jira
- read:avatar:jira
- read:project-category:jira
- read:project:jira
state: Beta
x-atlassian-connect-scope: ADMIN
/rest/api/3/workflow/transitions/{transitionId}/properties:
delete:
deprecated: false
description: >-
Deletes a property from a workflow transition. Transition properties are
used to change the behavior of a transition. For more information, see
[Transition
properties](https://confluence.atlassian.com/x/zIhKLg#Advancedworkflowconfiguration-transitionproperties)
and [Workflow
properties](https://confluence.atlassian.com/x/JYlKLg).<br><br>**[Permissions](#permissions)
required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianDeleteworkflowtransitionproperty
parameters:
- description: >-
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.
in: path
name: transitionId
required: true
schema:
format: int64
type: integer
- description: >-
The name of the transition property to delete, also known as the
name of the property.
in: query
name: key
required: true
schema:
type: string
- description: The name of the workflow that the transition belongs to.
in: query
name: workflowName
required: true
schema:
type: string
- description: >-
The workflow status. Set to `live` for inactive workflows or `draft`
for draft workflows. Active workflows cannot be edited.
in: query
name: workflowMode
schema:
enum:
- live
- draft
type: string
responses:
'200':
description: 200 response
'304':
description: >-
Returned if no changes were made by the request. For example, trying
to delete a property that cannot be found.
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
'404':
description: Returned if the workflow transition is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Delete Workflow Transition Property
tags:
- Workflow Transition Properties
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-configuration
state: Current
- scheme: OAuth2
scopes:
- delete:workflow.property:jira
state: Beta
x-atlassian-connect-scope: ADMIN
get:
deprecated: false
description: >-
Returns the properties on a workflow transition. Transition properties
are used to change the behavior of a transition. For more information,
see [Transition
properties](https://confluence.atlassian.com/x/zIhKLg#Advancedworkflowconfiguration-transitionproperties)
and [Workflow
properties](https://confluence.atlassian.com/x/JYlKLg).<br><br>**[Permissions](#permissions)
required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianGetworkflowtransitionproperties
parameters:
- description: >-
The ID of the transition. To get the ID, view the workflow in text
mode in the Jira administration console. The ID is shown next to the
transition.
in: path
name: transitionId
required: true
schema:
format: int64
type: integer
- description: >-
Some properties with keys that have the *jira.* prefix are reserved,
which means they are not editable. To include these properties in
the results, set this parameter to *true*.
in: query
name: includeReservedKeys
schema:
default: false
type: boolean
- description: >-
The key of the property being returned, also known as the name of
the property. If this parameter is not specified, all properties on
the transition are returned.
in: query
name: key
schema:
type: string
- description: The name of the workflow that the transition belongs to.
in: query
name: workflowName
required: true
schema:
type: string
- description: >-
The workflow status. Set to *live* for active and inactive
workflows, or *draft* for draft workflows.
in: query
name: workflowMode
schema:
default: live
enum:
- live
- draft
type: string
responses:
'200':
content:
application/json:
example: >-
[{"id":"jira.i18n.title","key":"jira.i18n.title","value":"some.title"},{"id":"jira.permission","key":"jira.permission","value":"createissue"}]
schema:
$ref: '#/components/schemas/WorkflowTransitionProperty'
description: 200 response
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have admin permission
'404':
description: Returned if the workflow transition or property is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Get Workflow Transition Properties
tags:
- Workflow Transition Properties
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-configuration
state: Current
- scheme: OAuth2
scopes:
- read:workflow.property:jira
state: Beta
x-atlassian-connect-scope: ADMIN
post:
deprecated: false
description: >-
Adds a property to a workflow transition. Transition properties are used
to change the behavior of a transition. For more information, see
[Transition
properties](https://confluence.atlassian.com/x/zIhKLg#Advancedworkflowconfigurat
# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/atlassian/refs/heads/main/openapi/atlassian-rest-api-3-workflow--openapi-original.yml