# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Atlassian The Jira Cloud platform REST Workflow Schemes API
  version: 1.0.0
extends: openapi/atlassian-workflow-schemes-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 17
- target: $.paths['/rest/api/3/workflowscheme'].get
  update:
    x-apievangelist-phrasing:
      intent: List all workflow schemes
      effect: read
      questions:
      - What workflow schemes exist in my Jira site?
      - Does the workflow scheme list include drafts?
      instructions:
      - text: List every workflow scheme in Jira.
      - text: Page through workflow schemes starting at {startAt}, {maxResults} at a time.
        slots:
          startAt: query.startAt
          maxResults: query.maxResults
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/workflowscheme'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a workflow scheme
      effect: write
      questions:
      - How do I create a new workflow scheme for my company-managed projects?
      - Can I set a default workflow and issue type mappings when creating a scheme?
      instructions:
      - text: Create a workflow scheme named {name} with default workflow {defaultWorkflow}.
        slots:
          name: requestBody.name
          defaultWorkflow: requestBody.defaultWorkflow
      - text: Make a new workflow scheme {name} described as {description}.
        slots:
          name: requestBody.name
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/workflowscheme/read'].post
  update:
    x-apievangelist-phrasing:
      intent: Look up workflow schemes by scheme or project IDs
      effect: read
      questions:
      - Which workflow scheme is a given set of projects using?
      - Can I fetch several workflow schemes at once by their IDs?
      instructions:
      - text: Get the workflow schemes used by projects {projectIds}.
        slots:
          projectIds: requestBody.projectIds
      - text: Fetch workflow schemes {workflowSchemeIds} in one bulk read.
        slots:
          workflowSchemeIds: requestBody.workflowSchemeIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/workflowscheme/update'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a workflow scheme immediately, without drafts
      effect: write
      questions:
      - Is there a way to change a team-managed project's workflow scheme with no draft step?
      - What happens to issue statuses when I change a scheme's workflows for issue types?
      instructions:
      - text: Update workflow scheme {id} at version {version} with name {name} and description {description}, applying immediately.
        slots:
          id: requestBody.id
          version: requestBody.version
          name: requestBody.name
          description: requestBody.description
      - text: Set default workflow {defaultWorkflowId} on scheme {id} (version {version}, name {name}, description {description}) right away.
        slots:
          defaultWorkflowId: requestBody.defaultWorkflowId
          id: requestBody.id
          version: requestBody.version
          name: requestBody.name
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/workflowscheme/update/mappings'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview status mappings needed for a scheme change
      effect: read
      questions:
      - Which status mappings will I need to provide before changing a workflow scheme?
      - Can I see the required status migrations per issue type for a planned scheme update?
      instructions:
      - text: Work out the status mappings required to apply {workflowsForIssueTypes} to workflow scheme {id}.
        slots:
          workflowsForIssueTypes: requestBody.workflowsForIssueTypes
          id: requestBody.id
      - text: Preview the status mappings for scheme {id} if its default workflow becomes {defaultWorkflowId} with {workflowsForIssueTypes}.
        slots:
          id: requestBody.id
          defaultWorkflowId: requestBody.defaultWorkflowId
          workflowsForIssueTypes: requestBody.workflowsForIssueTypes
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/workflowscheme/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a workflow scheme
      effect: read
      questions:
      - What workflows and issue types are configured in one workflow scheme?
      - Can I see the draft version of a workflow scheme instead of the live one?
      instructions:
      - text: Get workflow scheme {id}.
        slots:
          id: path.id
      - text: 'Show workflow scheme {id}, returning the draft if one exists: {returnDraftIfExists}.'
        slots:
          id: path.id
          returnDraftIfExists: query.returnDraftIfExists
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/workflowscheme/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a company-managed workflow scheme (draft if active)
      effect: write
      questions:
      - How do I rename a workflow scheme that projects are already using?
      - Does editing an active workflow scheme create a draft instead of changing it live?
      instructions:
      - text: Rename workflow scheme {id} to {name}, creating a draft if it's active ({updateDraftIfNeeded}).
        slots:
          id: path.id
          name: requestBody.name
          updateDraftIfNeeded: requestBody.updateDraftIfNeeded
      - text: Update the issue type mappings of workflow scheme {id} to {issueTypeMappings}.
        slots:
          id: path.id
          issueTypeMappings: requestBody.issueTypeMappings
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/workflowscheme/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an unused workflow scheme
      effect: destructive
      questions:
      - Can I delete a workflow scheme that a project is still using?
      - How do I clean up old workflow schemes nobody uses?
      instructions:
      - text: Delete workflow scheme {id}.
        slots:
          id: path.id
      - text: Remove the inactive workflow scheme {id} from Jira.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/workflowscheme/{id}/default'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a workflow scheme's default workflow
      effect: read
      questions:
      - Which workflow do unmapped issue types fall back to in my scheme?
      - What is the default workflow on a scheme's draft?
      instructions:
      - text: Get the default workflow of workflow scheme {id}.
        slots:
          id: path.id
      - text: Show the fallback workflow for unassigned issue types in scheme {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/workflowscheme/{id}/default'].put
  update:
    x-apievangelist-phrasing:
      intent: Set a workflow scheme's default workflow
      effect: write
      questions:
      - How do I change which workflow unmapped issue types use in a scheme?
      - Can I set the default workflow on an active scheme through a draft?
      instructions:
      - text: Set {workflow} as the default workflow of scheme {id}.
        slots:
          workflow: requestBody.workflow
          id: path.id
      - text: 'Make {workflow} the default for scheme {id}, updating a draft if needed: {updateDraftIfNeeded}.'
        slots:
          workflow: requestBody.workflow
          id: path.id
          updateDraftIfNeeded: requestBody.updateDraftIfNeeded
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/workflowscheme/{id}/default'].delete
  update:
    x-apievangelist-phrasing:
      intent: Reset a scheme's default workflow to the system one
      effect: destructive
      questions:
      - How do I revert a workflow scheme's default back to Jira's built-in workflow?
      - What does resetting the default workflow on a scheme do?
      instructions:
      - text: Reset the default workflow of scheme {id} to the jira system workflow.
        slots:
          id: path.id
      - text: 'Clear the custom default workflow on scheme {id}, using a draft if active: {updateDraftIfNeeded}.'
        slots:
          id: path.id
          updateDraftIfNeeded: query.updateDraftIfNeeded
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/workflowscheme/{id}/issuetype/{issueType}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the workflow mapped to an issue type in a scheme
      effect: read
      questions:
      - Which workflow do bugs use under a particular workflow scheme?
      - Is a given issue type mapped to its own workflow in my scheme?
      instructions:
      - text: Get the workflow mapped to issue type {issueType} in scheme {id}.
        slots:
          issueType: path.issueType
          id: path.id
      - text: Show which workflow issue type {issueType} follows in workflow scheme {id}.
        slots:
          issueType: path.issueType
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/workflowscheme/{id}/issuetype/{issueType}'].put
  update:
    x-apievangelist-phrasing:
      intent: Assign a workflow to an issue type in a scheme
      effect: write
      questions:
      - How do I make stories use a different workflow from bugs in one scheme?
      - Can I map a single issue type to a workflow on an active scheme?
      instructions:
      - text: Map issue type {issueType} to workflow {workflow} in scheme {id}.
        slots:
          issueType: path.issueType
          workflow: requestBody.workflow
          id: path.id
      - text: 'Use workflow {workflow} for issue type {issueType} on scheme {id}, updating a draft if needed: {updateDraftIfNeeded}.'
        slots:
          workflow: requestBody.workflow
          issueType: path.issueType
          id: path.id
          updateDraftIfNeeded: requestBody.updateDraftIfNeeded
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/workflowscheme/{id}/issuetype/{issueType}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an issue type's workflow mapping from a scheme
      effect: destructive
      questions:
      - How do I send an issue type back to the scheme's default workflow?
      - Can I unmap one issue type from its workflow in a scheme?
      instructions:
      - text: Remove the workflow mapping for issue type {issueType} in scheme {id}.
        slots:
          issueType: path.issueType
          id: path.id
      - text: 'Unmap issue type {issueType} from scheme {id}, using a draft if active: {updateDraftIfNeeded}.'
        slots:
          issueType: path.issueType
          id: path.id
          updateDraftIfNeeded: query.updateDraftIfNeeded
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/workflowscheme/{id}/workflow'].get
  update:
    x-apievangelist-phrasing:
      intent: List a scheme's workflow-to-issue-type mappings
      effect: read
      questions:
      - Which issue types is each workflow in my scheme assigned to?
      - Can I see the issue types mapped to one named workflow in a scheme?
      instructions:
      - text: List the workflow-issue type mappings for scheme {id}.
        slots:
          id: path.id
      - text: Show which issue types use workflow {workflowName} in scheme {id}.
        slots:
          workflowName: query.workflowName
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/workflowscheme/{id}/workflow'].put
  update:
    x-apievangelist-phrasing:
      intent: Set the issue types for a workflow in a scheme
      effect: write
      questions:
      - How do I assign several issue types to one workflow at once in a scheme?
      - Can I also make that workflow the scheme default while mapping issue types?
      instructions:
      - text: Assign issue types {issueTypes} to workflow {workflowName} in scheme {id}.
        slots:
          issueTypes: requestBody.issueTypes
          workflowName: query.workflowName
          id: path.id
      - text: 'Map workflow {workflowName} in scheme {id} as the default mapping: {defaultMapping}.'
        slots:
          workflowName: query.workflowName
          id: path.id
          defaultMapping: requestBody.defaultMapping
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/workflowscheme/{id}/workflow'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a workflow's issue type mappings from a scheme
      effect: destructive
      questions:
      - How do I take a workflow out of a workflow scheme entirely?
      - What happens to issue types when I delete a workflow's mapping in a scheme?
      instructions:
      - text: Delete the mapping for workflow {workflowName} from scheme {id}.
        slots:
          workflowName: query.workflowName
          id: path.id
      - text: 'Remove workflow {workflowName} from scheme {id}, creating a draft if active: {updateDraftIfNeeded}.'
        slots:
          workflowName: query.workflowName
          id: path.id
          updateDraftIfNeeded: query.updateDraftIfNeeded
      method: generated
      generated: '2026-10-01'