# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Kibana Roles API
  version: 1.0.0
extends: openapi/elk-stack-roles-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: 5
- target: $.paths['/api/security/role'].get
  update:
    x-apievangelist-phrasing:
      intent: List all Kibana roles
      effect: read
      questions:
      - What roles are defined in Kibana?
      - Can I list roles with deprecated privileges replaced by their current names?
      instructions:
      - text: List all Kibana roles.
      - text: Show every role with replaceDeprecatedPrivileges {replaceDeprecatedPrivileges}.
        slots:
          replaceDeprecatedPrivileges: query.replaceDeprecatedPrivileges
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/security/role/{name}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Kibana role
      effect: read
      questions:
      - How do I see the privileges granted by one Kibana role?
      - Which Elasticsearch and Kibana privileges does a named role have?
      instructions:
      - text: Get Kibana role {name}.
        slots:
          name: path.name
      - text: Show the privileges in role {name}.
        slots:
          name: path.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/security/role/{name}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or update a Kibana role
      effect: write
      questions:
      - How do I create a role granting read access to certain indices and Kibana features?
      - Can I make the request fail if a role with that name already exists?
      instructions:
      - text: Create role {name} with Elasticsearch privileges {elasticsearch}.
        slots:
          name: path.name
          elasticsearch: requestBody.elasticsearch
      - text: Update role {name} with index privileges {elasticsearch} and Kibana privileges {kibana}.
        slots:
          name: path.name
          elasticsearch: requestBody.elasticsearch
          kibana: requestBody.kibana
      - text: Create role {name} only if new, using createOnly {createOnly} and privileges {elasticsearch}.
        slots:
          name: path.name
          createOnly: query.createOnly
          elasticsearch: requestBody.elasticsearch
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/security/role/{name}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a Kibana role
      effect: destructive
      questions:
      - How do I delete a Kibana role by name?
      - Can I remove a custom role nobody uses anymore?
      instructions:
      - text: Delete Kibana role {name}.
        slots:
          name: path.name
      - text: Remove the custom role {name}.
        slots:
          name: path.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/security/roles'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or update several Kibana roles at once
      effect: write
      questions:
      - Can I create or update multiple roles in a single request?
      - How do I sync a whole set of role definitions into Kibana at once?
      instructions:
      - text: Bulk create or update roles {roles}.
        slots:
          roles: requestBody.roles
      - text: 'Apply these role definitions in one request: {roles}.'
        slots:
          roles: requestBody.roles
      method: generated
      generated: '2026-09-26'