# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Snyk Tenant Role API
  version: 1.0.0
extends: openapi/snyk-tenantrole-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['/tenants/{tenant_id}/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List roles available in a tenant
      effect: read
      questions:
      - Which roles are available in my tenant?
      - Can I list only the custom roles I'm allowed to assign?
      instructions:
      - text: List the roles in tenant {tenant_id}.
        slots:
          tenant_id: path.tenant_id
      - text: List tenant {tenant_id} roles where custom is {custom}.
        slots:
          tenant_id: path.tenant_id
          custom: query.custom
      - text: Find tenant {tenant_id} roles named {name}.
        slots:
          tenant_id: path.tenant_id
          name: query.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tenants/{tenant_id}/roles'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom tenant role
      effect: write
      questions:
      - How do I create a custom role for my tenant?
      - Can I define my own set of permissions as a tenant role?
      instructions:
      - text: Create a custom role in tenant {tenant_id}.
        slots:
          tenant_id: path.tenant_id
      - text: Add a new read-only auditor role to tenant {tenant_id}.
        slots:
          tenant_id: path.tenant_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tenants/{tenant_id}/roles/{role_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a tenant role and its permissions
      effect: read
      questions:
      - What permissions does a particular tenant role grant?
      - Can I tell whether any users are assigned to a tenant role?
      instructions:
      - text: Get role {role_id} in tenant {tenant_id}.
        slots:
          role_id: path.role_id
          tenant_id: path.tenant_id
      - text: Show tenant {tenant_id} role {role_id} with has_users_assigned {has_users_assigned}.
        slots:
          tenant_id: path.tenant_id
          role_id: path.role_id
          has_users_assigned: query.has_users_assigned
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tenants/{tenant_id}/roles/{role_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a custom tenant role
      effect: destructive
      questions:
      - Can I delete a custom role from my tenant?
      - What removes a tenant role I no longer need?
      instructions:
      - text: Delete role {role_id} from tenant {tenant_id}.
        slots:
          role_id: path.role_id
          tenant_id: path.tenant_id
      - text: Remove custom tenant {tenant_id} role {role_id}.
        slots:
          tenant_id: path.tenant_id
          role_id: path.role_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tenants/{tenant_id}/roles/{role_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a custom tenant role
      effect: write
      questions:
      - Can I change the permissions on an existing custom tenant role?
      - Is there a force option when updating a tenant role that users already hold?
      instructions:
      - text: Update role {role_id} in tenant {tenant_id}.
        slots:
          role_id: path.role_id
          tenant_id: path.tenant_id
      - text: Update tenant {tenant_id} role {role_id} with force set to {force}.
        slots:
          tenant_id: path.tenant_id
          role_id: path.role_id
          force: query.force
      method: generated
      generated: '2026-09-26'