# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Kinde Roles API
  version: 1.0.0
extends: openapi/kinde-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: 12
- target: $.paths['/account_api/v1/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List the signed-in user's roles
      effect: read
      questions:
      - Which roles does the currently logged-in user hold?
      - Can my app read the signed-in user's roles?
      instructions:
      - text: List my roles.
      - text: Show the current user's roles, {page_size} per page.
        slots:
          page_size: query.page_size
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List all roles
      effect: read
      questions:
      - Which roles are defined in my business?
      - Can I sort the role list by name or ID?
      instructions:
      - text: List every role defined in my account.
      - text: Show all roles sorted by {sort}.
        slots:
          sort: query.sort
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/roles'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a role
      effect: write
      questions:
      - How do I create a new role like admin or editor?
      - Can I make a role the default for new users?
      instructions:
      - text: Create a role {name} with key {key}.
        slots:
          name: requestBody.name
          key: requestBody.key
      - text: Add role {name} described as {description}, assigned by default.
        slots:
          name: requestBody.name
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/roles/{role_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a role
      effect: read
      questions:
      - Can I look up one role by its ID?
      - What does a particular role's definition contain?
      instructions:
      - text: Show role {role_id}.
        slots:
          role_id: path.role_id
      - text: Get the details of role {role_id}.
        slots:
          role_id: path.role_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/roles/{role_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a role
      effect: destructive
      questions:
      - How do I delete a role I no longer use?
      - Can I remove a role definition permanently?
      instructions:
      - text: Delete role {role_id}.
        slots:
          role_id: path.role_id
      - text: Remove the role definition {role_id}.
        slots:
          role_id: path.role_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/roles/{role_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a role
      effect: write
      questions:
      - Can I rename a role or change its key?
      - How do I stop a role being assigned to new users by default?
      instructions:
      - text: Rename role {role_id} to {name} with key {key}.
        slots:
          role_id: path.role_id
          name: requestBody.name
          key: requestBody.key
      - text: 'Update role {role_id}: name {name}, key {key}, default {is_default_role}.'
        slots:
          role_id: path.role_id
          name: requestBody.name
          key: requestBody.key
          is_default_role: requestBody.is_default_role
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/roles/{role_id}/scopes'].get
  update:
    x-apievangelist-phrasing:
      intent: List a role's API scopes
      effect: read
      questions:
      - Which API scopes are attached to a role?
      - Can I see the scopes granted through a role?
      instructions:
      - text: List the scopes on role {role_id}.
        slots:
          role_id: path.role_id
      - text: Show API scopes granted by role {role_id}.
        slots:
          role_id: path.role_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/roles/{role_id}/scopes'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an API scope to a role
      effect: write
      questions:
      - How do I grant an API scope to everyone with a role?
      - Can I attach a scope to a role?
      instructions:
      - text: Add scope {scope_id} to role {role_id}.
        slots:
          scope_id: requestBody.scope_id
          role_id: path.role_id
      - text: Grant API scope {scope_id} through role {role_id}.
        slots:
          scope_id: requestBody.scope_id
          role_id: path.role_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/roles/{role_id}/scopes/{scope_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an API scope from a role
      effect: destructive
      questions:
      - How do I take an API scope off a role?
      - Can I detach a scope from a role without deleting it?
      instructions:
      - text: Remove scope {scope_id} from role {role_id}.
        slots:
          scope_id: path.scope_id
          role_id: path.role_id
      - text: Detach API scope {scope_id} from role {role_id}.
        slots:
          scope_id: path.scope_id
          role_id: path.role_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/roles/{role_id}/permissions'].get
  update:
    x-apievangelist-phrasing:
      intent: List a role's permissions
      effect: read
      questions:
      - Which permissions does a role grant?
      - Can I page through the permissions on a role?
      instructions:
      - text: List the permissions on role {role_id}.
        slots:
          role_id: path.role_id
      - text: Show permissions granted by role {role_id}, sorted by {sort}.
        slots:
          role_id: path.role_id
          sort: query.sort
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/roles/{role_id}/permissions'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a role's permissions
      effect: write
      questions:
      - How do I add or remove several permissions on a role at once?
      - Can I change a role's permission set in one call?
      instructions:
      - text: Update the permissions on role {role_id} to {permissions}.
        slots:
          role_id: path.role_id
          permissions: requestBody.permissions
      - text: Change the permission set for role {role_id}.
        slots:
          role_id: path.role_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/roles/{role_id}/permissions/{permission_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a permission from a role
      effect: destructive
      questions:
      - How do I remove a single permission from a role?
      - Can I revoke one permission from a role?
      instructions:
      - text: Remove permission {permission_id} from role {role_id}.
        slots:
          permission_id: path.permission_id
          role_id: path.role_id
      - text: Revoke permission {permission_id} granted by role {role_id}.
        slots:
          permission_id: path.permission_id
          role_id: path.role_id
      method: generated
      generated: '2026-09-26'