Atlassian Jira Workflows API
The Atlassian Jira Workflows API enables bulk workflow operations including creation, validation, and capability checking.
OpenAPI Specification
components:
schemas:
WorkflowCapabilities:
additionalProperties: false
properties:
connectRules:
description: The Connect provided ecosystem rules available.
items:
$ref: '#/components/schemas/AvailableWorkflowConnectRule'
type: array
editorScope:
description: >-
The scope of the workflow capabilities. `GLOBAL` for company-managed
projects and `PROJECT` for team-managed projects.
enum:
- PROJECT
- GLOBAL
type: string
forgeRules:
description: The Forge provided ecosystem rules available.
items:
$ref: '#/components/schemas/AvailableWorkflowForgeRule'
type: array
projectTypes:
description: The types of projects that this capability set is available for.
enum:
- software
- service_desk
- product_discovery
- business
- unknown
items:
description: The types of projects that this capability set is available for.
enum:
- software
- service_desk
- product_discovery
- business
- unknown
type: string
type: array
systemRules:
description: The Atlassian provided system rules available.
items:
$ref: '#/components/schemas/AvailableWorkflowSystemRule'
type: array
triggerRules:
description: The trigger rules available.
items:
$ref: '#/components/schemas/AvailableWorkflowTriggers'
type: array
type: object
WorkflowCreateResponse:
additionalProperties: false
description: Details of the created workflows and statuses.
properties:
statuses:
description: List of created statuses.
items:
$ref: '#/components/schemas/JiraWorkflowStatus'
type: array
uniqueItems: true
workflows:
description: List of created workflows.
items:
$ref: '#/components/schemas/JiraWorkflow'
type: array
uniqueItems: true
type: object
WorkflowValidationErrorList:
additionalProperties: false
properties:
errors:
description: The list of validation errors.
items:
$ref: '#/components/schemas/WorkflowValidationError'
type: array
type: object
WorkflowUpdateResponse:
additionalProperties: false
properties:
statuses:
description: List of updated statuses.
items:
$ref: '#/components/schemas/JiraWorkflowStatus'
type: array
uniqueItems: true
taskId:
description: >-
If there is a [asynchronous task](#async-operations) operation, as a
result of this update.
nullable: true
type: string
workflows:
description: List of updated workflows.
items:
$ref: '#/components/schemas/JiraWorkflow'
type: array
uniqueItems: true
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/workflows/'
version: 1001.0.0-SNAPSHOT-67b5c6e5f3598d7ec1649016d026468ab2838a77
openapi: 3.0.1
paths:
/rest/api/3/workflows/capabilities:
get:
deprecated: false
description: >-
Get the list of workflow capabilities for a specific workflow using
either the workflow ID, or the project and issue type ID pair. The
response includes the scope of the workflow, defined as
global/project-based, and a list of project types that the workflow is
scoped to. It also includes all rules organised into their broad
categories (conditions, validators, actions, triggers, screens) as well
as the source location (Atlassian-provided, Connect,
Forge).<br><br>**[Permissions](#permissions) required:**<br><br> * *Administer Jira* project permission to access all, including
global-scoped, workflows<br> * *Administer projects* project
permissions to access project-scoped workflows<br><br>The current list
of Atlassian-provided rules:<br><br>#### Validators ####<br><br>A
validator rule that checks if a user has the required permissions to
execute the transition in the workflow.<br><br>##### Permission
validator #####<br><br>A validator rule that checks if a user has the
required permissions to execute the transition in the
workflow.<br><br> {<br> "ruleKey":
"system:check-permission-validator",<br> "parameters":
{<br> "permissionKey": "ADMINISTER_PROJECTS"<br> }<br> }<br><br>Parameters:<br><br> * `permissionKey` The permission required
to perform the transition. Allowed values: [built-in Jira
permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-permission-schemes/#built-in-permissions).<br><br>#####
Parent or child blocking validator #####<br><br>A validator to block the
child issue\\u2019s transition depending on the parent issue\\u2019s
status.<br><br> {<br> "ruleKey" :
"system:parent-or-child-blocking-validator"<br> "parameters" :
{<br> "blocker" : "PARENT"<br> "statusIds" :
"1,2,3"<br> }<br> }<br><br>Parameters:<br><br> * `blocker`
currently only supports `PARENT`.<br> * `statusIds` a comma-separated
list of status IDs.<br><br>##### Previous status validator
#####<br><br>A validator that checks if an issue has transitioned
through specified previous status(es) before allowing the current
transition to occur.<br><br> {<br> "ruleKey":
"system:previous-status-validator",<br> "parameters":
{<br> "previousStatusIds": "10014",<br> "mostRecentStatusOnly": "true"<br> }<br> }<br><br>Parameters:<br><br> * `previousStatusIds` a comma-separated
list of status IDs, currently only support one ID.<br> * `mostRecentStatusOnly` when `true` only considers the most recent status
for the condition evaluation. Allowed values: `true`,
`false`.<br><br>##### Validate a field value #####<br><br>A validation
that ensures a specific field's value meets the defined criteria before
allowing an issue to transition in the workflow.<br><br>Depending on the
rule type, the result will vary:<br><br>###### Field required
######<br><br> {<br> "ruleKey":
"system:validate-field-value",<br> "parameters": {<br> "ruleType": "fieldRequired",<br> "fieldsRequired":
"assignee",<br> "ignoreContext": "true",<br> "errorMessage": "An assignee must be set!"<br> }<br> }<br><br>Parameters:<br><br> * `fieldsRequired` the ID of the field
that is required. For a custom field, it would look like
`customfield_123`.<br> * `ignoreContext` controls the impact of context
settings on field validation. When set to `true`, the validator doesn't
check a required field if its context isn't configured for the current
issue. When set to `false`, the validator requires a field even if its
context is invalid. Allowed values: `true`, `false`.<br> * `errorMessage` is the error message to display if the user does not
provide a value during the transition. A default error message will be
shown if you don't provide one (Optional).<br><br>###### Field changed
######<br><br> {<br> "ruleKey":
"system:validate-field-value",<br> "parameters": {<br> "ruleType": "fieldChanged",<br> "groupsExemptFromValidation":
"6862ac20-8672-4f68-896d-4854f5efb79e",<br> "fieldKey":
"versions",<br> "errorMessage": "Affect versions must be
modified before transition"<br> }<br> }<br><br>Parameters:<br><br> * `groupsExemptFromValidation` a
comma-separated list of group IDs to be exempt from the validation.<br>
* `fieldKey` the ID of the field that has changed. For a custom field,
it would look like `customfield_123`.<br> * `errorMessage` the error
message to display if the user does not provide a value during the
transition. A default error message will be shown if you don't provide
one (Optional).<br><br>###### Field has a single value ######<br><br> {<br> "ruleKey": "system:validate-field-value",<br> "parameters": {<br> "ruleType":
"fieldHasSingleValue",<br> "fieldKey": "created",<br> "excludeSubtasks": "true"<br> }<br> }<br><br>Parameters:<br><br> * `fieldKey` the ID of the field to
validate. For a custom field, it would look like `customfield_123`.<br>
* `excludeSubtasks` Option to exclude values copied from sub-tasks.
Allowed values: `true`, `false`.<br><br>###### Field matches regular
expression ######<br><br> {<br> "ruleKey":
"system:validate-field-value",<br> "parameters": {<br> "ruleType": "fieldMatchesRegularExpression",<br> "regexp":
"[0-9]{4}",<br> "fieldKey": "description"<br> }<br> }<br><br>Parameters:<br><br> * `regexp` the regular expression used to
validate the field\\u2019s content.<br> * `fieldKey` the ID of the
field to validate. For a custom field, it would look like
`customfield_123`.<br><br>###### Date field comparison ######<br><br> {<br> "ruleKey": "system:validate-field-value",<br> "parameters": {<br> "ruleType":
"dateFieldComparison",<br> "date1FieldKey":
"duedate",<br> "date2FieldKey": "customfield_10054",<br> "includeTime": "true",<br> "conditionSelected": ">="<br> }<br> }<br><br>Parameters:<br><br> * `date1FieldKey` the ID of the
first field to compare. For a custom field, it would look like
`customfield_123`.<br> * `date2FieldKey` the ID of the second field to
compare. For a custom field, it would look like `customfield_123`.<br>
* `includeTime` if `true`, compares both date and time. Allowed values:
`true`, `false`.<br> * `conditionSelected` the condition to compare
with. Allowed values: `>`, `>=`, `=`, ``, `>=`, `=`, `
operationId: atlassianWorkflowcapabilities
parameters:
- in: query
name: workflowId
schema:
type: string
- in: query
name: projectId
schema:
type: string
- in: query
name: issueTypeId
schema:
type: string
responses:
'200':
content:
application/json:
example: >-
{"connectRules":[{"addonKey":"com.atlassian.jira.refapp","createUrl":"/validators/jira-expression/create?id={validator.id}","description":"Validates
if the given Jira expression is
true.","editUrl":"/validators/jira-expression/edit?id={validator.id}","moduleKey":"jiraExpressionValidator","name":"Jira
expression validator (by
APPNAME)","ruleKey":"connect:expression-validator","ruleType":"Validator","viewUrl":"/validators/jira-expression/view?id={validator.id}"}],"editorScope":"GLOBAL","forgeRules":[{"description":"A
Jira workflow validator
example.","id":"ari:cloud:ecosystem::extension/9df6d15f-1bbe-443e-be08-150309e8dbb0/f6a3bed3-737f-4e7a-8942-130df302b749/static/workflow-validator-example-workflow-validator","name":"workflow-validator","ruleKey":"forge:expression-validator","ruleType":"Validator"}],"projectTypes":["software","business"],"systemRules":[{"description":"Automatically
assign a request to someone after moving the request using a
particular
transition.","incompatibleRuleKeys":[],"isAvailableForInitialTransition":true,"isVisible":true,"name":"Assign
a
request","ruleKey":"system:change-assignee","ruleType":"Function"}],"triggerRules":[{"availableTypes":[{"description":"Automatically
transitions the issue when a related branch is created in a
connected repository","name":"Branch
created","type":"com.atlassian.jira.plugins.jira-development-integration-plugin:branch-created-trigger"}],"ruleKey":"system:development-triggers"}]}
schema:
$ref: '#/components/schemas/WorkflowCapabilities'
description: Returned if the request is successful.
'400':
description: Returned if the request is not valid.
'401':
description: >-
Returned if the authentication credentials are incorrect or missing,
or the caller doesn't have permissions to perform the operation.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Get Available Workflow Capabilities
tags:
- Workflows
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-experimental: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/workflows/create:
post:
deprecated: false
description: >-
Create workflows and related
statuses.<br><br>**[Permissions](#permissions) required:**<br><br> * *Administer Jira* project permission to create all, including
global-scoped, workflows<br> * *Administer projects* project
permissions to create project-scoped workflows
operationId: atlassianCreateworkflows
parameters: []
requestBody:
content:
application/json:
example:
scope:
type: GLOBAL
statuses:
- description: ''
name: To Do
statusCategory: TODO
statusReference: f0b24de5-25e7-4fab-ab94-63d81db6c0c0
- description: ''
name: In Progress
statusCategory: IN_PROGRESS
statusReference: c7a35bf0-c127-4aa6-869f-4033730c61d8
- description: ''
name: Done
statusCategory: DONE
statusReference: 6b3fc04d-3316-46c5-a257-65751aeb8849
workflows:
- description: ''
name: Software workflow 1
startPointLayout:
x: -100.00030899047852
'y': -153.00020599365234
statuses:
- layout:
x: 114.99993896484375
'y': -16
properties: {}
statusReference: f0b24de5-25e7-4fab-ab94-63d81db6c0c0
- layout:
x: 317.0000915527344
'y': -16
properties: {}
statusReference: c7a35bf0-c127-4aa6-869f-4033730c61d8
- layout:
x: 508.000244140625
'y': -16
properties: {}
statusReference: 6b3fc04d-3316-46c5-a257-65751aeb8849
transitions:
- actions: []
description: ''
from: []
id: '1'
name: Create
properties: {}
to:
statusReference: f0b24de5-25e7-4fab-ab94-63d81db6c0c0
triggers: []
type: INITIAL
validators: []
- actions: []
description: ''
from: []
id: '11'
name: To Do
properties: {}
to:
statusReference: f0b24de5-25e7-4fab-ab94-63d81db6c0c0
triggers: []
type: GLOBAL
validators: []
- actions: []
description: ''
from: []
id: '21'
name: In Progress
properties: {}
to:
statusReference: c7a35bf0-c127-4aa6-869f-4033730c61d8
triggers: []
type: GLOBAL
validators: []
- actions: []
description: ''
from: []
id: '31'
name: Done
properties: {}
to:
statusReference: 6b3fc04d-3316-46c5-a257-65751aeb8849
triggers: []
type: GLOBAL
validators: []
schema:
$ref: '#/components/schemas/WorkflowCreateRequest'
required: true
responses:
'200':
content:
application/json:
example: >-
{"statuses":[{"description":"","id":"10001","name":"To
Do","scope":{"type":"GLOBAL"},"statusCategory":"TODO","statusReference":"10001","usages":[]},{"description":"","id":"10002","name":"In
Progress","scope":{"type":"GLOBAL"},"statusCategory":"IN_PROGRESS","statusReference":"10002","usages":[]},{"description":"","id":"10003","name":"Done","scope":{"type":"GLOBAL"},"statusCategory":"DONE","statusReference":"10003","usages":[]}],"workflows":[{"description":"","id":"b9ff2384-d3b6-4d4e-9509-3ee19f607168","isEditable":true,"name":"Software
workflow
1","scope":{"type":"GLOBAL"},"startPointLayout":{"x":-100.00030899047852,"y":-153.00020599365234},"statuses":[{"deprecated":false,"layout":{"x":114.99993896484375,"y":-16.0},"properties":{},"statusReference":"10001"},{"deprecated":false,"layout":{"x":317.0000915527344,"y":-16.0},"properties":{},"statusReference":"10002"},{"deprecated":false,"layout":{"x":508.000244140625,"y":-16.0},"properties":{},"statusReference":"10003"}],"transitions":[{"actions":[],"description":"","from":[],"id":"31","name":"Done","properties":{},"to":{"statusReference":"10003"},"triggers":[],"type":"GLOBAL","validators":[]},{"actions":[],"description":"","from":[],"id":"11","name":"To
Do","properties":{},"to":{"statusReference":"10001"},"triggers":[],"type":"GLOBAL","validators":[]},{"actions":[],"description":"","from":[],"id":"21","name":"In
Progress","properties":{},"to":{"statusReference":"10002"},"triggers":[],"type":"GLOBAL","validators":[]},{"actions":[],"description":"","from":[],"id":"1","name":"Create","properties":{},"to":{"statusReference":"10001"},"triggers":[],"type":"INITIAL","validators":[]}],"usages":[],"version":{"id":"f010ac1b-3dd3-43a3-aa66-0ee8a447f76e","versionNumber":0}}]}
schema:
$ref: '#/components/schemas/WorkflowCreateResponse'
description: Returned if the request is successful.
'400':
description: Returned if the request is not valid.
'401':
description: >-
Returned if the authentication credentials are incorrect or missing,
or the caller doesn't have permissions to perform the operation.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Bulk Create Workflows
tags:
- Workflows
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-experimental: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/workflows/create/validation:
post:
deprecated: false
description: >-
Validate the payload for bulk create
workflows.<br><br>**[Permissions](#permissions) required:**<br><br> * *Administer Jira* project permission to create all, including
global-scoped, workflows<br> * *Administer projects* project
permissions to create project-scoped workflows
operationId: atlassianValidatecreateworkflows
parameters: []
requestBody:
content:
application/json:
example:
payload:
scope:
type: GLOBAL
statuses:
- description: ''
name: To Do
statusCategory: TODO
statusReference: f0b24de5-25e7-4fab-ab94-63d81db6c0c0
- description: ''
name: In Progress
statusCategory: IN_PROGRESS
statusReference: c7a35bf0-c127-4aa6-869f-4033730c61d8
- description: ''
name: Done
statusCategory: DONE
statusReference: 6b3fc04d-3316-46c5-a257-65751aeb8849
workflows:
- description: ''
name: Software workflow 1
startPointLayout:
x: -100.00030899047852
'y': -153.00020599365234
statuses:
- layout:
x: 114.99993896484375
'y': -16
properties: {}
statusReference: f0b24de5-25e7-4fab-ab94-63d81db6c0c0
- layout:
x: 317.0000915527344
'y': -16
properties: {}
statusReference: c7a35bf0-c127-4aa6-869f-4033730c61d8
- layout:
x: 508.000244140625
'y': -16
properties: {}
statusReference: 6b3fc04d-3316-46c5-a257-65751aeb8849
transitions:
- actions: []
description: ''
from: []
id: '1'
name: Create
properties: {}
to:
statusReference: f0b24de5-25e7-4fab-ab94-63d81db6c0c0
triggers: []
type: INITIAL
validators: []
- actions: []
description: ''
from: []
id: '11'
name: To Do
properties: {}
to:
statusReference: f0b24de5-25e7-4fab-ab94-63d81db6c0c0
triggers: []
type: GLOBAL
validators: []
- actions: []
description: ''
from: []
id: '21'
name: In Progress
properties: {}
to:
statusReference: c7a35bf0-c127-4aa6-869f-4033730c61d8
triggers: []
type: GLOBAL
validators: []
- actions: []
description: ''
from: []
id: '31'
name: Done
properties: {}
to:
statusReference: 6b3fc04d-3316-46c5-a257-65751aeb8849
triggers: []
type: GLOBAL
validators: []
validationOptions:
levels:
- ERROR
- WARNING
schema:
$ref: '#/components/schemas/WorkflowCreateValidateRequest'
required: true
responses:
'200':
content:
application/json:
example: >-
{"errors":[{"code":"NON_UNIQUE_STATUS_NAME","elementReference":{"statusReference":"1f0443ff-47e4-4306-9c26-0af696059a43"},"level":"ERROR","message":"You
must use a unique status name.","type":"STATUS"}]}
schema:
$ref: '#/components/schemas/WorkflowValidationErrorList'
description: Returned if the request is successful.
'400':
description: Returned if the request is not valid.
'401':
description: >-
Returned if the authentication credentials are incorrect or missing,
or the caller doesn't have permissions to perform the operation.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Validate Create Workflows
tags:
- Workflows
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-experimental: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/workflows/update:
post:
deprecated: false
description: >-
Update workflows and related
statuses.<br><br>**[Permissions](#permissions) required:**<br><br> * *Administer Jira* project permission to create all, including
global-scoped, workflows<br> * *Administer projects* project
permissions to create project-scoped workflows
operationId: atlassianUpdateworkflows
parameters:
- description: >-
Use [expand](#expansion) to include additional information in the
response. This parameter accepts a comma-separated list. Expand
options include:
* `workflows.usages` Returns the project and issue types that each workflow is associated with.
* `statuses.usages` Returns the project and issue types that each status is associated with.
in: query
name: expand
schema:
type: string
requestBody:
content:
application/json:
example:
statuses:
- description: ''
name: To Do
statusCategory: TODO
statusReference: f0b24de5-25e7-4fab-ab94-63d81db6c0c0
- description: ''
name: In Progress
statusCategory: IN_PROGRESS
statusReference: c7a35bf0-c127-4aa6-869f-4033730c61d8
- description: ''
name: Done
statusCategory: DONE
statusReference: 6b3fc04d-3316-46c5-a257-65751aeb8849
workflows:
- defaultStatusMappings:
- newStatusReference: '10011'
oldStatusReference: '10010'
description: ''
id: '10001'
startPointLayout:
x: -100.00030899047852
'y': -153.00020599365234
statusMappings:
- issueTypeId: '10002'
projectId: '10003'
statusMigrations:
- newStatusReference: '10011'
oldStatusReference: '10010'
statuses:
- layout:
x: 114.99993896484375
'y': -16
properties: {}
statusReference: f0b24de5-25e7-4fab-ab94-63d81db6c0c0
- layout:
x: 317.0000915527344
'y': -16
properties: {}
statusReference: c7a35bf0-c127-4aa6-869f-4033730c61d8
- layout:
x: 508.000244140625
'y': -16
properties: {}
statusReference: 6b3fc04d-3316-46c5-a257-65751aeb8849
transitions:
- actions: []
description: ''
from: []
id: '1'
name: Create
properties: {}
to:
statusReference: f0b24de5-25e7-4fab-ab94-63d81db6c0c0
triggers: []
type: INITIAL
validators: []
- actions: []
description: ''
from: []
id: '11'
name: To Do
properties: {}
to:
statusReference: f0b24de5-25e7-4fab-ab94-63d81db6c0c0
triggers: []
type: GLOBAL
validators: []
- actions: []
description: ''
from: []
id: '21'
name: In Progress
properties: {}
to:
statusReference: c7a35bf0-c127-4aa6-869f-4033730c61d8
triggers: []
type: GLOBAL
validators: []
- actions: []
description: ''
from: []
id: '31'
name: Done
properties: {}
to:
statusReference: 6b3fc04d-3316-46c5-a257-65751aeb8849
triggers: []
type: GLOBAL
validators: []
version:
id: 6f6c988b-2590-4358-90c2-5f7960265592
versionNumber: 1
schema:
$ref: '#/components/schemas/WorkflowUpdateRequest'
required: true
responses:
'200':
content:
application/json:
example: >-
{"statuses":[{"description":"","id":"10001","name":"To
Do","scope":{"type":"GLOBAL"},"statusCategory":"TODO","statusReference":"10001","usages":[]},{"description":"","id":"10002","name":"In
Progress","scope":{"type":"GLOBAL"},"statusCategory":"IN_PROGRESS","statusReference":"10002","usages":[]},{"description":"","id":"10003","name":"Done","scope":{"type":"GLOBAL"},"statusCategory":"DONE","statusReference":"10003","usages":[]}],"taskId":"10001","workflows":[{"description":"","id":"b9ff2384-d3b6-4d4e-9509-3ee19f607168","isEditable":true,"name":"Software
workflow
1","scope":{"type":"GLOBAL"},"startPointLayout":{"x":-100.00030899047852,"y":-153.00020599365234},"statuses":[{"deprecated":false,"layout":{"x":114.99993896484375,"y":-16.0},"properties":{},"statusReference":"10001"},{"deprecated":false,"layout":{"x":317.0000915527344,"y":-16.0},"properties":{},"statusReference":"10002"},{"deprecated":false,"layout":{"x":508.000244140625,"y":-16.0},"properties":{},"statusReference":"10003"}],"transitions":[{"actions":[],"description":"","from":[],"id":"31","name":"Done","properties":{},"to":{"statusReference":"10003"},"triggers":[],"type":"GLOBAL","validators":[]},{"actions":[],"description":"","from":[],"id":"11","name":"To
Do","
# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/atlassian/refs/heads/main/openapi/atlassian-rest-api-3-workflows--openapi-original.yml