# 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 Groups API
  version: 1.0.0
extends: openapi/canvas-groups-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: 25
- target: $.paths['/v1/groups/{group_id}/files'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a file upload to a group
      effect: write
      questions:
      - How do I upload a file into a student group's files?
      - Can I add an avatar image file to a group before setting it as the avatar?
      instructions:
      - text: Start uploading a file to group {group_id}.
        slots:
          group_id: path.group_id
      - text: Request an upload slot for a new file in group {group_id}'s files.
        slots:
          group_id: path.group_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/group_categories/{group_category_id}/groups'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a group inside a group set
      effect: write
      questions:
      - How do I add a new group to an existing group set in a course?
      - Can I give a group in a category its own SIS group ID?
      instructions:
      - text: Create a group named {name} in group category {group_category_id}.
        slots:
          name: requestBody.name
          group_category_id: path.group_category_id
      - text: Add group {name} to group set {group_category_id} with join level {join_level}.
        slots:
          name: requestBody.name
          group_category_id: path.group_category_id
          join_level: requestBody.join_level
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/self/groups'].get
  update:
    x-apievangelist-phrasing:
      intent: List groups I belong to
      effect: read
      questions:
      - Which groups am I a member of?
      - Can I see only my course groups, not account groups?
      instructions:
      - text: List all my active groups.
      - text: Show my groups in {context_type} contexts only.
        slots:
          context_type: query.context_type
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/accounts/{account_id}/groups'].get
  update:
    x-apievangelist-phrasing:
      intent: List groups in an account
      effect: read
      questions:
      - What groups exist across a whole Canvas account?
      - Can an admin list only the account-level groups they belong to?
      instructions:
      - text: List the groups in account {account_id}.
        slots:
          account_id: path.account_id
      - text: Show account {account_id} groups with only own groups set to {only_own_groups}.
        slots:
          account_id: path.account_id
          only_own_groups: query.only_own_groups
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/courses/{course_id}/groups'].get
  update:
    x-apievangelist-phrasing:
      intent: List groups in a course
      effect: read
      questions:
      - Which student groups have been set up in my course?
      - Can I filter a course's groups by collaboration state?
      instructions:
      - text: List the groups in course {course_id}.
        slots:
          course_id: path.course_id
      - text: Show course {course_id} groups with collaboration state {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}/bulk_user_tags'].get
  update:
    x-apievangelist-phrasing:
      intent: Get differentiation tags for many users
      effect: read
      questions:
      - Which differentiation tags are assigned to each student in a course?
      - Can I look up tag memberships for a list of users in one call?
      instructions:
      - text: Get the user tags for users {user_ids} in course {course_id}.
        slots:
          user_ids: query.user_ids
          course_id: path.course_id
      - text: Map every student in course {course_id} to their differentiation tag IDs.
        slots:
          course_id: path.course_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/groups/{group_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a single group
      effect: read
      questions:
      - How do I look up one group's details by ID?
      - Will I get an error if I fetch a group I don't have rights to see?
      instructions:
      - text: Get group {group_id}.
        slots:
          group_id: path.group_id
      - text: Show group {group_id} including {include}.
        slots:
          group_id: path.group_id
          include: query.include
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/groups/{group_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a group's name, settings or members
      effect: write
      questions:
      - Can I rename a group or change its description?
      - How do I set a group's avatar after uploading the image?
      - Is it possible to replace a group's full member list in one update?
      instructions:
      - text: Rename group {group_id} to {name}.
        slots:
          group_id: path.group_id
          name: requestBody.name
      - text: Set the avatar of group {group_id} to file {avatar_id}.
        slots:
          group_id: path.group_id
          avatar_id: requestBody.avatar_id
      - text: Replace the members of group {group_id} with {members}.
        slots:
          group_id: path.group_id
          members: requestBody.members
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/groups/{group_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a group
      effect: destructive
      questions:
      - What happens to members when a group is deleted?
      - Can I remove a group I no longer need?
      instructions:
      - text: Delete group {group_id}.
        slots:
          group_id: path.group_id
      - text: Remove group {group_id} and all of its members.
        slots:
          group_id: path.group_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/groups'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a community group
      effect: write
      questions:
      - How do I create a community group that isn't tied to a course?
      - Can I make a public community group anyone can join?
      instructions:
      - text: Create a community group named {name}.
        slots:
          name: requestBody.name
      - text: Create community group {name} described as {description} with join level {join_level}.
        slots:
          name: requestBody.name
          description: requestBody.description
          join_level: requestBody.join_level
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/groups/{group_id}/invite'].post
  update:
    x-apievangelist-phrasing:
      intent: Invite people to a group by email
      effect: write
      questions:
      - Can I invite people to join a group using their email addresses?
      - How do I send group invitations to several people?
      instructions:
      - text: Invite {invitees} to group {group_id}.
        slots:
          invitees: requestBody.invitees
          group_id: path.group_id
      - text: Email a join invitation for group {group_id} to {invitees}.
        slots:
          group_id: path.group_id
          invitees: requestBody.invitees
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/groups/{group_id}/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List users in a group
      effect: read
      questions:
      - Who are the people in a particular group?
      - Can I leave inactive users out of a group's user list?
      instructions:
      - text: List users in group {group_id}.
        slots:
          group_id: path.group_id
      - text: Search group {group_id} for users matching {search_term}.
        slots:
          group_id: path.group_id
          search_term: query.search_term
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/groups/{group_id}/users'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk remove members from a group
      effect: destructive
      questions:
      - Can I remove many members from a group at once by user ID?
      - Is there a way to strip every course student out of a differentiation tag group?
      instructions:
      - text: Remove users {user_ids} from group {group_id}.
        slots:
          user_ids: query.user_ids
          group_id: path.group_id
      - text: Remove all course students from tag group {group_id} except {exclude_user_ids}, with all in group course {all_in_group_course}.
        slots:
          group_id: path.group_id
          exclude_user_ids: query.exclude_user_ids
          all_in_group_course: query.all_in_group_course
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/groups/{group_id}/preview_html'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview processed HTML for a group
      effect: read
      questions:
      - Can I preview how HTML will render inside a group's pages?
      - What does group content processing do to my HTML?
      instructions:
      - text: Preview how {html} renders in group {group_id}.
        slots:
          html: requestBody.html
          group_id: path.group_id
      - text: 'Run this HTML through group {group_id}''s processing and show me: {html}'
        slots:
          group_id: path.group_id
          html: requestBody.html
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/groups/{group_id}/activity_stream'].get
  update:
    x-apievangelist-phrasing:
      intent: Show my activity stream for a group
      effect: read
      questions:
      - What's been happening recently in one of my groups?
      - Can I see just a group's discussions and announcements feed?
      instructions:
      - text: Show my activity stream for group {group_id}.
        slots:
          group_id: path.group_id
      - text: List recent activity in group {group_id}.
        slots:
          group_id: path.group_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/groups/{group_id}/activity_stream/summary'].get
  update:
    x-apievangelist-phrasing:
      intent: Summarize my group activity stream
      effect: read
      questions:
      - How many unread items do I have in a group, by type?
      - Is there a count-only summary of a group's activity?
      instructions:
      - text: Summarize my activity stream counts for group {group_id}.
        slots:
          group_id: path.group_id
      - text: Give me unread activity totals in group {group_id}.
        slots:
          group_id: path.group_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/groups/{group_id}/permissions'].get
  update:
    x-apievangelist-phrasing:
      intent: Check my permissions in a group
      effect: read
      questions:
      - Am I allowed to post discussions in this group?
      - Which group-level rights does my user have?
      instructions:
      - text: Check my permissions in group {group_id}.
        slots:
          group_id: path.group_id
      - text: Tell me whether I have {permissions} in group {group_id}.
        slots:
          permissions: query.permissions
          group_id: path.group_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/groups/{group_id}/memberships'].get
  update:
    x-apievangelist-phrasing:
      intent: List a group's memberships
      effect: read
      questions:
      - Who has a pending request to join my group?
      - Can I list group memberships filtered by state, like invited or accepted?
      instructions:
      - text: List memberships in group {group_id}.
        slots:
          group_id: path.group_id
      - text: Show group {group_id} memberships in states {filter_states}.
        slots:
          group_id: path.group_id
          filter_states: query.filter_states
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/groups/{group_id}/memberships'].post
  update:
    x-apievangelist-phrasing:
      intent: Join or add someone to a group
      effect: write
      questions:
      - How do I join a group or request to join it?
      - Can I add a specific user to a group as a member?
      - Can I bulk add all course students to a differentiation tag?
      instructions:
      - text: Add user {user_id} to group {group_id}.
        slots:
          user_id: requestBody.user_id
          group_id: path.group_id
      - text: Add members {members} to group {group_id}.
        slots:
          members: requestBody.members
          group_id: path.group_id
      - text: Request to join group {group_id}.
        slots:
          group_id: path.group_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/groups/{group_id}/memberships/{membership_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a group membership by membership ID
      effect: read
      questions:
      - Can I look up a group membership record using its membership ID?
      - What state is a particular membership in?
      instructions:
      - text: Get membership {membership_id} in group {group_id}.
        slots:
          membership_id: path.membership_id
          group_id: path.group_id
      - text: Show the status of group {group_id} membership {membership_id}.
        slots:
          group_id: path.group_id
          membership_id: path.membership_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/groups/{group_id}/memberships/{membership_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Accept or moderate a membership by ID
      effect: write
      questions:
      - How do I accept a pending join request using the membership ID?
      - Can I make a member a group moderator by their membership record?
      instructions:
      - text: Accept membership {membership_id} in group {group_id} by setting state {workflow_state}.
        slots:
          membership_id: path.membership_id
          group_id: path.group_id
          workflow_state: requestBody.workflow_state
      - text: Set moderator to {moderator} for membership {membership_id} in group {group_id}.
        slots:
          moderator: requestBody.moderator
          membership_id: path.membership_id
          group_id: path.group_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/groups/{group_id}/memberships/{membership_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Leave a group by membership ID
      effect: destructive
      questions:
      - Can I leave a group I joined using my membership ID?
      - Why can't I leave some teacher-created course groups?
      instructions:
      - text: Leave group {group_id} by removing membership {membership_id}.
        slots:
          group_id: path.group_id
          membership_id: path.membership_id
      - text: Remove membership {membership_id} from group {group_id}.
        slots:
          membership_id: path.membership_id
          group_id: path.group_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/groups/{group_id}/users/{user_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a group membership by user ID
      effect: read
      questions:
      - Is a given user a member of this group, and in what state?
      - Can I look up a membership using the user's ID instead of the membership ID?
      instructions:
      - text: Get the membership of user {user_id} in group {group_id}.
        slots:
          user_id: path.user_id
          group_id: path.group_id
      - text: Check whether user {user_id} belongs to group {group_id}.
        slots:
          user_id: path.user_id
          group_id: path.group_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/groups/{group_id}/users/{user_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Accept or moderate a membership by user
      effect: write
      questions:
      - How do I accept a user's request to join my group using their user ID?
      - Can I grant moderator rights to a specific user in a group?
      instructions:
      - text: Accept user {user_id}'s request to join group {group_id} with state {workflow_state}.
        slots:
          user_id: path.user_id
          group_id: path.group_id
          workflow_state: requestBody.workflow_state
      - text: Set moderator to {moderator} for user {user_id} in group {group_id}.
        slots:
          moderator: requestBody.moderator
          user_id: path.user_id
          group_id: path.group_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/groups/{group_id}/users/{user_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a user from a group by user ID
      effect: destructive
      questions:
      - Can I remove a particular user from a group by their user ID?
      - How does a user leave a group when I only know their user ID?
      instructions:
      - text: Remove user {user_id} from group {group_id}.
        slots:
          user_id: path.user_id
          group_id: path.group_id
      - text: Have user {user_id} leave group {group_id}.
        slots:
          user_id: path.user_id
          group_id: path.group_id
      method: generated
      generated: '2026-10-01'