# 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 Custom Gradebook Columns API
  version: 1.0.0
extends: openapi/canvas-custom-gradebook-columns-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}/custom_gradebook_columns'].get
  update:
    x-apievangelist-phrasing:
      intent: List custom gradebook columns
      effect: read
      questions:
      - What custom columns have been added to a course gradebook?
      - Can I include hidden custom gradebook columns in the list?
      instructions:
      - text: List custom gradebook columns in course {course_id}.
        slots:
          course_id: path.course_id
      - text: List custom columns in course {course_id} with include hidden {include_hidden}.
        slots:
          course_id: path.course_id
          include_hidden: query.include_hidden
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/courses/{course_id}/custom_gradebook_columns'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a custom gradebook column
      effect: write
      questions:
      - How do I add a notes column to the gradebook?
      - Can I create a custom gradebook column that's read-only or hidden?
      instructions:
      - text: Create a custom gradebook column titled {title} in course {course_id}.
        slots:
          title: requestBody.column[title]
          course_id: path.course_id
      - text: Add a teacher notes column {title} to course {course_id} with teacher notes {teacher_notes}.
        slots:
          title: requestBody.column[title]
          course_id: path.course_id
          teacher_notes: requestBody.column[teacher_notes]
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/courses/{course_id}/custom_gradebook_columns/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a custom gradebook column
      effect: write
      questions:
      - Can I rename or hide an existing custom gradebook column?
      - Which settings of a custom column can be edited after creation?
      instructions:
      - text: Update custom column {id} in course {course_id}.
        slots:
          id: path.id
          course_id: path.course_id
      - text: Edit the settings of gradebook column {id} in course {course_id}.
        slots:
          id: path.id
          course_id: path.course_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/courses/{course_id}/custom_gradebook_columns/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a custom gradebook column
      effect: destructive
      questions:
      - Does deleting a custom gradebook column also delete the data in it?
      - How do I permanently remove a custom column from the gradebook?
      instructions:
      - text: Delete custom gradebook column {id} in course {course_id}.
        slots:
          id: path.id
          course_id: path.course_id
      - text: Permanently remove column {id} and its entries from course {course_id}.
        slots:
          id: path.id
          course_id: path.course_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/courses/{course_id}/custom_gradebook_columns/reorder'].post
  update:
    x-apievangelist-phrasing:
      intent: Reorder custom gradebook columns
      effect: write
      questions:
      - Can I change the order custom columns appear in the gradebook?
      - How do I put my notes column before the others?
      instructions:
      - text: Reorder the custom columns in course {course_id} to {order}.
        slots:
          course_id: path.course_id
          order: requestBody.order
      - text: Arrange course {course_id}'s gradebook columns in order {order}.
        slots:
          course_id: path.course_id
          order: requestBody.order
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/courses/{course_id}/custom_gradebook_columns/{id}/data'].get
  update:
    x-apievangelist-phrasing:
      intent: List entries in a custom column
      effect: read
      questions:
      - What has been entered for each student in a custom gradebook column?
      - Why don't students without data show up in a column's entries?
      instructions:
      - text: List entries for custom column {id} in course {course_id}.
        slots:
          id: path.id
          course_id: path.course_id
      - text: Show the per-student values in gradebook column {id} of course {course_id}.
        slots:
          id: path.id
          course_id: path.course_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/courses/{course_id}/custom_gradebook_columns/{id}/data/{user_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Set one student's custom column entry
      effect: write
      questions:
      - How do I set a note for a single student in a custom column?
      - Can I update one student's value in a gradebook column?
      instructions:
      - text: Set column {id} for student {user_id} in course {course_id} to {content}.
        slots:
          id: path.id
          user_id: path.user_id
          course_id: path.course_id
          content: requestBody.column_data[content]
      - text: Write {content} in custom column {id} for user {user_id}, course {course_id}.
        slots:
          content: requestBody.column_data[content]
          id: path.id
          user_id: path.user_id
          course_id: path.course_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/courses/{course_id}/custom_gradebook_column_data'].put
  update:
    x-apievangelist-phrasing:
      intent: Bulk set custom column entries
      effect: write
      questions:
      - Can I fill in custom column values for many students in one request?
      - Is there a bulk way to update several custom columns at once?
      instructions:
      - text: Bulk update custom column data in course {course_id} with {column_data}.
        slots:
          course_id: path.course_id
          column_data: requestBody.column_data
      - text: 'Apply these column entries to course {course_id}''s gradebook: {column_data}'
        slots:
          course_id: path.course_id
          column_data: requestBody.column_data
      method: generated
      generated: '2026-10-01'