# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Canvas LMS REST Roles API
  version: 1.0.0
extends: openapi/canvas-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: 9
- target: $.paths['/v1/accounts/{account_id}/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List an account's roles
      effect: read
      questions:
      - Which custom and built-in roles exist in my account?
      - Can I include roles inherited from parent accounts, or filter to inactive ones?
      instructions:
      - text: List the roles in account {account_id}.
        slots:
          account_id: path.account_id
      - text: Show roles in account {account_id} with state {state}.
        slots:
          account_id: path.account_id
          state: query.state
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/accounts/{account_id}/roles'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom role
      effect: write
      questions:
      - How do I create a custom course-level role like Grader?
      - Can a new role be based on the Teacher or TA enrollment type?
      instructions:
      - text: Create a role labeled {label} in account {account_id}.
        slots:
          label: requestBody.label
          account_id: path.account_id
      - text: Create role {label} in account {account_id} based on {base_role_type}.
        slots:
          label: requestBody.label
          account_id: path.account_id
          base_role_type: requestBody.base_role_type
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/accounts/{account_id}/roles/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one role and its permissions
      effect: read
      questions:
      - What permissions does a particular role have?
      - Can I look up a role's settings by its id?
      instructions:
      - text: Show role {id} in account {account_id}.
        slots:
          id: path.id
          account_id: path.account_id
      - text: Get the permission set of role {role_id} in account {account_id} (path id {id}).
        slots:
          role_id: query.role_id
          account_id: path.account_id
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/accounts/{account_id}/roles/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a role's permissions
      effect: write
      questions:
      - Can I change the permissions on the built-in Teacher role?
      - Is it possible to rename a custom role?
      instructions:
      - text: Rename role {id} in account {account_id} to {label}.
        slots:
          id: path.id
          account_id: path.account_id
          label: requestBody.label
      - text: Update the permissions of role {id} in account {account_id}.
        slots:
          id: path.id
          account_id: path.account_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/accounts/{account_id}/roles/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Deactivate a custom role
      effect: destructive
      questions:
      - What happens to users who already hold a role I deactivate?
      - Can I stop a custom role from being assigned to new people?
      instructions:
      - text: Deactivate role {role_id} in account {account_id} (path id {id}).
        slots:
          role_id: query.role_id
          account_id: path.account_id
          id: path.id
      - text: Retire custom role {id} in account {account_id}, role id {role_id}.
        slots:
          role_id: query.role_id
          account_id: path.account_id
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/accounts/{account_id}/roles/{id}/activate'].post
  update:
    x-apievangelist-phrasing:
      intent: Reactivate an inactive role
      effect: write
      questions:
      - Can I bring back a role I previously deactivated?
      - Once reactivated, can a role be assigned to new users again?
      instructions:
      - text: Reactivate role {role_id} in account {account_id} (path id {id}).
        slots:
          role_id: requestBody.role_id
          account_id: path.account_id
          id: path.id
      - text: Restore inactive role {id} in account {account_id} using role id {role_id}.
        slots:
          role_id: requestBody.role_id
          account_id: path.account_id
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/accounts/{account_id}/roles/permissions'].get
  update:
    x-apievangelist-phrasing:
      intent: List permissions that roles can be granted
      effect: read
      questions:
      - Which permissions can I grant to roles in my account?
      - Can I search the grantable permissions by keyword?
      instructions:
      - text: List the assignable permissions in account {account_id}.
        slots:
          account_id: path.account_id
      - text: Search account {account_id}'s grantable permissions for {search_term}.
        slots:
          account_id: path.account_id
          search_term: query.search_term
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/permissions/{context_type}/{permission}/help'].get
  update:
    x-apievangelist-phrasing:
      intent: Explain what a permission does
      effect: read
      questions:
      - What does a specific Canvas permission actually allow?
      - Is there localized help text for a permission in a course or account context?
      instructions:
      - text: Explain permission {permission} in the {context_type} context.
        slots:
          permission: path.permission
          context_type: path.context_type
      - text: Get the help text for {permission} as it applies to {context_type}.
        slots:
          permission: path.permission
          context_type: path.context_type
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/permissions/groups'].get
  update:
    x-apievangelist-phrasing:
      intent: List permission groups
      effect: read
      questions:
      - How are granular permissions grouped together?
      - Where can I get the labels for each group of granular permissions?
      instructions:
      - text: List the granular permission groups.
      - text: Show each permission group key with its label.
      method: generated
      generated: '2026-10-01'