# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Clerk Backend Organization Roles API
  version: 1.0.0
extends: openapi/clerk-com-organization-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: 7
- target: $.paths['/organization_roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List organization roles
      effect: read
      questions:
      - What custom organization roles exist in my instance?
      - Can I search organization roles by name or key?
      instructions:
      - text: List all organization roles.
      - text: Find organization roles matching {query}.
        slots:
          query: query.query
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organization_roles'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an organization role
      effect: write
      questions:
      - How do I define a custom role like billing manager for organizations?
      - What format must an organization role key follow?
      - Can a new role be added to the initial role set?
      instructions:
      - text: Create an organization role {name} with key {key}.
        slots:
          name: requestBody.name
          key: requestBody.key
      - text: Create role {name} ({key}) with permissions {permissions}.
        slots:
          name: requestBody.name
          key: requestBody.key
          permissions: requestBody.permissions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organization_roles/{organization_role_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve an organization role
      effect: read
      questions:
      - How do I see the permissions attached to one organization role?
      - What details does a single organization role have?
      instructions:
      - text: Get organization role {organization_role_id}.
        slots:
          organization_role_id: path.organization_role_id
      - text: Show the permissions of role {organization_role_id}.
        slots:
          organization_role_id: path.organization_role_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organization_roles/{organization_role_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an organization role
      effect: destructive
      questions:
      - How do I delete a custom organization role?
      - Why can't I delete a role that is still assigned to members?
      instructions:
      - text: Delete organization role {organization_role_id}.
        slots:
          organization_role_id: path.organization_role_id
      - text: Remove the unused role {organization_role_id} from the instance.
        slots:
          organization_role_id: path.organization_role_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organization_roles/{organization_role_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an organization role
      effect: write
      questions:
      - How do I rename an organization role or change its description?
      - Can I replace a role's whole permission set at once?
      instructions:
      - text: Rename organization role {organization_role_id} to {name}.
        slots:
          organization_role_id: path.organization_role_id
          name: requestBody.name
      - text: Replace the permissions of role {organization_role_id} with {permissions}.
        slots:
          organization_role_id: path.organization_role_id
          permissions: requestBody.permissions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organization_roles/{organization_role_id}/permissions/{permission_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a permission to an organization role
      effect: write
      questions:
      - How do I grant one extra permission to an existing organization role?
      - Can I attach a single permission to a role without resending all of them?
      instructions:
      - text: Assign permission {permission_id} to role {organization_role_id}.
        slots:
          permission_id: path.permission_id
          organization_role_id: path.organization_role_id
      - text: Give organization role {organization_role_id} the permission {permission_id}.
        slots:
          organization_role_id: path.organization_role_id
          permission_id: path.permission_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organization_roles/{organization_role_id}/permissions/{permission_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a permission from an organization role
      effect: destructive
      questions:
      - How do I take a single permission away from an organization role?
      - Can I revoke one permission from a role and keep the others?
      instructions:
      - text: Remove permission {permission_id} from role {organization_role_id}.
        slots:
          permission_id: path.permission_id
          organization_role_id: path.organization_role_id
      - text: Revoke the permission {permission_id} on organization role {organization_role_id}.
        slots:
          permission_id: path.permission_id
          organization_role_id: path.organization_role_id
      method: generated
      generated: '2026-09-26'