# 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 Project versions API
  version: 1.0.0
extends: openapi/jira-project-versions-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: 15
- target: $.paths['/rest/api/3/project/{projectIdOrKey}/version'].get
  update:
    x-apievangelist-phrasing:
      intent: Page through a project's versions
      effect: read
      questions:
      - Can I search a project's versions by name and filter to released or archived ones?
      - Which versions in a project are still unreleased, sorted by release date?
      - How do I page through a long list of project versions?
      instructions:
      - text: List versions in project {projectIdOrKey} page by page.
        slots:
          projectIdOrKey: path.projectIdOrKey
      - text: Find {status} versions in project {projectIdOrKey} whose name contains {query}.
        slots:
          status: query.status
          projectIdOrKey: path.projectIdOrKey
          query: query.query
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/project/{projectIdOrKey}/versions'].get
  update:
    x-apievangelist-phrasing:
      intent: Get all versions of a project unpaginated
      effect: read
      questions:
      - Can I get every version of a project in one unpaginated response?
      - What's the full release list for a project?
      instructions:
      - text: Get the complete, unpaginated version list for project {projectIdOrKey}.
        slots:
          projectIdOrKey: path.projectIdOrKey
      - text: Return all of project {projectIdOrKey}'s versions in a single call.
        slots:
          projectIdOrKey: path.projectIdOrKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/version'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a project version
      effect: write
      questions:
      - How do I add a new release version to a project?
      - Can I set start and release dates when creating a version?
      instructions:
      - text: Create version {name} in project {projectId}.
        slots:
          name: requestBody.name
          projectId: requestBody.projectId
      - text: Create version {name} for project {projectId} releasing on {releaseDate}.
        slots:
          name: requestBody.name
          projectId: requestBody.projectId
          releaseDate: requestBody.releaseDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/version/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a project version
      effect: read
      questions:
      - What are the dates and release status of a particular version?
      - Can I look up one version by its ID?
      instructions:
      - text: Get version {id}.
        slots:
          id: path.id
      - text: Show release details for version {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/version/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update or release a project version
      effect: write
      questions:
      - Can I mark an existing version as released?
      - Is it possible to rename a version or change its release date after creating it?
      instructions:
      - text: Mark version {id} as released.
        slots:
          id: path.id
      - text: Rename version {id} to {name} and set its release date to {releaseDate}.
        slots:
          id: path.id
          name: requestBody.name
          releaseDate: requestBody.releaseDate
      - text: Archive version {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/version/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a version (legacy)
      effect: destructive
      questions:
      - Can I delete a version and move its fix-version issues somewhere else using the older delete endpoint?
      - What happens to issues when a version is deleted with the deprecated method?
      instructions:
      - text: Delete version {id} with the legacy delete endpoint.
        slots:
          id: path.id
      - text: Delete version {id} and move its fix issues to version {moveFixIssuesTo}.
        slots:
          id: path.id
          moveFixIssuesTo: query.moveFixIssuesTo
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/version/{id}/mergeto/{moveIssuesTo}'].put
  update:
    x-apievangelist-phrasing:
      intent: Merge one version into another
      effect: destructive
      questions:
      - Can I merge two versions so all fix-version references point at one?
      - What happens to the source version when versions are merged?
      instructions:
      - text: Merge version {id} into version {moveIssuesTo}.
        slots:
          id: path.id
          moveIssuesTo: path.moveIssuesTo
      - text: Fold duplicate version {id} into {moveIssuesTo} and delete it.
        slots:
          id: path.id
          moveIssuesTo: path.moveIssuesTo
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/version/{id}/move'].post
  update:
    x-apievangelist-phrasing:
      intent: Reorder a version in a project
      effect: write
      questions:
      - Can I change the display order of versions in a project?
      - Is there a way to move a version to the top of the list?
      instructions:
      - text: Move version {id} to position {position}.
        slots:
          id: path.id
          position: requestBody.position
      - text: Place version {id} right after version {after}.
        slots:
          id: path.id
          after: requestBody.after
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/version/{id}/relatedIssueCounts'].get
  update:
    x-apievangelist-phrasing:
      intent: Count issues that reference a version
      effect: read
      questions:
      - How many issues use a version as their fix version or affected version?
      - Before deleting a version, can I see how many issues reference it?
      instructions:
      - text: Count the issues related to version {id}.
        slots:
          id: path.id
      - text: Show fix-version and affected-version issue counts for version {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/version/{id}/relatedwork'].get
  update:
    x-apievangelist-phrasing:
      intent: List related work on a version
      effect: read
      questions:
      - What related work items, like design docs or links, are attached to a version?
      - Can I see a release's related work links?
      instructions:
      - text: List related work for version {id}.
        slots:
          id: path.id
      - text: Show the links attached as related work to version {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/version/{id}/relatedwork'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a related work link on a version
      effect: write
      questions:
      - Can I change the title or URL of an existing related work link on a version?
      - Which kinds of related work can be edited through the API?
      instructions:
      - text: Update related work {relatedWorkId} on version {id} to point at {url}.
        slots:
          relatedWorkId: requestBody.relatedWorkId
          id: path.id
          url: requestBody.url
      - text: Rename related work {relatedWorkId} on version {id} to {title} in category {category}.
        slots:
          relatedWorkId: requestBody.relatedWorkId
          id: path.id
          title: requestBody.title
          category: requestBody.category
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/version/{id}/relatedwork'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a related work link to a version
      effect: write
      questions:
      - Can I attach a new link, like release notes, as related work on a version?
      - What category is required when adding related work to a release?
      instructions:
      - text: Add related work {title} at {url} to version {id} under category {category}.
        slots:
          title: requestBody.title
          url: requestBody.url
          id: path.id
          category: requestBody.category
      - text: Link {url} to version {id} as {category} related work.
        slots:
          url: requestBody.url
          id: path.id
          category: requestBody.category
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/version/{id}/removeAndSwap'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete a version and swap in replacements
      effect: destructive
      questions:
      - Can I delete a version and reassign its fix and affected issues to other versions?
      - Does deleting a version also update version custom fields on issues?
      instructions:
      - text: Delete and replace version {id}, swapping its fix-version issues onto {moveFixIssuesTo}.
        slots:
          id: path.id
          moveFixIssuesTo: requestBody.moveFixIssuesTo
      - text: Remove version {id}, replacing affected-version references with {moveAffectedIssuesTo}.
        slots:
          id: path.id
          moveAffectedIssuesTo: requestBody.moveAffectedIssuesTo
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/version/{id}/unresolvedIssueCount'].get
  update:
    x-apievangelist-phrasing:
      intent: Count unresolved issues in a version
      effect: read
      questions:
      - How many issues in a release are still unresolved?
      - Is a version ready to ship, or does it still have open issues?
      instructions:
      - text: Count the unresolved issues in version {id}.
        slots:
          id: path.id
      - text: Show total versus unresolved issue counts for version {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/version/{versionId}/relatedwork/{relatedWorkId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a related work link from a version
      effect: destructive
      questions:
      - Can I delete a related work item from a release?
      - What permissions are needed to remove related work from a version?
      instructions:
      - text: Delete related work {relatedWorkId} from version {versionId}.
        slots:
          relatedWorkId: path.relatedWorkId
          versionId: path.versionId
      - text: Remove the related work link {relatedWorkId} on version {versionId}.
        slots:
          relatedWorkId: path.relatedWorkId
          versionId: path.versionId
      method: generated
      generated: '2026-09-26'