# 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 Outcome Results API
  version: 1.0.0
extends: openapi/canvas-outcome-results-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: 6
- target: $.paths['/v1/courses/{course_id}/outcome_results'].get
  update:
    x-apievangelist-phrasing:
      intent: Get learning outcome results for students
      effect: read
      questions:
      - How did each student score against the learning outcomes in my course?
      - Can I pull outcome results for just a few students and outcomes, including hidden ones?
      instructions:
      - text: Get the outcome results for course {course_id}.
        slots:
          course_id: path.course_id
      - text: Get outcome results in course {course_id} for users {user_ids} on outcomes {outcome_ids}.
        slots:
          course_id: path.course_id
          user_ids: query.user_ids
          outcome_ids: query.outcome_ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/courses/{course_id}/assign_outcome_order'].post
  update:
    x-apievangelist-phrasing:
      intent: Save outcome column order in the mastery gradebook
      effect: write
      questions:
      - How do I save the order of outcome columns in the Learning Mastery Gradebook?
      - Can I rearrange which outcomes appear first in my mastery gradebook?
      instructions:
      - text: Save my outcome ordering for the mastery gradebook in course {course_id}.
        slots:
          course_id: path.course_id
      - text: Reorder the outcome columns in course {course_id}'s Learning Mastery Gradebook.
        slots:
          course_id: path.course_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/courses/{course_id}/outcome_rollups'].get
  update:
    x-apievangelist-phrasing:
      intent: Get rolled-up outcome scores per student
      effect: read
      questions:
      - What's each student's overall mastery score per outcome in my course?
      - Can I get a course-wide average of outcome scores instead of per-student rollups?
      instructions:
      - text: Get the outcome rollups for course {course_id}.
        slots:
          course_id: path.course_id
      - text: Get course {course_id} outcome rollups aggregated as {aggregate} using {aggregate_stat}.
        slots:
          course_id: path.course_id
          aggregate: query.aggregate
          aggregate_stat: query.aggregate_stat
      - text: Get outcome rollups in course {course_id} sorted by {sort_by}.
        slots:
          course_id: path.course_id
          sort_by: query.sort_by
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/courses/{course_id}/outcomes/{outcome_id}/contributing_scores'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the scores behind one outcome result
      effect: read
      questions:
      - Which assignment and quiz scores fed into a student's outcome score?
      - Can I include unpublished assignments when looking at what contributed to an outcome?
      instructions:
      - text: Get the contributing scores for outcome {outcome_id} in course {course_id}.
        slots:
          outcome_id: path.outcome_id
          course_id: path.course_id
      - text: Show which assignments contributed to outcome {outcome_id} for users {user_ids} in course {course_id}.
        slots:
          outcome_id: path.outcome_id
          user_ids: query.user_ids
          course_id: path.course_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/courses/{course_id}/outcome_mastery_distribution'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the distribution of students across mastery levels
      effect: read
      questions:
      - How many students fall into each mastery level for every outcome?
      - Can I chart the mastery distribution for all students without paging?
      instructions:
      - text: Get the mastery distribution for course {course_id}.
        slots:
          course_id: path.course_id
      - text: Get the mastery level breakdown in course {course_id} for outcomes {outcome_ids}.
        slots:
          course_id: path.course_id
          outcome_ids: query.outcome_ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/courses/{course_id}/enqueue_outcome_rollup_calculation'].post
  update:
    x-apievangelist-phrasing:
      intent: Queue a recalculation of outcome rollups
      effect: write
      questions:
      - How do I trigger a recalculation of outcome rollups for a course?
      - Can I queue an outcome rollup recalculation for one student?
      instructions:
      - text: Queue an outcome rollup recalculation for course {course_id}.
        slots:
          course_id: path.course_id
      - text: Recalculate outcome rollups in course {course_id} for student {student_uuid}.
        slots:
          course_id: path.course_id
          student_uuid: requestBody.student_uuid
      method: generated
      generated: '2026-10-01'