# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Docplanner Integrations Slots API
  version: 1.0.0
extends: openapi/znanylekarz-slots-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: 4
- target: $.paths['/facilities/{facility_id}/doctors/{doctor_id}/addresses/{address_id}/slots'].get
  update:
    x-apievangelist-phrasing:
      intent: List free appointment slots at an address
      effect: read
      questions:
      - What free appointment times does a doctor have at an address next month?
      - What's the longest date range I can request open slots for?
      instructions:
      - text: List free slots for address {address} of doctor {doctor} in facility {facility} from {start} to {end}.
        slots:
          facility: path.facility_id
          doctor: path.doctor_id
          address: path.address_id
          start: query.start
          end: query.end
      - text: Show open slots between {start} and {end} at address {address} with their services ({with}).
        slots:
          start: query.start
          end: query.end
          address: path.address_id
          with: query.with
      method: generated
      generated: '2026-10-01'
- target: $.paths['/facilities/{facility_id}/doctors/{doctor_id}/addresses/{address_id}/slots'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace an address's slots for date ranges
      effect: write
      questions:
      - How do I push my clinic's availability so it overrides existing slots?
      - Can I clear or replace all slots for certain date ranges in one request?
      - What happens if I send the same slot update twice?
      instructions:
      - text: Replace the slots on address {address} of doctor {doctor} in facility {facility} with {slots}.
        slots:
          facility: path.facility_id
          doctor: path.doctor_id
          address: path.address_id
          slots: requestBody.slots
      - text: 'Overwrite availability for address {address} using these slot ranges: {slots}.'
        slots:
          address: path.address_id
          slots: requestBody.slots
      method: generated
      generated: '2026-10-01'
- target: $.paths['/facilities/{facility_id}/doctors/{doctor_id}/addresses/{address_id}/slots/{start}/book'].post
  update:
    x-apievangelist-phrasing:
      intent: Book a patient into a free slot
      effect: write
      questions:
      - How do I book an appointment for a patient in an open slot?
      - Can I attach the patient's insurance plan when booking a visit?
      - Is it possible to mark a new booking as a recurring visit?
      instructions:
      - text: Book slot {start} at address {address} of doctor {doctor} in facility {facility} for {patient}, service {address_service_id}, {duration} minutes.
        slots:
          facility: path.facility_id
          doctor: path.doctor_id
          address: path.address_id
          start: path.start
          patient: requestBody.patient
          address_service_id: requestBody.address_service_id
          duration: requestBody.duration
      - text: Book slot {start} for {patient} under insurer {insurance_provider_id}, plan {insurance_plan_id}, service {address_service_id}, {duration} min.
        slots:
          start: path.start
          patient: requestBody.patient
          insurance_provider_id: requestBody.insurance_provider_id
          insurance_plan_id: requestBody.insurance_plan_id
          address_service_id: requestBody.address_service_id
          duration: requestBody.duration
      method: generated
      generated: '2026-10-01'
- target: $.paths['/facilities/{facility_id}/doctors/{doctor_id}/addresses/{address_id}/slots/{date}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete all slots on a given date
      effect: destructive
      questions:
      - How do I wipe a doctor's open slots for one day?
      - Can I remove availability at an address for a single date?
      instructions:
      - text: Delete slots on {date} at address {address} of doctor {doctor} in facility {facility}.
        slots:
          facility: path.facility_id
          doctor: path.doctor_id
          address: path.address_id
          date: path.date
      - text: Clear all availability on {date} for address {address}.
        slots:
          date: path.date
          address: path.address_id
      method: generated
      generated: '2026-10-01'