API Evangelist conversational phrasing for Jira Issues 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 Issues API
  version: 1.0.0
extends: openapi/jira-issues-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: 28
- target: $.paths['/issue'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an issue via the legacy /issue endpoint
      effect: write
      questions:
      - Is there an older unversioned /issue endpoint for creating an issue or sub-task?
      - Can the legacy create-issue call record update history for the project I pick?
      instructions:
      - text: Use the legacy /issue endpoint to create an issue with fields {fields}.
        slots:
          fields: requestBody.fields
      - text: Create a sub-task through the older unversioned /issue path using fields {fields}.
        slots:
          fields: requestBody.fields
      method: generated
      generated: '2026-09-26'
- target: $.paths['/issue/{issueIdOrKey}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an issue via the legacy /issue endpoint
      effect: read
      questions:
      - Can I still fetch an issue from the older unversioned /issue path by key?
      - Does the legacy get-issue call return the changelog and transitions too?
      instructions:
      - text: Fetch issue {issueIdOrKey} from the legacy /issue endpoint.
        slots:
          issueIdOrKey: path.issueIdOrKey
      - text: Using the older unversioned path, get issue {issueIdOrKey} with only fields {fields}.
        slots:
          issueIdOrKey: path.issueIdOrKey
          fields: query.fields
      method: generated
      generated: '2026-09-26'
- target: $.paths['/issue/{issueIdOrKey}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit an issue via the legacy /issue endpoint
      effect: write
      questions:
      - Can the older unversioned edit-issue call apply a transition during the edit?
      - Is it possible to edit an issue on the legacy path without notifying watchers?
      instructions:
      - text: Through the legacy /issue endpoint, edit issue {issueIdOrKey} setting fields {fields}.
        slots:
          issueIdOrKey: path.issueIdOrKey
          fields: requestBody.fields
      - text: Edit issue {issueIdOrKey} on the older path and apply transition {transition} as part of the edit.
        slots:
          issueIdOrKey: path.issueIdOrKey
          transition: requestBody.transition
      method: generated
      generated: '2026-09-26'
- target: $.paths['/issue/{issueIdOrKey}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an issue via the legacy /issue endpoint
      effect: destructive
      questions:
      - Can I delete an issue using the older unversioned /issue path?
      - Will the legacy delete refuse an issue that still has sub-tasks?
      instructions:
      - text: Delete issue {issueIdOrKey} through the legacy /issue endpoint.
        slots:
          issueIdOrKey: path.issueIdOrKey
      - text: Using the older path, delete issue {issueIdOrKey} along with its sub-tasks ({deleteSubtasks}).
        slots:
          issueIdOrKey: path.issueIdOrKey
          deleteSubtasks: query.deleteSubtasks
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/changelog/bulkfetch'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk fetch changelogs across many issues
      effect: read
      questions:
      - How do I pull the change history for a batch of issues in one request?
      - Can I filter bulk changelogs down to changes on specific fields only?
      instructions:
      - text: Fetch changelogs for issues {issueIdsOrKeys} in one bulk request.
        slots:
          issueIdsOrKeys: requestBody.issueIdsOrKeys
      - text: Get the change history of issues {issueIdsOrKeys}, limited to changes on fields {fieldIds}.
        slots:
          issueIdsOrKeys: requestBody.issueIdsOrKeys
          fieldIds: requestBody.fieldIds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/events'].get
  update:
    x-apievangelist-phrasing:
      intent: List all issue events
      effect: read
      questions:
      - What issue event types exist in my Jira instance?
      - Which events like issue created or issue resolved can trigger notifications?
      instructions:
      - text: List every issue event type defined on the instance.
      - text: Show me the names and IDs of all issue events.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/issue'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an issue or subtask
      effect: write
      questions:
      - How do I open a new issue in a project with a summary and issue type?
      - Can I create a subtask and move it straight into a workflow step other than the start?
      - Is it possible to set issue properties while creating a single issue?
      instructions:
      - text: Create a new issue with fields {fields}.
        slots:
          fields: requestBody.fields
      - text: Create an issue with fields {fields} and immediately apply transition {transition}.
        slots:
          fields: requestBody.fields
          transition: requestBody.transition
      - text: Open a subtask under the parent given in fields {fields}.
        slots:
          fields: requestBody.fields
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/issue/archive'].put
  update:
    x-apievangelist-phrasing:
      intent: Archive up to 1000 issues by ID or key
      effect: write
      questions:
      - Can I archive a specific list of issues by their keys?
      - What is the limit on how many issues I can archive by key in one call?
      instructions:
      - text: Archive issues {issueIdsOrKeys}.
        slots:
          issueIdsOrKeys: requestBody.issueIdsOrKeys
      - text: 'Archive this list of issue keys and report any that failed: {issueIdsOrKeys}.'
        slots:
          issueIdsOrKeys: requestBody.issueIdsOrKeys
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/issue/archive'].post
  update:
    x-apievangelist-phrasing:
      intent: Archive issues matching a JQL query
      effect: write
      questions:
      - How do I archive every issue that matches a JQL search?
      - Can I archive up to 100,000 old issues in one asynchronous request?
      instructions:
      - text: Archive all issues matching JQL {jql}.
        slots:
          jql: requestBody.jql
      - text: Submit a background job to archive issues found by the query {jql} and give me the status URL.
        slots:
          jql: requestBody.jql
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/issue/bulk'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk create up to 50 issues
      effect: write
      questions:
      - Can I create many issues at once instead of one call per issue?
      - What is the maximum number of issues I can create in a single bulk request?
      instructions:
      - text: 'Bulk create these issues in one request: {issueUpdates}.'
        slots:
          issueUpdates: requestBody.issueUpdates
      - text: Create the batch of issues and subtasks described in {issueUpdates}.
        slots:
          issueUpdates: requestBody.issueUpdates
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/issue/bulkfetch'].post
  update:
    x-apievangelist-phrasing:
      intent: Fetch details for a set of issues
      effect: read
      questions:
      - How can I get details for a hundred issues in a single request?
      - Can I bulk fetch issues and return only certain fields?
      instructions:
      - text: Bulk fetch the details of issues {issueIdsOrKeys}.
        slots:
          issueIdsOrKeys: requestBody.issueIdsOrKeys
      - text: Get issues {issueIdsOrKeys} in one call, returning only fields {fields}.
        slots:
          issueIdsOrKeys: requestBody.issueIdsOrKeys
          fields: requestBody.fields
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/issue/createmeta'].get
  update:
    x-apievangelist-phrasing:
      intent: Get create-issue metadata for projects
      effect: read
      questions:
      - Which projects and issue types am I allowed to create issues in?
      - What fields appear on the create screen for each issue type across projects?
      instructions:
      - text: Show the create metadata for projects {projectKeys}.
        slots:
          projectKeys: query.projectKeys
      - text: Get create screen metadata for issue types {issuetypeNames} in projects {projectKeys}, expanding fields.
        slots:
          issuetypeNames: query.issuetypeNames
          projectKeys: query.projectKeys
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/issue/createmeta/{projectIdOrKey}/issuetypes'].get
  update:
    x-apievangelist-phrasing:
      intent: List creatable issue types for a project
      effect: read
      questions:
      - Which issue types can I create in a given project?
      - Does the list of creatable issue types for one project support paging?
      instructions:
      - text: List the issue types I can create in project {projectIdOrKey}.
        slots:
          projectIdOrKey: path.projectIdOrKey
      - text: Page through creatable issue type metadata for project {projectIdOrKey}, {maxResults} at a time.
        slots:
          projectIdOrKey: path.projectIdOrKey
          maxResults: query.maxResults
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/issue/createmeta/{projectIdOrKey}/issuetypes/{issueTypeId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get create fields for a project issue type
      effect: read
      questions:
      - What fields are required when creating a Bug in a specific project?
      - Which fields are on the create screen for one project and issue type combination?
      instructions:
      - text: Get the create field metadata for issue type {issueTypeId} in project {projectIdOrKey}.
        slots:
          issueTypeId: path.issueTypeId
          projectIdOrKey: path.projectIdOrKey
      - text: Show which fields I must fill in to create issue type {issueTypeId} in {projectIdOrKey}.
        slots:
          issueTypeId: path.issueTypeId
          projectIdOrKey: path.projectIdOrKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/issue/limit/adf/report'].get
  update:
    x-apievangelist-phrasing:
      intent: Report issues breaching the ADF size limit
      effect: read
      questions:
      - Which issues have rich text fields that exceed the ADF byte size limit?
      - Can I restrict the ADF limit report to a particular field type?
      instructions:
      - text: Report issues whose rich text content is over the ADF size limit.
      - text: List issue keys breaching the ADF size limit for field type {fieldType}.
        slots:
          fieldType: query.fieldType
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/issue/limit/report'].get
  update:
    x-apievangelist-phrasing:
      intent: Report issues breaching per-issue limits
      effect: read
      questions:
      - Which issues are close to hitting per-issue limits like too many comments or attachments?
      - Can I get the issue limit report as issue keys instead of IDs?
      instructions:
      - text: Show issues that are breaching or approaching per-issue entity limits.
      - text: Get the per-issue limit report returning keys ({isReturningKeys}).
        slots:
          isReturningKeys: query.isReturningKeys
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/issue/unarchive'].put
  update:
    x-apievangelist-phrasing:
      intent: Unarchive issues by ID or key
      effect: write
      questions:
      - How do I restore archived issues back to active?
      - Can I unarchive a subtask directly or only through its parent?
      instructions:
      - text: Unarchive issues {issueIdsOrKeys}.
        slots:
          issueIdsOrKeys: requestBody.issueIdsOrKeys
      - text: 'Restore these archived issues and list any errors: {issueIdsOrKeys}.'
        slots:
          issueIdsOrKeys: requestBody.issueIdsOrKeys
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/issue/{issueIdOrKey}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an issue's details
      effect: read
      questions:
      - What are the current fields and status of a particular issue?
      - Will looking up an issue still work if it was moved to another project?
      - Can I fetch an issue with its changelog expanded?
      instructions:
      - text: Get the details of issue {issueIdOrKey}.
        slots:
          issueIdOrKey: path.issueIdOrKey
      - text: Fetch issue {issueIdOrKey} returning only fields {fields}.
        slots:
          issueIdOrKey: path.issueIdOrKey
          fields: query.fields
      - text: Show issue {issueIdOrKey} with {expand} expanded.
        slots:
          issueIdOrKey: path.issueIdOrKey
          expand: query.expand
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/issue/{issueIdOrKey}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit an issue's fields
      effect: write
      questions:
      - How do I change the summary or description of an existing issue?
      - Can I update an issue without sending notifications to watchers?
      - Can the edit response return the updated issue?
      instructions:
      - text: Update issue {issueIdOrKey} with fields {fields}.
        slots:
          issueIdOrKey: path.issueIdOrKey
          fields: requestBody.fields
      - text: Edit issue {issueIdOrKey} using operations {update} and don't notify users ({notifyUsers}).
        slots:
          issueIdOrKey: path.issueIdOrKey
          update: requestBody.update
          notifyUsers: query.notifyUsers
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/issue/{issueIdOrKey}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an issue
      effect: destructive
      questions:
      - How do I permanently remove an issue?
      - What happens when I try to delete an issue that has subtasks?
      instructions:
      - text: Delete issue {issueIdOrKey}.
        slots:
          issueIdOrKey: path.issueIdOrKey
      - text: Delete issue {issueIdOrKey} and all of its subtasks ({deleteSubtasks}).
        slots:
          issueIdOrKey: path.issueIdOrKey
          deleteSubtasks: query.deleteSubtasks
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/issue/{issueIdOrKey}/assignee'].put
  update:
    x-apievangelist-phrasing:
      intent: Assign an issue to a user
      effect: write
      questions:
      - How do I assign an issue to someone when I only have Assign permission?
      - Can I unassign an issue or send it to the project's default assignee?
      instructions:
      - text: Assign issue {issueIdOrKey} to account {accountId}.
        slots:
          issueIdOrKey: path.issueIdOrKey
          accountId: requestBody.accountId
      - text: Unassign issue {issueIdOrKey}.
        slots:
          issueIdOrKey: path.issueIdOrKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/issue/{issueIdOrKey}/changelog'].get
  update:
    x-apievangelist-phrasing:
      intent: List an issue's changelog
      effect: read
      questions:
      - Who changed what on an issue and when?
      - Can I page through the full change history of one issue, oldest first?
      instructions:
      - text: Show the changelog for issue {issueIdOrKey}.
        slots:
          issueIdOrKey: path.issueIdOrKey
      - text: Get {maxResults} changelog entries of issue {issueIdOrKey} starting at {startAt}.
        slots:
          maxResults: query.maxResults
          issueIdOrKey: path.issueIdOrKey
          startAt: query.startAt
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/issue/{issueIdOrKey}/changelog/list'].post
  update:
    x-apievangelist-phrasing:
      intent: Get specific changelogs of an issue by ID
      effect: read
      questions:
      - Can I retrieve only certain changelog entries of an issue if I know their IDs?
      - Is there a way to look up specific history records on one issue by changelog ID?
      instructions:
      - text: Get changelogs {changelogIds} for issue {issueIdOrKey}.
        slots:
          changelogIds: requestBody.changelogIds
          issueIdOrKey: path.issueIdOrKey
      - text: Look up changelog entries {changelogIds} on issue {issueIdOrKey}.
        slots:
          changelogIds: requestBody.changelogIds
          issueIdOrKey: path.issueIdOrKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/issue/{issueIdOrKey}/editmeta'].get
  update:
    x-apievangelist-phrasing:
      intent: Get editable fields for an issue
      effect: read
      questions:
      - Which fields on an issue am I allowed to edit?
      - What does the edit screen of a particular issue contain?
      instructions:
      - text: Show the edit metadata for issue {issueIdOrKey}.
        slots:
          issueIdOrKey: path.issueIdOrKey
      - text: List the fields I can edit on issue {issueIdOrKey}, including hidden ones ({overrideScreenSecurity}).
        slots:
          issueIdOrKey: path.issueIdOrKey
          overrideScreenSecurity: query.overrideScreenSecurity
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/issue/{issueIdOrKey}/notify'].post
  update:
    x-apievangelist-phrasing:
      intent: Send an email notification about an issue
      effect: write
      questions:
      - How do I email people about an issue from Jira?
      - Can I send an issue notification to the reporter and watchers with a custom subject?
      instructions:
      - text: Send a notification for issue {issueIdOrKey} with subject {subject} to {to}.
        slots:
          issueIdOrKey: path.issueIdOrKey
          subject: requestBody.subject
          to: requestBody.to
      - text: Email recipients {to} about issue {issueIdOrKey} with the message {textBody}.
        slots:
          to: requestBody.to
          issueIdOrKey: path.issueIdOrKey
          textBody: requestBody.textBody
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/issue/{issueIdOrKey}/transitions'].get
  update:
    x-apievangelist-phrasing:
      intent: List available transitions for an issue
      effect: read
      questions:
      - What workflow transitions can I perform on an issue right now?
      - Can I see transitions that are unavailable along with the ones I can use?
      instructions:
      - text: List the transitions available for issue {issueIdOrKey}.
        slots:
          issueIdOrKey: path.issueIdOrKey
      - text: Check whether transition {transitionId} can be performed on issue {issueIdOrKey}.
        slots:
          transitionId: query.transitionId
          issueIdOrKey: path.issueIdOrKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/issue/{issueIdOrKey}/transitions'].post
  update:
    x-apievangelist-phrasing:
      intent: Transition an issue to a new status
      effect: write
      questions:
      - How do I move an issue to Done?
      - Can I set fields from the transition screen while moving an issue to a new status?
      instructions:
      - text: Transition issue {issueIdOrKey} using transition {transition}.
        slots:
          issueIdOrKey: path.issueIdOrKey
          transition: requestBody.transition
      - text: Move issue {issueIdOrKey} through transition {transition} and set fields {fields}.
        slots:
          issueIdOrKey: path.issueIdOrKey
          transition: requestBody.transition
          fields: requestBody.fields
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/issues/archive/export'].put
  update:
    x-apievangelist-phrasing:
      intent: Export archived issues to a CSV by email
      effect: write
      questions:
      - Can I get a CSV export of all archived issues?
      - Is it possible to export archived issues filtered by project or date archived?
      instructions:
      - text: Export archived issues from projects {projects} and email me the CSV link.
        slots:
          projects: requestBody.projects
      - text: Export issues archived within {archivedDateRange} by {archivedBy}.
        slots:
          archivedDateRange: requestBody.archivedDateRange
          archivedBy: requestBody.archivedBy
      method: generated
      generated: '2026-09-26'