# 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 Dashboards API
  version: 1.0.0
extends: openapi/jira-dashboards-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: 17
- target: $.paths['/rest/api/3/dashboard'].get
  update:
    x-apievangelist-phrasing:
      intent: List dashboards I own or that are shared with me
      effect: read
      questions:
      - Which Jira dashboards do I own or have shared with me?
      - Can I list only my favorite dashboards?
      instructions:
      - text: List all the dashboards I own or can see.
      - text: Show my {filter} dashboards, starting at result {startAt}.
        slots:
          filter: query.filter
          startAt: query.startAt
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/dashboard'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new dashboard
      effect: write
      questions:
      - How do I create a new dashboard with its own share and edit permissions?
      - What do I need to supply to set up a brand new dashboard?
      instructions:
      - text: Create a dashboard named {name} shared as {sharePermissions} and editable by {editPermissions}.
        slots:
          name: requestBody.name
          sharePermissions: requestBody.sharePermissions
          editPermissions: requestBody.editPermissions
      - text: Make a new dashboard called {name} with the description {description}, editable by {editPermissions} and shared as {sharePermissions}.
        slots:
          name: requestBody.name
          description: requestBody.description
          editPermissions: requestBody.editPermissions
          sharePermissions: requestBody.sharePermissions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/dashboard/bulk/edit'].put
  update:
    x-apievangelist-phrasing:
      intent: Change owner or permissions on many dashboards
      effect: write
      questions:
      - Can I change the owner of up to 100 dashboards in one request?
      - Is there a way to update sharing permissions on lots of dashboards at once?
      instructions:
      - text: Apply the bulk action {action} to dashboards {entityIds}.
        slots:
          action: requestBody.action
          entityIds: requestBody.entityIds
      - text: Transfer ownership of dashboards {entityIds} using action {action} with owner details {changeOwnerDetails}.
        slots:
          entityIds: requestBody.entityIds
          action: requestBody.action
          changeOwnerDetails: requestBody.changeOwnerDetails
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/dashboard/gadgets'].get
  update:
    x-apievangelist-phrasing:
      intent: List gadgets that can be added to dashboards
      effect: read
      questions:
      - What gadgets are available to add to a dashboard?
      - Which gadget types does my site offer for dashboards?
      instructions:
      - text: List every gadget I could add to a dashboard.
      - text: Show the catalog of available dashboard gadgets.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/dashboard/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search dashboards by name, owner, group or project
      effect: read
      questions:
      - How do I find a dashboard by its name?
      - Can I search for dashboards owned by a particular user or shared with a group?
      - Is it possible to find archived dashboards or ones shared with a specific project?
      instructions:
      - text: Search dashboards named {dashboardName}.
        slots:
          dashboardName: query.dashboardName
      - text: Find dashboards owned by account {accountId}, sorted by {orderBy}.
        slots:
          accountId: query.accountId
          orderBy: query.orderBy
      - text: Search for dashboards shared with project {projectId} that have status {status}.
        slots:
          projectId: query.projectId
          status: query.status
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/dashboard/{dashboardId}/gadget'].get
  update:
    x-apievangelist-phrasing:
      intent: List the gadgets on a dashboard
      effect: read
      questions:
      - Which gadgets are currently on my dashboard?
      - Can I filter a dashboard's gadgets by module key or gadget ID?
      instructions:
      - text: List the gadgets on dashboard {dashboardId}.
        slots:
          dashboardId: path.dashboardId
      - text: Show gadgets with module key {moduleKey} on dashboard {dashboardId}.
        slots:
          moduleKey: query.moduleKey
          dashboardId: path.dashboardId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/dashboard/{dashboardId}/gadget'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a gadget to a dashboard
      effect: write
      questions:
      - How do I put a new gadget on a dashboard?
      - Can I choose the color and position when adding a gadget?
      instructions:
      - text: Add the gadget with module key {moduleKey} to dashboard {dashboardId}.
        slots:
          moduleKey: requestBody.moduleKey
          dashboardId: path.dashboardId
      - text: Add a {color} gadget titled {title} from {uri} to dashboard {dashboardId}.
        slots:
          color: requestBody.color
          title: requestBody.title
          uri: requestBody.uri
          dashboardId: path.dashboardId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/dashboard/{dashboardId}/gadget/{gadgetId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Change a gadget's title, position or color
      effect: write
      questions:
      - Can I rename a gadget that's already on a dashboard?
      - How do I move or recolor an existing dashboard gadget?
      instructions:
      - text: Rename gadget {gadgetId} on dashboard {dashboardId} to {title}.
        slots:
          gadgetId: path.gadgetId
          dashboardId: path.dashboardId
          title: requestBody.title
      - text: Change gadget {gadgetId} on dashboard {dashboardId} to color {color} at position {position}.
        slots:
          gadgetId: path.gadgetId
          dashboardId: path.dashboardId
          color: requestBody.color
          position: requestBody.position
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/dashboard/{dashboardId}/gadget/{gadgetId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a gadget from a dashboard
      effect: destructive
      questions:
      - How do I take a gadget off a dashboard?
      - What happens to the other gadgets in the column when I remove one?
      instructions:
      - text: Remove gadget {gadgetId} from dashboard {dashboardId}.
        slots:
          gadgetId: path.gadgetId
          dashboardId: path.dashboardId
      - text: Delete the gadget {gadgetId} sitting on dashboard {dashboardId}.
        slots:
          gadgetId: path.gadgetId
          dashboardId: path.dashboardId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/dashboard/{dashboardId}/items/{itemId}/properties'].get
  update:
    x-apievangelist-phrasing:
      intent: List property keys stored on a dashboard item
      effect: read
      questions:
      - Which property keys has my app stored on a dashboard item?
      - Can I see all the custom property names set on a dashboard gadget item?
      instructions:
      - text: List the property keys on item {itemId} of dashboard {dashboardId}.
        slots:
          itemId: path.itemId
          dashboardId: path.dashboardId
      - text: Show which properties exist for dashboard {dashboardId} item {itemId}.
        slots:
          dashboardId: path.dashboardId
          itemId: path.itemId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/dashboard/{dashboardId}/items/{itemId}/properties/{propertyKey}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read one property value on a dashboard item
      effect: read
      questions:
      - How do I read the value my app stored under a key on a dashboard item?
      - What value does a given property hold on a dashboard gadget item?
      instructions:
      - text: Get property {propertyKey} from item {itemId} on dashboard {dashboardId}.
        slots:
          propertyKey: path.propertyKey
          itemId: path.itemId
          dashboardId: path.dashboardId
      - text: Read the value of {propertyKey} for dashboard {dashboardId} item {itemId}.
        slots:
          propertyKey: path.propertyKey
          dashboardId: path.dashboardId
          itemId: path.itemId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/dashboard/{dashboardId}/items/{itemId}/properties/{propertyKey}'].put
  update:
    x-apievangelist-phrasing:
      intent: Store custom data on a dashboard item
      effect: write
      questions:
      - Can my app save custom data against a dashboard gadget item?
      - How do I set or overwrite a property value on a dashboard item?
      instructions:
      - text: Set property {propertyKey} on item {itemId} of dashboard {dashboardId}.
        slots:
          propertyKey: path.propertyKey
          itemId: path.itemId
          dashboardId: path.dashboardId
      - text: Save a value under key {propertyKey} for dashboard {dashboardId} item {itemId}.
        slots:
          propertyKey: path.propertyKey
          dashboardId: path.dashboardId
          itemId: path.itemId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/dashboard/{dashboardId}/items/{itemId}/properties/{propertyKey}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a property from a dashboard item
      effect: destructive
      questions:
      - How do I remove a stored property from a dashboard item?
      - What permission do I need to delete a dashboard item property?
      instructions:
      - text: Delete property {propertyKey} from item {itemId} on dashboard {dashboardId}.
        slots:
          propertyKey: path.propertyKey
          itemId: path.itemId
          dashboardId: path.dashboardId
      - text: Clear the {propertyKey} property off dashboard {dashboardId} item {itemId}.
        slots:
          propertyKey: path.propertyKey
          dashboardId: path.dashboardId
          itemId: path.itemId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/dashboard/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a single dashboard's details
      effect: read
      questions:
      - How do I look up one specific dashboard by its ID?
      - Can I fetch a dashboard that someone shared with me?
      instructions:
      - text: Get dashboard {id}.
        slots:
          id: path.id
      - text: Show me the details of dashboard {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/dashboard/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a dashboard's name, description and permissions
      effect: write
      questions:
      - How do I rename a dashboard I own?
      - Does updating a dashboard replace all of its details, including sharing?
      instructions:
      - text: Rename dashboard {id} to {name}, keeping share permissions {sharePermissions} and edit permissions {editPermissions}.
        slots:
          id: path.id
          name: requestBody.name
          sharePermissions: requestBody.sharePermissions
          editPermissions: requestBody.editPermissions
      - text: Update dashboard {id} with description {description}, name {name}, share {sharePermissions}, edit {editPermissions}.
        slots:
          id: path.id
          description: requestBody.description
          name: requestBody.name
          sharePermissions: requestBody.sharePermissions
          editPermissions: requestBody.editPermissions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/dashboard/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a dashboard
      effect: destructive
      questions:
      - How do I delete a dashboard I no longer need?
      - Can I delete a dashboard that someone else owns?
      instructions:
      - text: Delete dashboard {id}.
        slots:
          id: path.id
      - text: Permanently remove my dashboard {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/dashboard/{id}/copy'].post
  update:
    x-apievangelist-phrasing:
      intent: Copy an existing dashboard
      effect: write
      questions:
      - Can I duplicate an existing dashboard under a new name?
      - How do I clone a dashboard that's shared with me?
      instructions:
      - text: Copy dashboard {id} as {name}, shared as {sharePermissions} and editable by {editPermissions}.
        slots:
          id: path.id
          name: requestBody.name
          sharePermissions: requestBody.sharePermissions
          editPermissions: requestBody.editPermissions
      - text: Duplicate dashboard {id} into a new one called {name} with edit {editPermissions} and share {sharePermissions}.
        slots:
          id: path.id
          name: requestBody.name
          editPermissions: requestBody.editPermissions
          sharePermissions: requestBody.sharePermissions
      method: generated
      generated: '2026-09-26'