# 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 Dashboards API
  version: 1.0.0
extends: openapi/atlassian-dashboards-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: 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:
      - How do I list all the Jira dashboards I own or that were shared with me?
      - Can I show only my favorite dashboards?
      instructions:
      - text: List every dashboard I can see.
      - text: Show my dashboards filtered to {filter}.
        slots:
          filter: query.filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/dashboard'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a dashboard
      effect: write
      questions:
      - How do I create a new Jira dashboard and decide who can see and edit it?
      - What sharing and edit permissions does a new dashboard need?
      instructions:
      - text: Create a dashboard named {name}.
        slots:
          name: requestBody.name
      - text: Create dashboard {name} described as {description} with share permissions {sharePermissions} and edit permissions {editPermissions}.
        slots:
          name: requestBody.name
          description: requestBody.description
          sharePermissions: requestBody.sharePermissions
          editPermissions: requestBody.editPermissions
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/dashboard/bulk/edit'].put
  update:
    x-apievangelist-phrasing:
      intent: Bulk edit up to 100 dashboards
      effect: write
      questions:
      - Can I change the owner or permissions of many dashboards at once?
      - What's the limit on how many dashboards a bulk edit can touch?
      instructions:
      - text: Apply bulk action {action} to dashboards {entityIds}.
        slots:
          action: requestBody.action
          entityIds: requestBody.entityIds
      - text: Transfer ownership of dashboards {entityIds} using {changeOwnerDetails}.
        slots:
          entityIds: requestBody.entityIds
          changeOwnerDetails: requestBody.changeOwnerDetails
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/dashboard/gadgets'].get
  update:
    x-apievangelist-phrasing:
      intent: List gadgets available for dashboards
      effect: read
      questions:
      - Which gadgets can be added to Jira dashboards on this site?
      - What's the full catalog of dashboard gadgets I can choose from?
      instructions:
      - text: List all gadgets available to add to dashboards.
      - text: Show me the gadget catalog for dashboards.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/dashboard/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search dashboards by name, owner or group
      effect: read
      questions:
      - How do I find dashboards with a particular name?
      - Can I search for dashboards owned by a specific user or shared with a group?
      - Is it possible to find archived dashboards for a 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 dashboards shared with group {groupId} that are {status}.
        slots:
          groupId: query.groupId
          status: query.status
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/dashboard/{dashboardId}/gadget'].get
  update:
    x-apievangelist-phrasing:
      intent: List gadgets on a dashboard
      effect: read
      questions:
      - What gadgets are currently on a given dashboard?
      - Can I look up dashboard gadgets by module key or URI?
      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-10-01'
- 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 set a gadget's color and position when adding it?
      instructions:
      - text: Add gadget {moduleKey} to dashboard {dashboardId}.
        slots:
          moduleKey: requestBody.moduleKey
          dashboardId: path.dashboardId
      - text: Add a gadget titled {title} in {color} at {position} on dashboard {dashboardId}.
        slots:
          title: requestBody.title
          color: requestBody.color
          position: requestBody.position
          dashboardId: path.dashboardId
      method: generated
      generated: '2026-10-01'
- 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:
      - How do I rename or recolor a gadget already on my dashboard?
      - Can I move an existing gadget to another spot on the dashboard?
      instructions:
      - text: Rename gadget {gadgetId} on dashboard {dashboardId} to {title}.
        slots:
          gadgetId: path.gadgetId
          dashboardId: path.dashboardId
          title: requestBody.title
      - text: Move gadget {gadgetId} on dashboard {dashboardId} to {position}.
        slots:
          gadgetId: path.gadgetId
          dashboardId: path.dashboardId
          position: requestBody.position
      method: generated
      generated: '2026-10-01'
- 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 one is removed?
      instructions:
      - text: Remove gadget {gadgetId} from dashboard {dashboardId}.
        slots:
          gadgetId: path.gadgetId
          dashboardId: path.dashboardId
      - text: Delete gadget {gadgetId} off dashboard {dashboardId}.
        slots:
          gadgetId: path.gadgetId
          dashboardId: path.dashboardId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/dashboard/{dashboardId}/items/{itemId}/properties'].get
  update:
    x-apievangelist-phrasing:
      intent: List property keys on a dashboard item
      effect: read
      questions:
      - What custom property keys are stored on a dashboard item?
      - Which properties has my app saved against a dashboard gadget item?
      instructions:
      - text: List property keys for item {itemId} on dashboard {dashboardId}.
        slots:
          itemId: path.itemId
          dashboardId: path.dashboardId
      - text: Show which properties exist on dashboard {dashboardId} item {itemId}.
        slots:
          dashboardId: path.dashboardId
          itemId: path.itemId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/dashboard/{dashboardId}/items/{itemId}/properties/{propertyKey}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a dashboard item property
      effect: read
      questions:
      - How do I read the value my app stored on a dashboard item?
      - Can I fetch one named property from a dashboard gadget item?
      instructions:
      - text: Get property {propertyKey} on item {itemId} of dashboard {dashboardId}.
        slots:
          propertyKey: path.propertyKey
          itemId: path.itemId
          dashboardId: path.dashboardId
      - text: Read the {propertyKey} value from dashboard item {itemId}.
        slots:
          propertyKey: path.propertyKey
          itemId: path.itemId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/dashboard/{dashboardId}/items/{itemId}/properties/{propertyKey}'].put
  update:
    x-apievangelist-phrasing:
      intent: Store a property on a dashboard item
      effect: write
      questions:
      - How can my app save custom data against a dashboard item?
      - Can I overwrite an existing dashboard item property value?
      instructions:
      - text: Set property {propertyKey} on item {itemId} of dashboard {dashboardId}.
        slots:
          propertyKey: path.propertyKey
          itemId: path.itemId
          dashboardId: path.dashboardId
      - text: Save my app data under {propertyKey} on dashboard item {itemId}.
        slots:
          propertyKey: path.propertyKey
          itemId: path.itemId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/dashboard/{dashboardId}/items/{itemId}/properties/{propertyKey}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a dashboard item property
      effect: destructive
      questions:
      - How do I remove a stored property from a dashboard item?
      - Who is allowed to delete dashboard item properties?
      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 item {itemId}.
        slots:
          propertyKey: path.propertyKey
          itemId: path.itemId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/dashboard/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a dashboard
      effect: read
      questions:
      - How do I fetch the details of one dashboard by its id?
      - Can I view 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-10-01'
- target: $.paths['/rest/api/3/dashboard/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a dashboard's details
      effect: write
      questions:
      - How do I rename a dashboard or change who it's shared with?
      - Does updating a dashboard replace all of its details?
      instructions:
      - text: Rename dashboard {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Update dashboard {id} to share with {sharePermissions} and allow edits by {editPermissions}.
        slots:
          id: path.id
          sharePermissions: requestBody.sharePermissions
          editPermissions: requestBody.editPermissions
      method: generated
      generated: '2026-10-01'
- 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 own?
      - Can I delete a dashboard 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-10-01'
- target: $.paths['/rest/api/3/dashboard/{id}/copy'].post
  update:
    x-apievangelist-phrasing:
      intent: Copy a dashboard
      effect: write
      questions:
      - How do I duplicate an existing dashboard?
      - Can I give the copy of a dashboard a new name and permissions?
      instructions:
      - text: Copy dashboard {id} as {name}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Clone dashboard {id} with share permissions {sharePermissions}.
        slots:
          id: path.id
          sharePermissions: requestBody.sharePermissions
      method: generated
      generated: '2026-10-01'