# 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 Project Versions API
  version: 1.0.0
extends: openapi/atlassian-project-versions-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: 15
- target: $.paths['/rest/api/3/project/{projectIdOrKey}/version'].get
  update:
    x-apievangelist-phrasing:
      intent: Page through a Jira project's versions
      effect: read
      questions:
      - How do I page through the releases of a large Jira project?
      - Can I filter a project's versions to only released or archived ones?
      - Is there a way to search project versions by name?
      instructions:
      - text: List versions in project {projectIdOrKey} page by page.
        slots:
          projectIdOrKey: path.projectIdOrKey
      - text: Show versions in {projectIdOrKey} with status {status}, ordered by {orderBy}.
        slots:
          projectIdOrKey: path.projectIdOrKey
          status: query.status
          orderBy: query.orderBy
      - text: Search versions in {projectIdOrKey} whose name matches {query}.
        slots:
          projectIdOrKey: path.projectIdOrKey
          query: query.query
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/project/{projectIdOrKey}/versions'].get
  update:
    x-apievangelist-phrasing:
      intent: Get every version in a project, unpaginated
      effect: read
      questions:
      - Can I get the full list of a Jira project's versions in one response?
      - What versions exist in this project without paging?
      instructions:
      - text: Get all versions of project {projectIdOrKey} in a single unpaginated list.
        slots:
          projectIdOrKey: path.projectIdOrKey
      - text: Return every release defined in {projectIdOrKey} at once.
        slots:
          projectIdOrKey: path.projectIdOrKey
      method: generated
      generated: '2026-10-01'
- 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 Jira project?
      - Can I set a start and release date when I create a version?
      instructions:
      - text: Create version {name} in project {projectId}.
        slots:
          name: requestBody.name
          projectId: requestBody.projectId
      - text: Add release {name} to project {projectId} due on {releaseDate}.
        slots:
          name: requestBody.name
          projectId: requestBody.projectId
          releaseDate: requestBody.releaseDate
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/version/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a project version
      effect: read
      questions:
      - How do I look up one Jira version by its id?
      - What are the release date and status of a given version?
      instructions:
      - text: Get version {id}.
        slots:
          id: path.id
      - text: Show me the details of Jira version {id} with {expand} expanded.
        slots:
          id: path.id
          expand: query.expand
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/version/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a project version
      effect: write
      questions:
      - How do I mark a Jira version as released?
      - Can I rename a version or change its release date afterwards?
      instructions:
      - text: Mark version {id} as released set to {released}.
        slots:
          id: path.id
          released: requestBody.released
      - text: Rename version {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/version/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a version (deprecated endpoint)
      effect: destructive
      questions:
      - What's the older way to delete a Jira version and move its fix-version issues?
      - Can the deprecated version delete move affected issues to another version?
      instructions:
      - text: Delete version {id} using the deprecated delete endpoint.
        slots:
          id: path.id
      - text: Delete version {id} and move its fix issues to {moveFixIssuesTo} and affected issues to {moveAffectedIssuesTo}.
        slots:
          id: path.id
          moveFixIssuesTo: query.moveFixIssuesTo
          moveAffectedIssuesTo: query.moveAffectedIssuesTo
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/version/{id}/mergeto/{moveIssuesTo}'].put
  update:
    x-apievangelist-phrasing:
      intent: Merge one version into another
      effect: destructive
      questions:
      - How do I merge two duplicate Jira versions into one?
      - What happens to the version that gets merged away?
      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-10-01'
- target: $.paths['/rest/api/3/version/{id}/move'].post
  update:
    x-apievangelist-phrasing:
      intent: Reorder a version within its project
      effect: write
      questions:
      - How do I change the display order of versions in a Jira project?
      - Can I move a version to the top of the list or after another version?
      instructions:
      - text: Move version {id} to position {position}.
        slots:
          id: path.id
          position: requestBody.position
      - text: Place version {id} after {after} in the project's order.
        slots:
          id: path.id
          after: requestBody.after
      method: generated
      generated: '2026-10-01'
- 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 have this version as their fix version or affected version?
      - Is any issue still using a version before I delete it?
      instructions:
      - text: Count the issues related to version {id}.
        slots:
          id: path.id
      - text: Show fix-version and affected-version issue counts for {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/version/{id}/relatedwork'].get
  update:
    x-apievangelist-phrasing:
      intent: List related work items on a version
      effect: read
      questions:
      - What related work links are attached to a Jira release?
      - Can I see the design docs and links tied to a version?
      instructions:
      - text: List the related work for version {id}.
        slots:
          id: path.id
      - text: Show me every related work link on release {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- 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:
      - How do I change the URL or title of a related work link on a version?
      - Can I edit related work on an archived version?
      instructions:
      - text: Update related work {relatedWorkId} on version {id} to category {category}.
        slots:
          relatedWorkId: requestBody.relatedWorkId
          id: path.id
          category: requestBody.category
      - text: Change the URL of related work {relatedWorkId} on version {id} to {url}.
        slots:
          relatedWorkId: requestBody.relatedWorkId
          id: path.id
          url: requestBody.url
      method: generated
      generated: '2026-10-01'
- 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:
      - How do I attach a link to a release, like a design doc?
      - Which kind of related work can be created through the API?
      instructions:
      - text: Add related work titled {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 release {id} as {category} work.
        slots:
          url: requestBody.url
          id: path.id
          category: requestBody.category
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/version/{id}/removeAndSwap'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete a version and reassign its issues
      effect: destructive
      questions:
      - How do I delete a version and move its issues, including custom version fields, to another version?
      - What happens to issues on a deleted version if I give no replacement?
      instructions:
      - text: Delete version {id} and swap its fix issues to {moveFixIssuesTo}.
        slots:
          id: path.id
          moveFixIssuesTo: requestBody.moveFixIssuesTo
      - text: Remove version {id}, moving affected issues to {moveAffectedIssuesTo} and custom field values per {customFieldReplacementList}.
        slots:
          id: path.id
          moveAffectedIssuesTo: requestBody.moveAffectedIssuesTo
          customFieldReplacementList: requestBody.customFieldReplacementList
      method: generated
      generated: '2026-10-01'
- 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 are still unresolved in this release?
      - Is this version ready to ship, or are open issues left?
      instructions:
      - text: Count unresolved issues in version {id}.
        slots:
          id: path.id
      - text: Tell me how many open versus total issues release {id} has.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- 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:
      - How do I delete a related work link from a release?
      - Can I remove an outdated link attached to a version?
      instructions:
      - text: Delete related work {relatedWorkId} from version {versionId}.
        slots:
          relatedWorkId: path.relatedWorkId
          versionId: path.versionId
      - text: Remove link {relatedWorkId} from release {versionId}.
        slots:
          relatedWorkId: path.relatedWorkId
          versionId: path.versionId
      method: generated
      generated: '2026-10-01'