# 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 Issues API
  version: 1.0.0
extends: openapi/atlassian-issues-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: 20
- target: $.paths['/rest/api/3/events'].get
  update:
    x-apievangelist-phrasing:
      intent: List all Jira issue event types
      effect: read
      questions:
      - What issue events does Jira fire, like issue created or issue resolved?
      - Which event types can I hook notifications onto in my Jira site?
      instructions:
      - text: List every issue event type defined in Jira.
      - text: Show me the IDs and names of all Jira issue events.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/issue'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a Jira issue or subtask
      effect: write
      questions:
      - How do I create a single new issue in Jira through the API?
      - Can I open a subtask and move it straight to a non-default workflow step when I create it?
      - Is it possible to set issue properties at the moment a ticket is created?
      instructions:
      - text: 'Create a new issue with these field values: {fields}.'
        slots:
          fields: requestBody.fields
      - text: Open a single ticket with {fields} and apply transition {transition} on creation.
        slots:
          fields: requestBody.fields
          transition: requestBody.transition
      - text: Create one issue from {fields} and attach the properties {properties}.
        slots:
          fields: requestBody.fields
          properties: requestBody.properties
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/issue/archive'].put
  update:
    x-apievangelist-phrasing:
      intent: Archive up to 1,000 issues by ID or key
      effect: write
      questions:
      - Can an admin archive a specific list of issues by their keys?
      - What is the limit on how many issues I can archive by key in one request?
      instructions:
      - text: Archive the issues {issueIdsOrKeys}.
        slots:
          issueIdsOrKeys: requestBody.issueIdsOrKeys
      - text: 'Archive these specific tickets by key and report any errors: {issueIdsOrKeys}.'
        slots:
          issueIdsOrKeys: requestBody.issueIdsOrKeys
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/issue/archive'].post
  update:
    x-apievangelist-phrasing:
      intent: Archive up to 100,000 issues matching a JQL query
      effect: write
      questions:
      - Can I archive every issue that matches a JQL search in one go?
      - How many issues can a JQL-based archive request handle, and how do I track its progress?
      instructions:
      - text: Archive all issues matching the JQL {jql}.
        slots:
          jql: requestBody.jql
      - text: Start a background archive job for every ticket returned by {jql}.
        slots:
          jql: requestBody.jql
      method: generated
      generated: '2026-10-01'
- 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 Jira issues in a single request?
      - What is the maximum number of issues a bulk create call accepts?
      instructions:
      - text: 'Bulk create these issues in one request: {issueUpdates}.'
        slots:
          issueUpdates: requestBody.issueUpdates
      - text: Create a batch of up to 50 tickets from {issueUpdates}.
        slots:
          issueUpdates: requestBody.issueUpdates
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/issue/createmeta'].get
  update:
    x-apievangelist-phrasing:
      intent: Get create-screen metadata across projects
      effect: read
      questions:
      - Which projects and issue types am I allowed to create issues in?
      - What fields appear on the create screen for issue types across several projects?
      instructions:
      - text: Show the create issue metadata for projects {projectKeys}.
        slots:
          projectKeys: query.projectKeys
      - text: Get create-screen fields for issue types {issuetypeNames} in projects {projectKeys}, expanding {expand}.
        slots:
          issuetypeNames: query.issuetypeNames
          projectKeys: query.projectKeys
          expand: query.expand
      method: generated
      generated: '2026-10-01'
- 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:
      - What issue types can I create in a given project?
      - Is there a paged list of issue type metadata for one project's create screen?
      instructions:
      - text: List the issue types I can create in project {projectIdOrKey}.
        slots:
          projectIdOrKey: path.projectIdOrKey
      - text: Show the first {maxResults} creatable issue types for project {projectIdOrKey}.
        slots:
          maxResults: query.maxResults
          projectIdOrKey: path.projectIdOrKey
      method: generated
      generated: '2026-10-01'
