# 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 Calendar Events API
  version: 1.0.0
extends: openapi/canvas-calendar-events-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: 12
- target: $.paths['/v1/calendar_events'].get
  update:
    x-apievangelist-phrasing:
      intent: List my calendar events
      effect: read
      questions:
      - What's on my Canvas calendar between two dates?
      - Can I list only assignments, or only events, for certain courses?
      - How do I include undated events in my calendar listing?
      instructions:
      - text: List my calendar events from {start_date} to {end_date}.
        slots:
          start_date: query.start_date
          end_date: query.end_date
      - text: Show my {type} calendar items for {context_codes}.
        slots:
          type: query.type
          context_codes: query.context_codes
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/calendar_events'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a calendar event
      effect: write
      questions:
      - How do I add an event to a course calendar?
      - Can I make a recurring calendar event that repeats weekly?
      instructions:
      - text: Create a calendar event {title} on {context_code} starting {start_at}.
        slots:
          title: requestBody.calendar_event[title]
          context_code: requestBody.calendar_event[context_code]
          start_at: requestBody.calendar_event[start_at]
      - text: Schedule {title} for {context_code} from {start_at} to {end_at} at {location_name}.
        slots:
          title: requestBody.calendar_event[title]
          context_code: requestBody.calendar_event[context_code]
          start_at: requestBody.calendar_event[start_at]
          end_at: requestBody.calendar_event[end_at]
          location_name: requestBody.calendar_event[location_name]
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/calendar_events'].get
  update:
    x-apievangelist-phrasing:
      intent: List another user's calendar events
      effect: read
      questions:
      - As a parent observer, can I see my student's calendar?
      - How do I list a specific user's events and assignments in a date range?
      instructions:
      - text: List calendar events for user {user_id}.
        slots:
          user_id: path.user_id
      - text: Show user {user_id}'s calendar from {start_date} to {end_date}.
        slots:
          user_id: path.user_id
          start_date: query.start_date
          end_date: query.end_date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/calendar_events/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one calendar event or assignment
      effect: read
      questions:
      - How do I see the full details of a single calendar entry?
      - Can I look up one calendar event by its id?
      instructions:
      - text: Show calendar event {id}.
        slots:
          id: path.id
      - text: Get the details of calendar entry {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/calendar_events/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a calendar event
      effect: write
      questions:
      - Can I move an existing event to a new time or location?
      - How do I change every event in a recurring series instead of just one?
      instructions:
      - text: Move calendar event {id} to start at {start_at}.
        slots:
          id: path.id
          start_at: requestBody.calendar_event[start_at]
      - text: Rename event {id} to {title}, applying to {which} in the series.
        slots:
          id: path.id
          title: requestBody.calendar_event[title]
          which: requestBody.which
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/calendar_events/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a calendar event
      effect: destructive
      questions:
      - How do I cancel an event and tell attendees why?
      - Can I delete just one occurrence of a recurring event?
      instructions:
      - text: Delete calendar event {id}.
        slots:
          id: path.id
      - text: Cancel event {id} with reason {cancel_reason}.
        slots:
          id: path.id
          cancel_reason: query.cancel_reason
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/calendar_events/{id}/reservations'].post
  update:
    x-apievangelist-phrasing:
      intent: Reserve an appointment time slot
      effect: write
      questions:
      - How do I book an open office-hours slot?
      - Can I swap my existing booking for a different time slot?
      instructions:
      - text: Reserve time slot {id}.
        slots:
          id: path.id
      - text: 'Book slot {id} with comment {comments}, cancelling my existing booking: {cancel_existing}.'
        slots:
          id: path.id
          comments: requestBody.comments
          cancel_existing: requestBody.cancel_existing
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/calendar_events/{id}/reservations/{participant_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Reserve a time slot for a specific participant
      effect: write
      questions:
      - Can an instructor book an appointment slot on behalf of a particular student?
      - How do I reserve a slot for a named participant or group?
      instructions:
      - text: Reserve slot {id} for participant {participant_id}.
        slots:
          id: path.id
          participant_id: path.participant_id
      - text: Book time slot {id} on behalf of {participant_id} with note {comments}.
        slots:
          id: path.id
          participant_id: path.participant_id
          comments: requestBody.comments
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/calendar_events/save_enabled_account_calendars'].post
  update:
    x-apievangelist-phrasing:
      intent: Choose which account calendars I see
      effect: write
      questions:
      - How do I turn on account-level calendars in my calendar view?
      - Can I mark the account calendars feature as seen?
      instructions:
      - text: Enable account calendars {enabled_account_calendars} for me.
        slots:
          enabled_account_calendars: requestBody.enabled_account_calendars
      - text: 'Save my enabled account calendars and mark the feature seen: {mark_feature_as_seen}.'
        slots:
          mark_feature_as_seen: requestBody.mark_feature_as_seen
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/courses/{course_id}/calendar_events/timetable'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a course's timetable
      effect: read
      questions:
      - What weekly class schedule was set for a course?
      - Can I read back the timetable a course was given?
      instructions:
      - text: Get the timetable for course {course_id}.
        slots:
          course_id: path.course_id
      - text: Show course {course_id}'s weekly meeting schedule.
        slots:
          course_id: path.course_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/courses/{course_id}/calendar_events/timetable'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate a course's weekly timetable
      effect: write
      questions:
      - Can I auto-generate class meetings like Monday and Wednesday at 2pm for a course?
      - How do I set a section's weekdays and meeting times as a timetable?
      instructions:
      - text: Set course {course_id}'s timetable to meet on {weekdays} from {start_time} to {end_time}.
        slots:
          course_id: path.course_id
          weekdays: requestBody.timetables[course_section_id][weekdays]
          start_time: requestBody.timetables[course_section_id][start_time]
          end_time: requestBody.timetables[course_section_id][end_time]
      - text: Generate weekly timetable events for course {course_id} at {location_name}.
        slots:
          course_id: path.course_id
          location_name: requestBody.timetables[course_section_id][location_name]
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/courses/{course_id}/calendar_events/timetable_events'].post
  update:
    x-apievangelist-phrasing:
      intent: Write timetable events directly
      effect: write
      questions:
      - Can I push my own list of class meeting events into a course timetable instead of a weekly pattern?
      - How do I sync explicit timetable events for one course section?
      instructions:
      - text: Write timetable events {events} directly to course {course_id}.
        slots:
          events: requestBody.events
          course_id: path.course_id
      - text: Replace section {course_section_id}'s timetable events in course {course_id} with {events}.
        slots:
          course_section_id: requestBody.course_section_id
          course_id: path.course_id
          events: requestBody.events
      method: generated
      generated: '2026-10-01'