# 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 Role Sets API
  version: 1.0.0
extends: openapi/clerk-com-role-sets-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['/role_sets'].get
  update:
    x-apievangelist-phrasing:
      intent: List role sets
      effect: read
      questions:
      - Which role sets exist in my instance?
      - Can I search role sets by name and change their sort order?
      instructions:
      - text: List all role sets.
      - text: Search role sets for {query}.
        slots:
          query: query.query
      method: generated
      generated: '2026-09-26'
- target: $.paths['/role_sets'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a role set
      effect: write
      questions:
      - How do I group organization roles into a new role set?
      - Does a role set need a default role and a creator role?
      instructions:
      - text: Create role set {name} with roles {roles}, default role {default_role_key} and creator role {creator_role_key}.
        slots:
          name: requestBody.name
          roles: requestBody.roles
          default_role_key: requestBody.default_role_key
          creator_role_key: requestBody.creator_role_key
      - text: Create role set {name} keyed {key} with roles {roles}, default {default_role_key}, creator {creator_role_key}.
        slots:
          name: requestBody.name
          key: requestBody.key
          roles: requestBody.roles
          default_role_key: requestBody.default_role_key
          creator_role_key: requestBody.creator_role_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/role_sets/{role_set_key_or_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a role set
      effect: read
      questions:
      - How do I see which roles are in a role set?
      - Can I look up a role set by its key instead of its ID?
      instructions:
      - text: Show role set {role_set_key_or_id}.
        slots:
          role_set_key_or_id: path.role_set_key_or_id
      - text: List the roles inside role set {role_set_key_or_id}.
        slots:
          role_set_key_or_id: path.role_set_key_or_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/role_sets/{role_set_key_or_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a role set's settings
      effect: write
      questions:
      - How do I rename a role set or change its description?
      - Can I change which role new organization members get by default?
      instructions:
      - text: Rename role set {role_set_key_or_id} to {name}.
        slots:
          role_set_key_or_id: path.role_set_key_or_id
          name: requestBody.name
      - text: Set the default role of role set {role_set_key_or_id} to {default_role_key}.
        slots:
          role_set_key_or_id: path.role_set_key_or_id
          default_role_key: requestBody.default_role_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/role_sets/{role_set_key_or_id}/replace'].post
  update:
    x-apievangelist-phrasing:
      intent: Replace a role set and migrate organizations
      effect: destructive
      questions:
      - How do I retire a role set and move its organizations to another one?
      - Can I map old roles to new roles when replacing a role set?
      instructions:
      - text: Replace role set {role_set_key_or_id} with {dest_role_set_key}.
        slots:
          role_set_key_or_id: path.role_set_key_or_id
          dest_role_set_key: requestBody.dest_role_set_key
      - text: Migrate organizations from role set {role_set_key_or_id} to {dest_role_set_key} using mappings {reassignment_mappings}.
        slots:
          role_set_key_or_id: path.role_set_key_or_id
          dest_role_set_key: requestBody.dest_role_set_key
          reassignment_mappings: requestBody.reassignment_mappings
      method: generated
      generated: '2026-09-26'
- target: $.paths['/role_sets/{role_set_key_or_id}/roles'].post
  update:
    x-apievangelist-phrasing:
      intent: Add roles to a role set
      effect: write
      questions:
      - How do I add more roles to an existing role set?
      - Can I update the creator role at the same time as adding roles?
      instructions:
      - text: Add roles {role_keys} to role set {role_set_key_or_id}.
        slots:
          role_keys: requestBody.role_keys
          role_set_key_or_id: path.role_set_key_or_id
      - text: Add roles {role_keys} to role set {role_set_key_or_id} and make {creator_role_key} the creator role.
        slots:
          role_keys: requestBody.role_keys
          role_set_key_or_id: path.role_set_key_or_id
          creator_role_key: requestBody.creator_role_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/role_sets/{role_set_key_or_id}/roles/replace'].post
  update:
    x-apievangelist-phrasing:
      intent: Swap one role for another in a role set
      effect: destructive
      questions:
      - How do I remove a role from a role set and move its members to a different role?
      - Are members reassigned automatically when a role in a role set is replaced?
      instructions:
      - text: In role set {role_set_key_or_id}, replace role {role_key} with {to_role_key}.
        slots:
          role_set_key_or_id: path.role_set_key_or_id
          role_key: requestBody.role_key
          to_role_key: requestBody.to_role_key
      - text: Retire role {role_key} in role set {role_set_key_or_id} and move its members to {to_role_key}.
        slots:
          role_key: requestBody.role_key
          role_set_key_or_id: path.role_set_key_or_id
          to_role_key: requestBody.to_role_key
      method: generated
      generated: '2026-09-26'