- 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:
      - Which fields are required when creating a particular issue type in a project?
      - What does the create screen look like for a bug type in one specific project?
      instructions:
      - text: Get the create fields for issue type {issueTypeId} in project {projectIdOrKey}.
        slots:
          issueTypeId: path.issueTypeId
          projectIdOrKey: path.projectIdOrKey
      - text: List required and optional create fields for type {issueTypeId} in {projectIdOrKey}, starting at {startAt}.
        slots:
          issueTypeId: path.issueTypeId
          projectIdOrKey: path.projectIdOrKey
          startAt: query.startAt
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/issue/unarchive'].put
  update:
    x-apievangelist-phrasing:
      intent: Restore archived issues by ID or key
      effect: write
      questions:
      - How do I bring archived Jira issues back?
      - Can I unarchive up to a thousand issues at once by key?
      instructions:
      - text: Unarchive the issues {issueIdsOrKeys}.
        slots:
          issueIdsOrKeys: requestBody.issueIdsOrKeys
      - text: 'Restore these archived tickets: {issueIdsOrKeys}.'
        slots:
          issueIdsOrKeys: requestBody.issueIdsOrKeys
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/issue/{issueIdOrKey}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the details of an issue
      effect: read
      questions:
      - What is the current status and assignee of a given ticket?
      - Can I fetch only selected fields of an issue instead of everything?
      instructions:
      - text: Show me issue {issueIdOrKey}.
        slots:
          issueIdOrKey: path.issueIdOrKey
      - text: Get only the fields {fields} for ticket {issueIdOrKey}.
        slots:
          fields: query.fields
          issueIdOrKey: path.issueIdOrKey
      - text: Fetch issue {issueIdOrKey} with the properties {properties} included.
        slots:
          issueIdOrKey: path.issueIdOrKey
          properties: query.properties
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/issue/{issueIdOrKey}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit an existing issue's fields
      effect: write
      questions:
      - How do I change the fields on an issue that already exists?
      - Can I edit a ticket without emailing all of its watchers?
      instructions:
      - text: Update issue {issueIdOrKey} with {fields}.
        slots:
          issueIdOrKey: path.issueIdOrKey
          fields: requestBody.fields
      - text: Edit ticket {issueIdOrKey} to set {fields} and don't notify watchers ({notifyUsers}).
        slots:
          issueIdOrKey: path.issueIdOrKey
          fields: requestBody.fields
          notifyUsers: query.notifyUsers
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/issue/{issueIdOrKey}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an issue
      effect: destructive
      questions:
      - How do I permanently delete a Jira issue?
      - Can I delete an issue that still has subtasks under it?
      instructions:
      - text: Delete issue {issueIdOrKey}.
        slots:
          issueIdOrKey: path.issueIdOrKey
      - text: Delete ticket {issueIdOrKey} along with its subtasks ({deleteSubtasks}).
        slots:
          issueIdOrKey: path.issueIdOrKey
          deleteSubtasks: query.deleteSubtasks
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/issue/{issueIdOrKey}/assignee'].put
  update:
    x-apievangelist-phrasing:
      intent: Assign an issue to a user
      effect: write
      questions:
      - Can I assign a ticket to someone if I only have the Assign issue permission?
      - What happens if I assign an issue without giving an account ID?
      instructions:
      - text: Assign issue {issueIdOrKey} to user {accountId}.
        slots:
          issueIdOrKey: path.issueIdOrKey
          accountId: requestBody.accountId
      - text: Make {accountId} the assignee of {issueIdOrKey}.
        slots:
          accountId: requestBody.accountId
          issueIdOrKey: path.issueIdOrKey
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/issue/{issueIdOrKey}/changelog'].get
  update:
    x-apievangelist-phrasing:
      intent: List the change history of an issue
      effect: read
      questions:
      - Who changed what on a ticket, and when, from oldest to newest?
      - Can I page through the full history of edits on an issue?
      instructions:
      - text: Show the changelog for issue {issueIdOrKey}.
        slots:
          issueIdOrKey: path.issueIdOrKey
      - text: List {maxResults} history entries for {issueIdOrKey} starting at {startAt}.
        slots:
          maxResults: query.maxResults
          issueIdOrKey: path.issueIdOrKey
          startAt: query.startAt
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/issue/{issueIdOrKey}/changelog/list'].post
  update:
    x-apievangelist-phrasing:
      intent: Get specific changelog entries of an issue
      effect: read
      questions:
      - Can I look up particular changelog entries by their IDs rather than the whole history?
      - What exactly changed in a known set of history records on a ticket?
      instructions:
      - text: Get changelogs {changelogIds} for issue {issueIdOrKey}.
        slots:
          changelogIds: requestBody.changelogIds
          issueIdOrKey: path.issueIdOrKey
      - text: Fetch only these history records {changelogIds} from {issueIdOrKey}.
        slots:
          changelogIds: requestBody.changelogIds
          issueIdOrKey: path.issueIdOrKey
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/issue/{issueIdOrKey}/editmeta'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the editable fields for an issue
      effect: read
      questions:
      - Which fields on an existing ticket am I allowed to edit?
      - Can I see hidden or non-editable fields on an issue's edit screen?
      instructions:
      - text: Show the edit screen fields for issue {issueIdOrKey}.
        slots:
          issueIdOrKey: path.issueIdOrKey
      - text: List editable fields for {issueIdOrKey}, including hidden ones ({overrideScreenSecurity}).
        slots:
          issueIdOrKey: path.issueIdOrKey
          overrideScreenSecurity: query.overrideScreenSecurity
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/issue/{issueIdOrKey}/notify'].post
  update:
    x-apievangelist-phrasing:
      intent: Send an email notification about an issue
      effect: write
      questions:
      - Can I email people about a ticket with a custom subject and body?
      - Is it possible to restrict an issue notification to users with certain permissions?
      instructions:
      - text: Email {to} about issue {issueIdOrKey} with subject {subject}.
        slots:
          to: requestBody.to
          issueIdOrKey: path.issueIdOrKey
          subject: requestBody.subject
      - text: Send a notification for {issueIdOrKey} with the message {textBody}.
        slots:
          issueIdOrKey: path.issueIdOrKey
          textBody: requestBody.textBody
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/issue/{issueIdOrKey}/transitions'].get
  update:
    x-apievangelist-phrasing:
      intent: List the transitions available on an issue
      effect: read
      questions:
      - What status changes can I make on a ticket right now?
      - Can I see transitions that are currently blocked by a condition?
      instructions:
      - text: List the available transitions for issue {issueIdOrKey}.
        slots:
          issueIdOrKey: path.issueIdOrKey
      - text: Check whether transition {transitionId} can be performed on {issueIdOrKey}.
        slots:
          transitionId: query.transitionId
          issueIdOrKey: path.issueIdOrKey
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/issue/{issueIdOrKey}/transitions'].post
  update:
    x-apievangelist-phrasing:
      intent: Move an issue through a workflow transition
      effect: write
      questions:
      - How do I move a ticket from In Progress to Done?
      - Can I fill in transition screen fields while changing an issue's status?
      instructions:
      - text: Transition issue {issueIdOrKey} using {transition}.
        slots:
          issueIdOrKey: path.issueIdOrKey
          transition: requestBody.transition
      - text: Apply transition {transition} to {issueIdOrKey} and set {fields} on the transition screen.
        slots:
          transition: requestBody.transition
          issueIdOrKey: path.issueIdOrKey
          fields: requestBody.fields
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/issues/archive/export'].put
  update:
    x-apievangelist-phrasing:
      intent: Export archived issues to a CSV by email
      effect: read
      questions:
      - Can I get a CSV of all the issues that have been archived?
      - Which archived issues did a particular person archive within a date range?
      instructions:
      - text: Export archived issues from projects {projects} to CSV.
        slots:
          projects: requestBody.projects
      - text: Email me a CSV of issues archived by {archivedBy} during {archivedDateRange}.
        slots:
          archivedBy: requestBody.archivedBy
          archivedDateRange: requestBody.archivedDateRange
      method: generated
      generated: '2026-10-01'