# 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 Group Categories API
  version: 1.0.0
extends: openapi/canvas-group-categories-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: 16
- target: $.paths['/v1/accounts/{account_id}/group_categories'].get
  update:
    x-apievangelist-phrasing:
      intent: List group sets in an account
      effect: read
      questions:
      - What group categories exist at the account level in Canvas?
      - Can I list only the non-collaborative group sets for a sub-account?
      instructions:
      - text: List the group categories in account {account_id}.
        slots:
          account_id: path.account_id
      - text: Show account {account_id} group sets with collaboration state {collaboration_state}.
        slots:
          account_id: path.account_id
          collaboration_state: query.collaboration_state
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/accounts/{account_id}/group_categories'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a group set in an account
      effect: write
      questions:
      - How do I set up a new group category across an entire account?
      - Can an account-wide group set allow self signup or cap group size?
      instructions:
      - text: Create an account group category named {name} in account {account_id}.
        slots:
          name: requestBody.name
          account_id: path.account_id
      - text: Add group set {name} to account {account_id} with a limit of {group_limit} members per group.
        slots:
          name: requestBody.name
          account_id: path.account_id
          group_limit: requestBody.group_limit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/courses/{course_id}/group_categories'].get
  update:
    x-apievangelist-phrasing:
      intent: List group sets in a course
      effect: read
      questions:
      - Which group sets has my instructor created in this course?
      - Are differentiation tags listed among a course's group categories?
      instructions:
      - text: List group categories for course {course_id}.
        slots:
          course_id: path.course_id
      - text: Show the course {course_id} group sets filtered by {collaboration_state}.
        slots:
          course_id: path.course_id
          collaboration_state: query.collaboration_state
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/courses/{course_id}/group_categories'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a group set in a course
      effect: write
      questions:
      - Can I create project groups for my class and have students split automatically?
      - Is it possible to auto-create a fixed number of groups when making a course group set?
      instructions:
      - text: Create a course group set called {name} in {course_id}.
        slots:
          name: requestBody.name
          course_id: path.course_id
      - text: Make group category {name} in course {course_id} and split students into {split_group_count} groups.
        slots:
          name: requestBody.name
          course_id: path.course_id
          split_group_count: requestBody.split_group_count
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/group_categories/{group_category_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one group set
      effect: read
      questions:
      - Can I look up the settings of a specific group category?
      - Does a group set have self signup or auto leader turned on?
      instructions:
      - text: Get group category {group_category_id}.
        slots:
          group_category_id: path.group_category_id
      - text: Show the configuration of group set {group_category_id}.
        slots:
          group_category_id: path.group_category_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/group_categories/{group_category_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a group set's settings
      effect: write
      questions:
      - Can I rename a group category or change its member limit later?
      - Is turning on automatic group leaders for an existing set possible?
      instructions:
      - text: Rename group category {group_category_id} to {name}.
        slots:
          group_category_id: path.group_category_id
          name: requestBody.name
      - text: Set auto leader to {auto_leader} on group set {group_category_id}.
        slots:
          auto_leader: requestBody.auto_leader
          group_category_id: path.group_category_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/group_categories/{group_category_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a group set and its groups
      effect: destructive
      questions:
      - Does deleting a group category also delete every group inside it?
      - Which group sets are protected from deletion?
      instructions:
      - text: Delete group category {group_category_id} and all its groups.
        slots:
          group_category_id: path.group_category_id
      - text: Remove group set {group_category_id}.
        slots:
          group_category_id: path.group_category_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/courses/{course_id}/group_categories/bulk_manage_differentiation_tag'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk create, rename or delete differentiation tags
      effect: write
      questions:
      - Can I create, rename and delete several differentiation tags in one request?
      - Do bulk differentiation tag changes roll back if one fails?
      instructions:
      - text: Apply differentiation tag operations {operations} to tag set {group_category} in course {course_id}.
        slots:
          operations: requestBody.operations
          group_category: requestBody.group_category
          course_id: path.course_id
      - text: In course {course_id}, bulk update the differentiation tags under {group_category} with {operations}.
        slots:
          course_id: path.course_id
          group_category: requestBody.group_category
          operations: requestBody.operations
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/courses/{course_id}/group_categories/differentiation_tag_candidate_count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count students eligible for a differentiation tag
      effect: read
      questions:
      - How many students in my course could be added to a differentiation tag?
      - Can I exclude certain users when counting differentiation tag candidates?
      instructions:
      - text: Count students in course {course_id} eligible for differentiation tag {differentiation_tag_id}.
        slots:
          course_id: path.course_id
          differentiation_tag_id: query.differentiation_tag_id
      - text: Tell me how many course {course_id} students with role {enrollment_role_id} could be tagged.
        slots:
          course_id: path.course_id
          enrollment_role_id: query.enrollment_role_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/courses/{course_id}/group_categories/import_tags'].post
  update:
    x-apievangelist-phrasing:
      intent: Import differentiation tags from CSV
      effect: write
      questions:
      - Can I upload a CSV to create differentiation tags for my course?
      - What file format does the differentiation tag import expect?
      instructions:
      - text: Import differentiation tags into course {course_id} from {attachment}.
        slots:
          course_id: path.course_id
          attachment: requestBody.attachment
      - text: Create course {course_id} differentiation tags using the CSV {attachment}.
        slots:
          course_id: path.course_id
          attachment: requestBody.attachment
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/group_categories/{group_category_id}/import'].post
  update:
    x-apievangelist-phrasing:
      intent: Import groups into a group set from CSV
      effect: write
      questions:
      - Can I bulk-create groups inside a group set by uploading a spreadsheet?
      - Is importing group memberships from a CSV supported?
      instructions:
      - text: Import groups into group category {group_category_id} from {attachment}.
        slots:
          group_category_id: path.group_category_id
          attachment: requestBody.attachment
      - text: Load the CSV {attachment} to build groups in set {group_category_id}.
        slots:
          attachment: requestBody.attachment
          group_category_id: path.group_category_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/group_categories/{group_category_id}/groups'].get
  update:
    x-apievangelist-phrasing:
      intent: List the groups in a group set
      effect: read
      questions:
      - Which groups belong to a particular group category?
      - Can I page through all the groups created under one set?
      instructions:
      - text: List the groups in group category {group_category_id}.
        slots:
          group_category_id: path.group_category_id
      - text: Show every group under set {group_category_id}.
        slots:
          group_category_id: path.group_category_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/group_categories/{group_category_id}/export'].get
  update:
    x-apievangelist-phrasing:
      intent: Export a group set's groups and members as CSV
      effect: read
      questions:
      - Can I download a CSV of who is in each group of a group set?
      - Is the group membership export in a format I can re-import?
      instructions:
      - text: Export groups and users in category {group_category_id} to CSV.
        slots:
          group_category_id: path.group_category_id
      - text: Download the membership spreadsheet for group set {group_category_id}.
        slots:
          group_category_id: path.group_category_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/courses/{course_id}/group_categories/export_tags'].get
  update:
    x-apievangelist-phrasing:
      intent: Export a course's differentiation tags and users
      effect: read
      questions:
      - Can I get a CSV of which students carry which differentiation tags in a course?
      - Is there an export of tag assignments ready to re-import?
      instructions:
      - text: Export differentiation tags and their users for course {course_id}.
        slots:
          course_id: path.course_id
      - text: Download the course {course_id} tag membership CSV.
        slots:
          course_id: path.course_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/group_categories/{group_category_id}/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List users in a group set
      effect: read
      questions:
      - Which students in a group set haven't been placed in a group yet?
      - Can I search the members of a group category by name?
      instructions:
      - text: List users in group category {group_category_id}.
        slots:
          group_category_id: path.group_category_id
      - text: Show unassigned students in group set {group_category_id}.
        slots:
          group_category_id: path.group_category_id
      - text: Search group set {group_category_id} members for {search_term}.
        slots:
          group_category_id: path.group_category_id
          search_term: query.search_term
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/group_categories/{group_category_id}/assign_unassigned_members'].post
  update:
    x-apievangelist-phrasing:
      intent: Spread unassigned students evenly across groups
      effect: write
      questions:
      - Can Canvas automatically place leftover students into existing groups?
      - Does auto-assigning group members run in the background or right away?
      instructions:
      - text: Assign all unassigned members of group category {group_category_id} to groups.
        slots:
          group_category_id: path.group_category_id
      - text: Evenly distribute leftover students in set {group_category_id}, synchronously {sync}.
        slots:
          group_category_id: path.group_category_id
          sync: requestBody.sync
      method: generated
      generated: '2026-10-01'