# 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 Poll Sessions API
  version: 1.0.0
extends: openapi/canvas-poll-sessions-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: 9
- target: $.paths['/v1/polls/{poll_id}/poll_sessions'].get
  update:
    x-apievangelist-phrasing:
      intent: List sessions of a poll
      effect: read
      questions:
      - How many times has this poll been run in class?
      - Which sessions exist for one of my polls?
      instructions:
      - text: List the sessions for poll {poll_id}.
        slots:
          poll_id: path.poll_id
      - text: Show every time poll {poll_id} has been run.
        slots:
          poll_id: path.poll_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/polls/{poll_id}/poll_sessions'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a new session of a poll for a course
      effect: write
      questions:
      - How do I run a poll for a specific course or section?
      - Can I make the poll results public to students when I create a session?
      instructions:
      - text: Create a session of poll {poll_id} for course {course_id}.
        slots:
          poll_id: path.poll_id
          course_id: requestBody.poll_sessions[course_id]
      - text: Run poll {poll_id} with public results set to {has_public_results} for students in course {course_id}.
        slots:
          poll_id: path.poll_id
          has_public_results: requestBody.poll_sessions[has_public_results]
          course_id: requestBody.poll_sessions[course_id]
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/polls/{poll_id}/poll_sessions/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get results of a poll session
      effect: read
      questions:
      - What did students answer in a particular poll session?
      - Can I see the results for one session of my poll?
      instructions:
      - text: Get the results of session {id} for poll {poll_id}.
        slots:
          id: path.id
          poll_id: path.poll_id
      - text: Show how students responded in poll {poll_id} session {id}.
        slots:
          poll_id: path.poll_id
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/polls/{poll_id}/poll_sessions/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a poll session
      effect: write
      questions:
      - How do I change which section a poll session is for?
      - Can I turn public results on or off for an existing poll session?
      instructions:
      - text: Set public results on poll {poll_id} session {id} to {has_public_results}.
        slots:
          poll_id: path.poll_id
          id: path.id
          has_public_results: requestBody.poll_sessions[has_public_results]
      - text: Move poll {poll_id} session {id} to section {course_section_id}.
        slots:
          poll_id: path.poll_id
          id: path.id
          course_section_id: requestBody.poll_sessions[course_section_id]
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/polls/{poll_id}/poll_sessions/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a poll session
      effect: destructive
      questions:
      - How do I delete a poll session I ran by mistake?
      - Can I remove one session from a poll without deleting the poll?
      instructions:
      - text: Delete session {id} of poll {poll_id}.
        slots:
          id: path.id
          poll_id: path.poll_id
      - text: Remove poll {poll_id} session {id}.
        slots:
          poll_id: path.poll_id
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/polls/{poll_id}/poll_sessions/{id}/open'].get
  update:
    x-apievangelist-phrasing:
      intent: Open a poll session for responses
      effect: write
      questions:
      - How do I start accepting answers in a poll session?
      - Can I open a poll session so students can vote now?
      instructions:
      - text: Open session {id} of poll {poll_id}.
        slots:
          id: path.id
          poll_id: path.poll_id
      - text: Start collecting votes on poll {poll_id} session {id}.
        slots:
          poll_id: path.poll_id
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/polls/{poll_id}/poll_sessions/{id}/close'].get
  update:
    x-apievangelist-phrasing:
      intent: Close an open poll session
      effect: write
      questions:
      - How do I stop students from answering a poll that's still open?
      - Can I close voting on a poll session?
      instructions:
      - text: Close session {id} of poll {poll_id}.
        slots:
          id: path.id
          poll_id: path.poll_id
      - text: Stop accepting votes on poll {poll_id} session {id}.
        slots:
          poll_id: path.poll_id
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/poll_sessions/opened'].get
  update:
    x-apievangelist-phrasing:
      intent: List poll sessions that are open
      effect: read
      questions:
      - Which polls are open for me to answer right now?
      - What poll sessions are currently accepting responses?
      instructions:
      - text: List the open poll sessions available to me.
      - text: Show polls I can vote in right now.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/poll_sessions/closed'].get
  update:
    x-apievangelist-phrasing:
      intent: List poll sessions that are closed
      effect: read
      questions:
      - Which poll sessions have already closed?
      - Can I review the polls that are no longer accepting answers?
      instructions:
      - text: List the closed poll sessions available to me.
      - text: Show polls that have finished voting.
      method: generated
      generated: '2026-10-01'