API Evangelist conversational phrasing for Jira Cloud platform REST Workflow schemes API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Jira Cloud platform REST Workflow schemes API
  version: 1.0.0
extends: openapi/jira-workflow-schemes-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 19
- target: $.paths['/rest/api/3/workflowscheme'].get
  update:
    x-apievangelist-phrasing:
      intent: List all published workflow schemes
      effect: read
      questions:
      - How do I list every workflow scheme on my Jira site?
      - Does the full workflow scheme list include draft schemes?
      - Can I page through workflow schemes a set number at a time?
      instructions:
      - text: List all workflow schemes on the site.
      - text: Show the next {maxResults} workflow schemes starting at position {startAt}.
        slots:
          maxResults: query.maxResults
          startAt: query.startAt
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/workflowscheme'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new workflow scheme
      effect: write
      questions:
      - How can I set up a brand-new workflow scheme for a group of projects?
      - Can I choose a default workflow when first creating a workflow scheme?
      - What name rules apply when creating a new workflow scheme?
      instructions:
      - text: Create a new workflow scheme named {name}.
        slots:
          name: requestBody.name
      - text: Create workflow scheme {name} with {defaultWorkflow} as its default workflow and description {description}.
        slots:
          name: requestBody.name
          defaultWorkflow: requestBody.defaultWorkflow
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/workflowscheme/project/switch'].post
  update:
    x-apievangelist-phrasing:
      intent: Switch a project to a different workflow scheme
      effect: write
      questions:
      - How do I move a classic project onto another workflow scheme?
      - What happens to issues whose statuses don't exist in the workflow scheme I'm switching a project to?
      - Can team-managed projects be switched to a different workflow scheme?
      instructions:
      - text: Switch project {projectId} to workflow scheme {targetSchemeId}.
        slots:
          projectId: requestBody.projectId
          targetSchemeId: requestBody.targetSchemeId
      - text: Move project {projectId} onto workflow scheme {targetSchemeId}, remapping statuses per issue type with {mappingsByIssueTypeOverride}.
        slots:
          projectId: requestBody.projectId
          targetSchemeId: requestBody.targetSchemeId
          mappingsByIssueTypeOverride: requestBody.mappingsByIssueTypeOverride
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/workflowscheme/read'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk fetch workflow schemes by scheme or project
      effect: read
      questions:
      - Which workflow schemes are my projects using?
      - Can I fetch several workflow schemes at once by their IDs?
      - Is there a way to look up workflow schemes, including project-scoped ones, from a list of project IDs?
      instructions:
      - text: Fetch the workflow schemes used by projects {projectIds}.
        slots:
          projectIds: requestBody.projectIds
      - text: Bulk get workflow schemes {workflowSchemeIds} in one request.
        slots:
          workflowSchemeIds: requestBody.workflowSchemeIds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/workflowscheme/update'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a workflow scheme immediately, without drafts
      effect: write
      questions:
      - How can I change a team-managed project's workflow scheme with the changes applying right away?
      - Will issues be migrated when I change which statuses an issue type's workflow allows?
      - Which update endpoint skips the draft step for workflow schemes?
      instructions:
      - text: Rename workflow scheme {id} to {name} with description {description} at version {version}, applying immediately.
        slots:
          id: requestBody.id
          name: requestBody.name
          description: requestBody.description
          version: requestBody.version
      - text: Update workflow scheme {id} (version {version}) to map workflows to issue types as {workflowsForIssueTypes}, keeping name {name} and description {description}.
        slots:
          id: requestBody.id
          version: requestBody.version
          workflowsForIssueTypes: requestBody.workflowsForIssueTypes
          name: requestBody.name
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- 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 before changing the workflows in a workflow scheme?
      - Can I check per issue type what statuses must be remapped before I update a workflow scheme?
      instructions:
      - text: Work out the status mappings required to apply {workflowsForIssueTypes} to workflow scheme {id}.
        slots:
          workflowsForIssueTypes: requestBody.workflowsForIssueTypes
          id: requestBody.id
      - text: Tell me which statuses need remapping if workflow scheme {id} gets {workflowsForIssueTypes} and default workflow {defaultWorkflowId}.
        slots:
          id: requestBody.id
          workflowsForIssueTypes: requestBody.workflowsForIssueTypes
          defaultWorkflowId: requestBody.defaultWorkflowId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/workflowscheme/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one workflow scheme's details
      effect: read
      questions:
      - What does a specific workflow scheme contain?
      - Can I see the pending draft of a workflow scheme instead of its active version?
      instructions:
      - text: Show me the details of workflow scheme {id}.
        slots:
          id: path.id
      - text: Get workflow scheme {id}, returning its draft if one exists ({returnDraftIfExists}).
        slots:
          id: path.id
          returnDraftIfExists: query.returnDraftIfExists
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/workflowscheme/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a classic workflow scheme (drafts if active)
      effect: write
      questions:
      - How do I rename a company-managed project's workflow scheme?
      - What happens if I edit a workflow scheme that projects are already using?
      - Can the classic update create a draft workflow scheme instead of failing on an active one?
      instructions:
      - text: Rename classic workflow scheme {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Update classic workflow scheme {id} with description {description}, creating a draft if it is active ({updateDraftIfNeeded}).
        slots:
          id: path.id
          description: requestBody.description
          updateDraftIfNeeded: requestBody.updateDraftIfNeeded
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/workflowscheme/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a workflow scheme
      effect: destructive
      questions:
      - How do I get rid of a workflow scheme I no longer use?
      - Can I delete a workflow scheme that a project is still using?
      instructions:
      - text: Delete workflow scheme {id}.
        slots:
          id: path.id
      - text: Remove the unused workflow scheme {id} from the site.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- 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 applies to unmapped issue types in a workflow scheme?
      - What is the default workflow in a scheme's draft?
      instructions:
      - text: Show the default workflow for workflow scheme {id}.
        slots:
          id: path.id
      - text: Get the default workflow of workflow scheme {id}, from its draft if {returnDraftIfExists}.
        slots:
          id: path.id
          returnDraftIfExists: query.returnDraftIfExists
      method: generated
      generated: '2026-09-26'
- 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 the workflow used for all unassigned issue types in a scheme?
      - Can I change the default workflow of an active scheme through a draft?
      instructions:
      - text: Make {workflow} the default workflow of workflow scheme {id}.
        slots:
          workflow: requestBody.workflow
          id: path.id
      - text: Set the default workflow of active scheme {id} to {workflow}, updating its draft ({updateDraftIfNeeded}).
        slots:
          id: path.id
          workflow: requestBody.workflow
          updateDraftIfNeeded: requestBody.updateDraftIfNeeded
      method: generated
      generated: '2026-09-26'
- 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 workflow back to Jira's built-in workflow?
      - Can I reset the default workflow on an active scheme?
      instructions:
      - text: Reset the default workflow of workflow scheme {id} to the system jira workflow.
        slots:
          id: path.id
      - text: Clear the custom default workflow on scheme {id}, via its draft if {updateDraftIfNeeded}.
        slots:
          id: path.id
          updateDraftIfNeeded: query.updateDraftIfNeeded
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/workflowscheme/{id}/issuetype/{issueType}'].get
  update:
    x-apievangelist-phrasing:
      intent: See which workflow an issue type uses in a scheme
      effect: read
      questions:
      - Which workflow does the Bug issue type follow in a given workflow scheme?
      - Can I check a single issue type's workflow mapping in a scheme's draft?
      instructions:
      - text: Show which workflow issue type {issueType} uses in workflow scheme {id}.
        slots:
          issueType: path.issueType
          id: path.id
      - text: Get the draft workflow mapping for issue type {issueType} in scheme {id} ({returnDraftIfExists}).
        slots:
          issueType: path.issueType
          id: path.id
          returnDraftIfExists: query.returnDraftIfExists
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/workflowscheme/{id}/issuetype/{issueType}'].put
  update:
    x-apievangelist-phrasing:
      intent: Assign a workflow to one issue type in a scheme
      effect: write
      questions:
      - How do I make one issue type follow a different workflow inside a workflow scheme?
      - Can I map a single issue type to a workflow on a scheme that's already active?
      instructions:
      - text: Set issue type {issueType} in workflow scheme {id} to use workflow {workflow}.
        slots:
          issueType: path.issueType
          id: path.id
          workflow: requestBody.workflow
      - text: Map issue type {issueType} to workflow {workflow} in active scheme {id}, updating the draft ({updateDraftIfNeeded}).
        slots:
          issueType: path.issueType
          workflow: requestBody.workflow
          id: path.id
          updateDraftIfNeeded: requestBody.updateDraftIfNeeded
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/workflowscheme/{id}/issuetype/{issueType}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove one issue type's workflow mapping in a scheme
      effect: destructive
      questions:
      - How do I unmap an issue type so it falls back to the scheme's default workflow?
      - Can I delete a single issue type's workflow mapping from an active scheme?
      instructions:
      - text: Remove the workflow mapping for issue type {issueType} from workflow scheme {id}.
        slots:
          issueType: path.issueType
          id: path.id
      - text: Unmap issue type {issueType} in scheme {id}, working on the draft if {updateDraftIfNeeded}.
        slots:
          issueType: path.issueType
          id: path.id
          updateDraftIfNeeded: query.updateDraftIfNeeded
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/workflowscheme/{id}/workflow'].get
  update:
    x-apievangelist-phrasing:
      intent: List issue types mapped to each workflow in a scheme
      effect: read
      questions:
      - Which issue types does each workflow cover in a workflow scheme?
      - Can I filter a scheme's workflow-to-issue-type mappings to one workflow name?
      instructions:
      - text: List the workflow-to-issue-type mappings in workflow 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-09-26'
- target: $.paths['/rest/api/3/workflowscheme/{id}/workflow'].put
  update:
    x-apievangelist-phrasing:
      intent: Set the issue types a workflow covers in a scheme
      effect: write
      questions:
      - How do I assign several issue types to one workflow in a workflow scheme at once?
      - Can I make a workflow the scheme default while setting its issue types?
      instructions:
      - text: In workflow scheme {id}, assign issue types {issueTypes} to workflow {workflowName}.
        slots:
          id: path.id
          issueTypes: requestBody.issueTypes
          workflowName: query.workflowName
      - text: Make {workflowName} the default workflow of scheme {id} as part of its issue type mapping ({defaultMapping}).
        slots:
          workflowName: query.workflowName
          id: path.id
          defaultMapping: requestBody.defaultMapping
      method: generated
      generated: '2026-09-26'
- 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?
      - Can I drop all issue type mappings for one workflow on an active scheme?
      instructions:
      - text: Remove workflow {workflowName} and its issue type mappings from workflow scheme {id}.
        slots:
          workflowName: query.workflowName
          id: path.id
      - text: Delete the {workflowName} mappings in scheme {id}, via the draft if {updateDraftIfNeeded}.
        slots:
          workflowName: query.workflowName
          id: path.id
          updateDraftIfNeeded: query.updateDraftIfNeeded
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/workflowscheme/{workflowSchemeId}/projectUsages'].get
  update:
    x-apievangelist-phrasing:
      intent: List projects using a workflow scheme
      effect: read
      questions:
      - Which projects are using a particular workflow scheme?
      - Is the workflow scheme I want to delete still in use by any project?
      instructions:
      - text: List the projects that use workflow scheme {workflowSchemeId}.
        slots:
          workflowSchemeId: path.workflowSchemeId
      - text: Show the next {maxResults} projects using workflow scheme {workflowSchemeId} after cursor {nextPageToken}.
        slots:
          maxResults: query.maxResults
          workflowSchemeId: path.workflowSchemeId
          nextPageToken: query.nextPageToken
      method: generated
      generated: '2026-09-26'