# 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 Issue properties API
  version: 1.0.0
extends: openapi/jira-issue-properties-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: 8
- target: $.paths['/rest/api/3/issue/properties'].post
  update:
    x-apievangelist-phrasing:
      intent: Set the same properties on many issues
      effect: write
      questions:
      - Can I apply one list of entity properties to thousands of issues in one request?
      - How many properties and issues can a single bulk property list update cover?
      instructions:
      - text: Set properties {properties} on issues {entitiesIds}.
        slots:
          properties: requestBody.properties
          entitiesIds: requestBody.entitiesIds
      - text: Apply the same property list {properties} across issues {entitiesIds} in one go.
        slots:
          properties: requestBody.properties
          entitiesIds: requestBody.entitiesIds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/issue/properties/multi'].post
  update:
    x-apievangelist-phrasing:
      intent: Set different properties per issue in bulk
      effect: write
      questions:
      - How do I give each issue its own property values in a single async request?
      - What's the limit on issues when setting per-issue property values in bulk?
      instructions:
      - text: 'Set these per-issue property values: {issues}.'
        slots:
          issues: requestBody.issues
      - text: Write a different set of properties to each issue in {issues} as a background task.
        slots:
          issues: requestBody.issues
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/issue/properties/{propertyKey}'].put
  update:
    x-apievangelist-phrasing:
      intent: Set one property across many issues
      effect: write
      questions:
      - Can I set a single property key on every issue that matches a filter?
      - Is it possible to compute a property's value with a Jira expression for each issue?
      instructions:
      - text: Set property {propertyKey} to {value} on issues matching {filter}.
        slots:
          propertyKey: path.propertyKey
          value: requestBody.value
          filter: requestBody.filter
      - text: Set property {propertyKey} on many issues using expression {expression}.
        slots:
          propertyKey: path.propertyKey
          expression: requestBody.expression
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/issue/properties/{propertyKey}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one property from many issues
      effect: destructive
      questions:
      - How do I strip a property off lots of issues at once?
      - Can I bulk delete a property only where it currently has a certain value?
      instructions:
      - text: Delete property {propertyKey} from issues {entityIds}.
        slots:
          propertyKey: path.propertyKey
          entityIds: requestBody.entityIds
      - text: Remove property {propertyKey} from every issue where it equals {currentValue}.
        slots:
          propertyKey: path.propertyKey
          currentValue: requestBody.currentValue
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/issue/{issueIdOrKey}/properties'].get
  update:
    x-apievangelist-phrasing:
      intent: List property keys on an issue
      effect: read
      questions:
      - What custom property keys are stored on an issue?
      - Which apps have saved data against a particular issue?
      instructions:
      - text: List the property keys on issue {issueIdOrKey}.
        slots:
          issueIdOrKey: path.issueIdOrKey
      - text: Show every entity property key attached to {issueIdOrKey}.
        slots:
          issueIdOrKey: path.issueIdOrKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/issue/{issueIdOrKey}/properties/{propertyKey}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read one property of an issue
      effect: read
      questions:
      - What value is stored under a given property key on one issue?
      - Can I read an issue's property if issue-level security applies?
      instructions:
      - text: Get property {propertyKey} of issue {issueIdOrKey}.
        slots:
          propertyKey: path.propertyKey
          issueIdOrKey: path.issueIdOrKey
      - text: Read the {propertyKey} value saved on {issueIdOrKey}.
        slots:
          propertyKey: path.propertyKey
          issueIdOrKey: path.issueIdOrKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/issue/{issueIdOrKey}/properties/{propertyKey}'].put
  update:
    x-apievangelist-phrasing:
      intent: Set a property on a single issue
      effect: write
      questions:
      - How do I store custom JSON data against one issue?
      - What's the maximum size of a single issue property value?
      instructions:
      - text: Set property {propertyKey} on issue {issueIdOrKey} to this JSON.
        slots:
          propertyKey: path.propertyKey
          issueIdOrKey: path.issueIdOrKey
      - text: Save this metadata on {issueIdOrKey} under the key {propertyKey}.
        slots:
          issueIdOrKey: path.issueIdOrKey
          propertyKey: path.propertyKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/issue/{issueIdOrKey}/properties/{propertyKey}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a property from a single issue
      effect: destructive
      questions:
      - How do I remove one custom property from a single issue?
      - Which permissions do I need to delete an issue's property?
      instructions:
      - text: Delete property {propertyKey} from issue {issueIdOrKey}.
        slots:
          propertyKey: path.propertyKey
          issueIdOrKey: path.issueIdOrKey
      - text: Clear the {propertyKey} data stored on {issueIdOrKey} only.
        slots:
          propertyKey: path.propertyKey
          issueIdOrKey: path.issueIdOrKey
      method: generated
      generated: '2026-09-26'