# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Zendesk Custom Roles API
  version: 1.0.0
extends: openapi/zendesk-custom-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: 5
- target: $.paths['/api/v2/custom_roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List custom agent roles
      effect: read
      questions:
      - What custom roles are defined for agents?
      - Are custom roles only on the Enterprise plan?
      instructions:
      - text: List all custom agent roles.
      - text: Show the custom roles in my account.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/custom_roles'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom agent role
      effect: write
      questions:
      - Can I create a role with limited permissions for contractors?
      - Which agents are allowed to create custom roles?
      instructions:
      - text: Create a custom role for contractors.
      - text: Add a new agent role that can only view tickets.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/custom_roles/{custom_role_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom role
      effect: read
      questions:
      - Where can I see the permissions of one custom role?
      - Can I look up a single agent role's configuration?
      instructions:
      - text: Show this custom role.
      - text: Get the permissions of the contractor role.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/custom_roles/{custom_role_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a custom role
      effect: write
      questions:
      - Can I change the permissions of an existing custom role?
      - Does manage_roles permission let an agent edit roles?
      instructions:
      - text: Update this custom role's permissions.
      - text: Allow the contractor role to edit ticket tags.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/custom_roles/{custom_role_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a custom role
      effect: destructive
      questions:
      - Can I remove a custom role we no longer use?
      - Who is allowed to delete a custom agent role?
      instructions:
      - text: Delete this custom role.
      - text: Remove the old contractor role.
      method: generated
      generated: '2026-09-26'