# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Jira Software Cloud Sprint API
  version: 1.0.0
extends: openapi/jira-sprint-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: 13
- target: $.paths['/rest/agile/1.0/sprint'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a future sprint on a board
      effect: write
      questions:
      - How do I create a new sprint on my Jira board?
      - Can I set a sprint goal and dates when creating it?
      instructions:
      - text: Create sprint {name} on board {originBoardId}.
        slots:
          name: requestBody.name
          originBoardId: requestBody.originBoardId
      - text: Create sprint {name} on board {originBoardId} with goal {goal} from {startDate} to {endDate}.
        slots:
          name: requestBody.name
          originBoardId: requestBody.originBoardId
          goal: requestBody.goal
          startDate: requestBody.startDate
          endDate: requestBody.endDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/agile/1.0/sprint/{sprintId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a sprint's details
      effect: read
      questions:
      - What are the dates, state and goal of a particular sprint?
      - How do I look up a sprint by its ID?
      instructions:
      - text: Show sprint {sprintId}.
        slots:
          sprintId: path.sprintId
      - text: Get the goal and dates of sprint {sprintId}.
        slots:
          sprintId: path.sprintId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/agile/1.0/sprint/{sprintId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace all fields of a sprint
      effect: write
      questions:
      - How do I do a full update of a sprint where missing fields get cleared?
      - Can I start a sprint by setting its state to active with a full update?
      instructions:
      - text: Fully replace sprint {sprintId} with name {name}, state {state}, start {startDate} and end {endDate}.
        slots:
          sprintId: path.sprintId
          name: requestBody.name
          state: requestBody.state
          startDate: requestBody.startDate
          endDate: requestBody.endDate
      - text: Overwrite every field of sprint {sprintId} so only {name} and {goal} remain set.
        slots:
          sprintId: path.sprintId
          name: requestBody.name
          goal: requestBody.goal
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/agile/1.0/sprint/{sprintId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Change selected fields of a sprint
      effect: write
      questions:
      - Can I change just a sprint's goal without touching its other fields?
      - How do I close an active sprint by updating only its state?
      instructions:
      - text: Set the goal of sprint {sprintId} to {goal}, leaving other fields alone.
        slots:
          sprintId: path.sprintId
          goal: requestBody.goal
      - text: Change only the state of sprint {sprintId} to {state}.
        slots:
          sprintId: path.sprintId
          state: requestBody.state
      - text: Push the end date of sprint {sprintId} to {endDate}.
        slots:
          sprintId: path.sprintId
          endDate: requestBody.endDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/agile/1.0/sprint/{sprintId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a sprint
      effect: destructive
      questions:
      - What happens to open issues when I delete a sprint?
      - How do I remove a sprint I created by mistake?
      instructions:
      - text: Delete sprint {sprintId}.
        slots:
          sprintId: path.sprintId
      - text: Remove sprint {sprintId} and send its open issues to the backlog.
        slots:
          sprintId: path.sprintId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/agile/1.0/sprint/{sprintId}/issue'].get
  update:
    x-apievangelist-phrasing:
      intent: List issues in a sprint
      effect: read
      questions:
      - Which issues are in the current sprint, ordered by rank?
      - Can I filter a sprint's issues with JQL?
      instructions:
      - text: List the issues in sprint {sprintId}.
        slots:
          sprintId: path.sprintId
      - text: Show issues in sprint {sprintId} matching {jql}.
        slots:
          sprintId: path.sprintId
          jql: query.jql
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/agile/1.0/sprint/{sprintId}/issue'].post
  update:
    x-apievangelist-phrasing:
      intent: Move issues into a sprint
      effect: write
      questions:
      - How do I pull issues from the backlog into an active sprint?
      - How many issues can I move into a sprint in one go?
      instructions:
      - text: Move issues {issues} into sprint {sprintId}.
        slots:
          issues: requestBody.issues
          sprintId: path.sprintId
      - text: Add {issues} to sprint {sprintId} ranked after {rankAfterIssue}.
        slots:
          issues: requestBody.issues
          sprintId: path.sprintId
          rankAfterIssue: requestBody.rankAfterIssue
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/software/1.0/sprint/{sprintId}/issue'].get
  update:
    x-apievangelist-phrasing:
      intent: List sprint issues with token paging
      effect: read
      questions:
      - Is there a sprint issue listing that pages with a nextPageToken instead of startAt?
      - Can I get a sprint's issues with reconciled search results for recently changed issues?
      instructions:
      - text: List issues in sprint {sprintId} using the enhanced token-paged endpoint.
        slots:
          sprintId: path.sprintId
      - text: Get the next page of sprint {sprintId} issues with token {nextPageToken}.
        slots:
          sprintId: path.sprintId
          nextPageToken: query.nextPageToken
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/agile/1.0/sprint/{sprintId}/properties'].get
  update:
    x-apievangelist-phrasing:
      intent: List property keys stored on a sprint
      effect: read
      questions:
      - What custom properties have been stored against a sprint?
      - How do I see the keys of a sprint's entity properties?
      instructions:
      - text: List the property keys on sprint {sprintId}.
        slots:
          sprintId: path.sprintId
      - text: Show which custom data keys sprint {sprintId} holds.
        slots:
          sprintId: path.sprintId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/agile/1.0/sprint/{sprintId}/properties/{propertyKey}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a sprint property value
      effect: read
      questions:
      - How do I read the value of a custom property saved on a sprint?
      - Can I fetch one sprint property by its key?
      instructions:
      - text: Get property {propertyKey} from sprint {sprintId}.
        slots:
          propertyKey: path.propertyKey
          sprintId: path.sprintId
      - text: Read the {propertyKey} value stored on sprint {sprintId}.
        slots:
          propertyKey: path.propertyKey
          sprintId: path.sprintId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/agile/1.0/sprint/{sprintId}/properties/{propertyKey}'].put
  update:
    x-apievangelist-phrasing:
      intent: Store a custom property on a sprint
      effect: write
      questions:
      - Can I store my own custom data against a sprint?
      - How do I set or overwrite a sprint property value?
      instructions:
      - text: Set property {propertyKey} on sprint {sprintId}.
        slots:
          propertyKey: path.propertyKey
          sprintId: path.sprintId
      - text: Save custom data under {propertyKey} for sprint {sprintId}.
        slots:
          propertyKey: path.propertyKey
          sprintId: path.sprintId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/agile/1.0/sprint/{sprintId}/properties/{propertyKey}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a property from a sprint
      effect: destructive
      questions:
      - How do I delete a custom property from a sprint?
      - What permission do I need to remove sprint property data?
      instructions:
      - text: Delete property {propertyKey} from sprint {sprintId}.
        slots:
          propertyKey: path.propertyKey
          sprintId: path.sprintId
      - text: Clear the {propertyKey} data on sprint {sprintId}.
        slots:
          propertyKey: path.propertyKey
          sprintId: path.sprintId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/agile/1.0/sprint/{sprintId}/swap'].post
  update:
    x-apievangelist-phrasing:
      intent: Swap the order of two sprints
      effect: write
      questions:
      - How do I swap the position of two sprints on a board?
      - Can I reorder sprints by exchanging one with another?
      instructions:
      - text: Swap sprint {sprintId} with sprint {sprintToSwapWith}.
        slots:
          sprintId: path.sprintId
          sprintToSwapWith: requestBody.sprintToSwapWith
      - text: Exchange positions of sprints {sprintId} and {sprintToSwapWith}.
        slots:
          sprintId: path.sprintId
          sprintToSwapWith: requestBody.sprintToSwapWith
      method: generated
      generated: '2026-09-26'