# 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 Moderated Grading API
  version: 1.0.0
extends: openapi/canvas-moderated-grading-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: 8
- target: $.paths['/v1/courses/{course_id}/assignments/{assignment_id}/moderated_students'].get
  update:
    x-apievangelist-phrasing:
      intent: List students picked for moderation
      effect: read
      questions:
      - Which students' work has been selected for moderated grading on an assignment?
      - Can I see the moderation set for a moderated assignment?
      instructions:
      - text: List students selected for moderation on assignment {assignment_id} in course {course_id}.
        slots:
          assignment_id: path.assignment_id
          course_id: path.course_id
      - text: Show the moderation set for assignment {assignment_id} in course {course_id}.
        slots:
          assignment_id: path.assignment_id
          course_id: path.course_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/courses/{course_id}/assignments/{assignment_id}/moderated_students'].post
  update:
    x-apievangelist-phrasing:
      intent: Add students to the moderation set
      effect: write
      questions:
      - How do I choose which students get a second grader on a moderated assignment?
      - Can I add several students to moderation at once?
      instructions:
      - text: Select students {student_ids} for moderation on assignment {assignment_id} in course {course_id}.
        slots:
          student_ids: requestBody.student_ids
          assignment_id: path.assignment_id
          course_id: path.course_id
      - text: Add {student_ids} to the moderation set of assignment {assignment_id} in course {course_id}.
        slots:
          student_ids: requestBody.student_ids
          assignment_id: path.assignment_id
          course_id: path.course_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/courses/{course_id}/assignments/{assignment_id}/provisional_grades/bulk_select'].put
  update:
    x-apievangelist-phrasing:
      intent: Choose many provisional grades at once
      effect: write
      questions:
      - As final grader, can I pick the provisional grades for many students in one go?
      - Who is allowed to bulk select provisional grades?
      instructions:
      - text: Bulk select provisional grades on assignment {assignment_id} in course {course_id}.
        slots:
          assignment_id: path.assignment_id
          course_id: path.course_id
      - text: Choose the winning provisional grades for several students on assignment {assignment_id} in course {course_id}.
        slots:
          assignment_id: path.assignment_id
          course_id: path.course_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/courses/{course_id}/assignments/{assignment_id}/provisional_grades/status'].get
  update:
    x-apievangelist-phrasing:
      intent: Check if a student needs provisional grades
      effect: read
      questions:
      - Does a student's submission still need provisional grades?
      - How can a grader tell whether a named student needs another provisional grade?
      instructions:
      - text: Check provisional grade status for student {student_id} on assignment {assignment_id} in course {course_id}.
        slots:
          student_id: query.student_id
          assignment_id: path.assignment_id
          course_id: path.course_id
      - text: Does student {student_id} still need provisional grading on assignment {assignment_id} in course {course_id}.
        slots:
          student_id: query.student_id
          assignment_id: path.assignment_id
          course_id: path.course_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/courses/{course_id}/assignments/{assignment_id}/provisional_grades/{provisional_grade_id}/select'].put
  update:
    x-apievangelist-phrasing:
      intent: Select a provisional grade for a submission
      effect: write
      questions:
      - How does the final grader choose which provisional grade a student receives?
      - Can an admin pick one grader's score over another for a submission?
      instructions:
      - text: Select provisional grade {provisional_grade_id} on assignment {assignment_id} in course {course_id}.
        slots:
          provisional_grade_id: path.provisional_grade_id
          assignment_id: path.assignment_id
          course_id: path.course_id
      - text: Use provisional grade {provisional_grade_id} as the student's grade for assignment {assignment_id} in course {course_id}.
        slots:
          provisional_grade_id: path.provisional_grade_id
          assignment_id: path.assignment_id
          course_id: path.course_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/courses/{course_id}/assignments/{assignment_id}/provisional_grades/publish'].post
  update:
    x-apievangelist-phrasing:
      intent: Publish selected provisional grades
      effect: write
      questions:
      - How do I release moderated grades to students once they are chosen?
      - Can provisional grades be published again after they've been published once?
      instructions:
      - text: Publish the provisional grades for assignment {assignment_id} in course {course_id} now.
        slots:
          assignment_id: path.assignment_id
          course_id: path.course_id
      - text: Release the selected moderated grades on assignment {assignment_id} in course {course_id} immediately.
        slots:
          assignment_id: path.assignment_id
          course_id: path.course_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/courses/{course_id}/assignments/{assignment_id}/provisional_grades/publish_async'].post
  update:
    x-apievangelist-phrasing:
      intent: Publish provisional grades in the background
      effect: write
      questions:
      - For a large class, can moderated grades be published as a background job?
      - Is there a non-blocking way to publish provisional grades?
      instructions:
      - text: Publish provisional grades for assignment {assignment_id} in course {course_id} as a background job.
        slots:
          assignment_id: path.assignment_id
          course_id: path.course_id
      - text: Queue an asynchronous grade publish for moderated assignment {assignment_id} in course {course_id}.
        slots:
          assignment_id: path.assignment_id
          course_id: path.course_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/courses/{course_id}/assignments/{assignment_id}/anonymous_provisional_grades/status'].get
  update:
    x-apievangelist-phrasing:
      intent: Check provisional status for an anonymous student
      effect: read
      questions:
      - With anonymous grading on, can I check if a submission needs provisional grades?
      - How do I check grading status using a student's anonymous id?
      instructions:
      - text: Look up anonymized grading needs of {anonymous_id} on assignment {assignment_id} in course {course_id}.
        slots:
          anonymous_id: query.anonymous_id
          assignment_id: path.assignment_id
          course_id: path.course_id
      - text: Does anonymous submission {anonymous_id} need more grading on assignment {assignment_id} in course {course_id}.
        slots:
          anonymous_id: query.anonymous_id
          assignment_id: path.assignment_id
          course_id: path.course_id
      method: generated
      generated: '2026-10-01'