# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for TextQL v2 Roles API
  version: 1.0.0
extends: openapi/textql-roles-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: 3
- target: $.paths['/v2/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List roles in the organization
      effect: read
      questions:
      - Which roles exist in my organization, including built-in ones?
      - What RBAC roles can I assign to people?
      instructions:
      - text: List all roles in my organization.
      - text: Show the system and custom roles defined.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/roles'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom role
      effect: write
      questions:
      - How do I create a custom role for my team?
      - Does a newly created role start with any permissions?
      instructions:
      - text: Create a role named {name}.
        slots:
          name: requestBody.name
      - text: Create custom role {name} with description {description}.
        slots:
          name: requestBody.name
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/roles/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a role's name or model settings
      effect: write
      questions:
      - Can I restrict which models a role is allowed to use?
      - How do I rename a role or change its default model?
      instructions:
      - text: Rename role {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Set role {id}'s default model to {model} and allow only {allowed}.
        slots:
          id: path.id
          model: requestBody.default_model_id
          allowed: requestBody.allowed_model_ids
      method: generated
      generated: '2026-10-01'