# 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 Workflows API
  version: 1.0.0
extends: openapi/jira-workflows-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: 16
- target: $.paths['/rest/api/3/workflow/history'].post
  update:
    x-apievangelist-phrasing:
      intent: Read a past version of a workflow
      effect: read
      questions:
      - What did a workflow look like at an earlier version number?
      - How far back can I retrieve a stored workflow version?
      instructions:
      - text: Get version {version} of workflow {workflowId} from history.
        slots:
          version: requestBody.version
          workflowId: requestBody.workflowId
      - text: Show the statuses workflow {workflowId} had at version {version}.
        slots:
          workflowId: requestBody.workflowId
          version: requestBody.version
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/workflow/history/list'].post
  update:
    x-apievangelist-phrasing:
      intent: List the change history of a workflow
      effect: read
      questions:
      - Which saved versions exist in a workflow's history?
      - Can I see when a workflow was changed over the last 60 days?
      instructions:
      - text: List the history entries for workflow {workflowId}.
        slots:
          workflowId: requestBody.workflowId
      - text: Show every recorded revision of workflow {workflowId}.
        slots:
          workflowId: requestBody.workflowId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/workflow/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Page through published classic workflows
      effect: read
      questions:
      - Where can I get a paged list of published classic workflows before that endpoint is retired?
      - Can the older classic workflow listing filter by active or inactive?
      instructions:
      - text: Using the older classic workflow listing, get workflow {workflowName}.
        slots:
          workflowName: query.workflowName
      - text: Page through published classic workflows whose name contains {queryString} via the deprecated endpoint.
        slots:
          queryString: query.queryString
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/workflow/{entityId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an inactive workflow
      effect: destructive
      questions:
      - How do I delete a workflow nobody uses anymore?
      - Why can't I delete a workflow that is still in a workflow scheme?
      instructions:
      - text: Delete inactive workflow {entityId}.
        slots:
          entityId: path.entityId
      - text: Remove the unused workflow with entity ID {entityId}.
        slots:
          entityId: path.entityId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/workflow/{workflowId}/project/{projectId}/issueTypeUsages'].get
  update:
    x-apievangelist-phrasing:
      intent: List issue types in a project using a workflow
      effect: read
      questions:
      - Which issue types in a given project are governed by a particular workflow?
      - Within one project, which work types follow this workflow?
      instructions:
      - text: List issue types in project {projectId} that use workflow {workflowId}.
        slots:
          projectId: path.projectId
          workflowId: path.workflowId
      - text: Show which work types in project {projectId} follow workflow {workflowId}.
        slots:
          projectId: path.projectId
          workflowId: path.workflowId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/workflow/{workflowId}/projectUsages'].get
  update:
    x-apievangelist-phrasing:
      intent: List projects using a workflow
      effect: read
      questions:
      - Which projects are using a given workflow?
      - Is a workflow shared across more than one project?
      instructions:
      - text: List the projects that use workflow {workflowId}.
        slots:
          workflowId: path.workflowId
      - text: Show up to {maxResults} projects relying on workflow {workflowId}.
        slots:
          maxResults: query.maxResults
          workflowId: path.workflowId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/workflow/{workflowId}/workflowSchemes'].get
  update:
    x-apievangelist-phrasing:
      intent: List workflow schemes using a workflow
      effect: read
      questions:
      - Which workflow schemes include a particular workflow?
      - What schemes would I need to change before a workflow can be removed?
      instructions:
      - text: List the workflow schemes that include workflow {workflowId}.
        slots:
          workflowId: path.workflowId
      - text: Find every workflow scheme referencing workflow {workflowId}.
        slots:
          workflowId: path.workflowId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/workflows'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk fetch workflows by name, ID or project
      effect: read
      questions:
      - Can I fetch the full definitions of several workflows at once by their IDs?
      - Which workflow applies to a given project and issue type pair, with its statuses?
      instructions:
      - text: Fetch the full definitions of workflows {workflowIds}.
        slots:
          workflowIds: requestBody.workflowIds
      - text: Bulk get the workflows named {workflowNames} with their statuses.
        slots:
          workflowNames: requestBody.workflowNames
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/workflows/capabilities'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the rules and capabilities a workflow supports
      effect: read
      questions:
      - What conditions, validators and post functions are available for a workflow?
      - Is a workflow global or scoped to a project, and which project types can it use?
      instructions:
      - text: Get the available capabilities for workflow {workflowId}.
        slots:
          workflowId: query.workflowId
      - text: Show which workflow rules I can use for issue type {issueTypeId} in project {projectId}.
        slots:
          issueTypeId: query.issueTypeId
          projectId: query.projectId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/workflows/create'].post
  update:
    x-apievangelist-phrasing:
      intent: Create workflows and their statuses
      effect: write
      questions:
      - How do I create a new workflow together with its statuses?
      - Can I create project-scoped workflows if I'm only a project admin?
      instructions:
      - text: Create these workflows with statuses {statuses}.
        slots:
          statuses: requestBody.statuses
      - text: Create workflows {workflows} scoped to {scope}.
        slots:
          workflows: requestBody.workflows
          scope: requestBody.scope
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/workflows/create/validation'].post
  update:
    x-apievangelist-phrasing:
      intent: Validate a workflow creation payload
      effect: read
      questions:
      - Can I dry-run a new workflow definition to catch errors before creating it?
      - Which validation problems would stop my workflow create request?
      instructions:
      - text: Validate this create-workflows payload {payload} without creating anything.
        slots:
          payload: requestBody.payload
      - text: Check new workflow payload {payload} for errors and warnings.
        slots:
          payload: requestBody.payload
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/workflows/defaultEditor'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the user's default workflow editor
      effect: read
      questions:
      - Am I set up to use the new workflow editor or the legacy one?
      - Which workflow editor opens by default for me?
      instructions:
      - text: Tell me which workflow editor is my default.
      - text: Check whether I'm on the new or legacy workflow editor.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/workflows/preview'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview a workflow within a project
      effect: read
      questions:
      - Can I get a read-only preview of a project's workflow without admin rights?
      - How many workflow IDs can I include in one workflow preview?
      instructions:
      - text: Preview the workflow for issue types {issueTypeIds} in project {projectId}.
        slots:
          issueTypeIds: requestBody.issueTypeIds
          projectId: requestBody.projectId
      - text: Show a lightweight preview of workflows {workflowIds} in project {projectId}.
        slots:
          workflowIds: requestBody.workflowIds
          projectId: requestBody.projectId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/workflows/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search global and project workflows
      effect: read
      questions:
      - Which workflows have a name containing a certain word?
      - Can I list only the active workflows used by one project?
      - Is there a way to separate global workflows from team-managed project ones?
      instructions:
      - text: Search workflows whose name contains {queryString}.
        slots:
          queryString: query.queryString
      - text: List workflows associated with project {projectId}.
        slots:
          projectId: query.projectId
      - text: Find workflows with {scope} scope sorted by {orderBy}.
        slots:
          scope: query.scope
          orderBy: query.orderBy
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/workflows/update'].post
  update:
    x-apievangelist-phrasing:
      intent: Update workflows and their statuses
      effect: write
      questions:
      - How do I change several existing workflows in one request?
      - Can I add statuses to workflows while updating them?
      instructions:
      - text: Apply these changes to existing workflows {workflows}.
        slots:
          workflows: requestBody.workflows
      - text: Update the workflows and associate statuses {statuses} with them.
        slots:
          statuses: requestBody.statuses
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/workflows/update/validation'].post
  update:
    x-apievangelist-phrasing:
      intent: Validate a workflow update payload
      effect: read
      questions:
      - Can I check my workflow edits for errors before applying them?
      - What errors would an update to existing workflows raise?
      instructions:
      - text: Validate this update-workflows payload {payload} before I apply it.
        slots:
          payload: requestBody.payload
      - text: Dry-run workflow update payload {payload} and report problems.
        slots:
          payload: requestBody.payload
      method: generated
      generated: '2026-09-26'