# 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 Avatars API
  version: 1.0.0
extends: openapi/jira-avatars-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: 7
- target: $.paths['/rest/api/3/avatar/{type}/system'].get
  update:
    x-apievangelist-phrasing:
      intent: List built-in system avatars by type
      effect: read
      questions:
      - Which built-in avatars does Jira ship for projects, users or priorities?
      - Can I browse the stock system icons for issue types?
      instructions:
      - text: List the system avatars for type {type}.
        slots:
          type: path.type
      - text: Show Jira's stock {type} avatars.
        slots:
          type: path.type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/universal_avatar/type/{type}/owner/{entityId}'].get
  update:
    x-apievangelist-phrasing:
      intent: List system and custom avatars for an item
      effect: read
      questions:
      - What avatars, including custom uploads, are available for a specific project?
      - Which icons could I pick for a given issue type or priority?
      instructions:
      - text: List the avatars available for {type} {entityId}.
        slots:
          type: path.type
          entityId: path.entityId
      - text: Show both system and custom avatars I can use for {type} {entityId}.
        slots:
          type: path.type
          entityId: path.entityId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/universal_avatar/type/{type}/owner/{entityId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a custom avatar for a project, issue type or priority
      effect: write
      questions:
      - How do I upload a custom avatar image for a project or priority?
      - Can I crop an uploaded avatar to a square region?
      instructions:
      - text: Upload this image as a custom avatar for {type} {entityId} cropped to {size}.
        slots:
          type: path.type
          entityId: path.entityId
          size: query.size
      - text: Load a {type} avatar for {entityId}, cropping a {size} square starting at x {x}, y {y}.
        slots:
          type: path.type
          entityId: path.entityId
          size: query.size
          x: query.x
          y: query.y
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/universal_avatar/type/{type}/owner/{owningObjectId}/avatar/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a custom avatar
      effect: destructive
      questions:
      - How do I remove a custom avatar from a project or issue type?
      - Who is allowed to delete an uploaded avatar?
      instructions:
      - text: Delete avatar {id} from {type} {owningObjectId}.
        slots:
          id: path.id
          type: path.type
          owningObjectId: path.owningObjectId
      - text: Remove the uploaded {type} avatar {id} belonging to {owningObjectId}.
        slots:
          type: path.type
          id: path.id
          owningObjectId: path.owningObjectId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/universal_avatar/view/type/{type}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the default avatar image for a type
      effect: read
      questions:
      - Where can I download the default image used for new projects or priorities?
      - Can I get the default avatar image in a particular size or format?
      instructions:
      - text: Download the default {type} avatar image.
        slots:
          type: path.type
      - text: Get the default {type} avatar as {format} at size {size}.
        slots:
          type: path.type
          format: query.format
          size: query.size
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/universal_avatar/view/type/{type}/avatar/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Download an avatar image by its ID
      effect: read
      questions:
      - How do I fetch the actual image file for a known avatar ID?
      - Can I request an avatar image as PNG instead of its original format?
      instructions:
      - text: Download {type} avatar image {id}.
        slots:
          type: path.type
          id: path.id
      - text: Get avatar {id} of type {type} rendered as {format}.
        slots:
          id: path.id
          type: path.type
          format: query.format
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/universal_avatar/view/type/{type}/owner/{entityId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Download the current avatar image of an item
      effect: read
      questions:
      - What image is a particular project currently using as its avatar?
      - Can I pull the icon a specific issue type displays right now?
      instructions:
      - text: Download the current avatar image of {type} {entityId}.
        slots:
          type: path.type
          entityId: path.entityId
      - text: Get the icon {type} {entityId} is showing, at size {size}.
        slots:
          type: path.type
          entityId: path.entityId
          size: query.size
      method: generated
      generated: '2026-09-26'