# 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 User Observees API
  version: 1.0.0
extends: openapi/canvas-user-observees-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/users/{user_id}/observees'].get
  update:
    x-apievangelist-phrasing:
      intent: List the students a user observes
      effect: read
      questions:
      - Which students is a parent account linked to observe in Canvas?
      - Does the observees list include one-off observer enrollments in a single course?
      instructions:
      - text: List the observees linked to user {user_id}.
        slots:
          user_id: path.user_id
      - text: Show who observer {user_id} is watching, including {include}.
        slots:
          user_id: path.user_id
          include: query.include
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/observees'].post
  update:
    x-apievangelist-phrasing:
      intent: Link an observee using their credentials or pairing code
      effect: write
      questions:
      - How does a parent link to their child's account with a pairing code?
      - Can I add an observee by entering the student's login and password?
      instructions:
      - text: Link observer {user_id} to a student using pairing code {pairing_code}.
        slots:
          user_id: path.user_id
          pairing_code: requestBody.pairing_code
      - text: Add an observee to user {user_id} with login {unique_id} and password {password}.
        slots:
          user_id: path.user_id
          unique_id: requestBody.observee[unique_id]
          password: requestBody.observee[password]
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/observers'].get
  update:
    x-apievangelist-phrasing:
      intent: List the observers linked to a user
      effect: read
      questions:
      - Which parents or guardians are observing a student?
      - Can a student see who is linked as their observer?
      instructions:
      - text: List the observers linked to user {user_id}.
        slots:
          user_id: path.user_id
      - text: Show everyone observing student {user_id}, including {include}.
        slots:
          user_id: path.user_id
          include: query.include
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/observees/{observee_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Show one observed user
      effect: read
      questions:
      - How do I get details on a single student I observe?
      - Can an observer view one specific observee's profile?
      instructions:
      - text: Show observee {observee_id} of user {user_id}.
        slots:
          observee_id: path.observee_id
          user_id: path.user_id
      - text: Get details for the student {observee_id} that {user_id} observes.
        slots:
          observee_id: path.observee_id
          user_id: path.user_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/observees/{observee_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Register a user as an observee by id
      effect: write
      questions:
      - As an admin, how do I link an observer to a student by user id without credentials?
      - Can I scope a new observer link to one root account?
      instructions:
      - text: Make user {user_id} an observer of user {observee_id}.
        slots:
          user_id: path.user_id
          observee_id: path.observee_id
      - text: Link observer {user_id} to student {observee_id} in root account {root_account_id}.
        slots:
          user_id: path.user_id
          observee_id: path.observee_id
          root_account_id: requestBody.root_account_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/observees/{observee_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unlink an observee from an observer
      effect: destructive
      questions:
      - How do I stop a parent from observing a student?
      - Can I remove an observer link only for one root account?
      instructions:
      - text: Remove observee {observee_id} from observer {user_id}.
        slots:
          observee_id: path.observee_id
          user_id: path.user_id
      - text: Unlink {user_id} from observing {observee_id} in root account {root_account_id}.
        slots:
          user_id: path.user_id
          observee_id: path.observee_id
          root_account_id: query.root_account_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/observers/{observer_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Show one observer of a user
      effect: read
      questions:
      - How do I see details about a specific parent observing my account?
      - Can a student look up one of their observers by id?
      instructions:
      - text: Show observer {observer_id} of user {user_id}.
        slots:
          observer_id: path.observer_id
          user_id: path.user_id
      - text: Get details on {observer_id}, who observes student {user_id}.
        slots:
          observer_id: path.observer_id
          user_id: path.user_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/observer_pairing_codes'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate an observer pairing code for a student
      effect: write
      questions:
      - How does a student generate a code so a parent can link to them?
      - Can I create a pairing code for parent self-registration?
      instructions:
      - text: Create an observer pairing code for student {user_id}.
        slots:
          user_id: path.user_id
      - text: Generate a parent pairing code for user {user_id}.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-10-01'