{
  "openapi": "3.1.0",
  "info": {
    "title": "CuspFlow API",
    "version": "1.0.0",
    "description": "REST API for a CuspFlow clinic, for the clinic's own IT/BI team and for inbound data\nmigration. Reads cover every core module; writes cover the clinical and reference records.\nMoney is readable but not writable in v1.\n\nFull guide: https://cuspflow.co/docs/developers/api-overview\n\n**Authentication.** `Authorization: Bearer cfk_live_...`. A key is clinic-scoped, carries an\nexplicit scope set, and is bound to a staff role whose permissions it can never exceed.\n\n**No CORS.** This API sends no `Access-Control-Allow-Origin`, deliberately. An API key in a\nbrowser is a leaked API key; call it from a server.\n\n**Pagination is keyset only.** Follow `meta.next_cursor`. There is no offset parameter.\n\n**`billing` is the canonical money table.** `invoices`/`invoice_items` are dead schema and are\nnot exposed; do not build against them.\n\n**`appointments.staff_id` is the assignee.** `dentist_id` and `doctor_id` are returned for\nexisting rows but are legacy and rejected in request bodies.\n\n**Tolerate additions.** New fields, resources, optional parameters and enum values ship into v1\nwithout a version bump. Unknown fields and unknown enum values must not break your client."
  },
  "servers": [
    {
      "url": "https://{projectRef}.supabase.co/functions/v1/api",
      "description": "CuspFlow production",
      "variables": {
        "projectRef": {
          "default": "zwhwryofdsgmzgqbcghl"
        }
      }
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "A CuspFlow API key: `cfk_live_<prefix>_<secret>`. Shown once at creation."
      }
    },
    "schemas": {
      "Problem": {
        "type": "object",
        "description": "RFC 9457 problem detail. `detail` never contains a field VALUE, because those are patient data.",
        "properties": {
          "type": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          },
          "instance": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "request_id": {
            "type": "string"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "field": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              }
            }
          }
        },
        "required": [
          "type",
          "title",
          "status",
          "code"
        ]
      },
      "patients": {
        "type": "object",
        "description": "A row of `patients`.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "clinic_id": {
            "type": "string",
            "format": "uuid"
          },
          "branch_id": {
            "type": "string",
            "format": "uuid"
          },
          "family_id": {
            "type": "string",
            "format": "uuid"
          },
          "patient_code": {
            "type": "string"
          },
          "first_name": {
            "type": "string"
          },
          "last_name": {
            "type": "string"
          },
          "dob": {
            "type": "string",
            "format": "date"
          },
          "age_group": {
            "type": "string"
          },
          "gender": {
            "type": "string"
          },
          "phone": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "location": {
            "type": "string"
          },
          "allergies": {
            "type": "string"
          },
          "current_medications": {
            "type": "string"
          },
          "medical_history_notes": {
            "type": "string"
          },
          "dental_history_notes": {
            "type": "string"
          },
          "patient_since": {
            "type": "string",
            "format": "date-time"
          },
          "is_active": {
            "type": "boolean"
          },
          "is_head_of_family": {
            "type": "boolean"
          },
          "emergency_contact_name": {
            "type": "string"
          },
          "emergency_contact_relationship": {
            "type": "string"
          },
          "emergency_contact_phone": {
            "type": "string"
          },
          "emergency_contact_email": {
            "type": "string"
          },
          "emergency_contact_location": {
            "type": "string"
          },
          "insurance_carrier_id": {
            "type": "string",
            "format": "uuid"
          },
          "insurance_provider": {
            "type": "string"
          },
          "insurance_policy_number": {
            "type": "string"
          },
          "insurance_group_number": {
            "type": "string"
          },
          "insurance_holder_name": {
            "type": "string"
          },
          "whatsapp_number": {
            "type": "string"
          },
          "whatsapp_opted_in": {
            "type": "boolean"
          },
          "whatsapp_consent_at": {
            "type": "string",
            "format": "date-time"
          },
          "reminders_email_opted_out": {
            "type": "boolean"
          },
          "reminders_whatsapp_opted_out": {
            "type": "boolean"
          },
          "import_report_id": {
            "type": "string",
            "format": "uuid"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "patients_create": {
        "type": "object",
        "properties": {
          "branch_id": {
            "type": "string",
            "format": "uuid"
          },
          "family_id": {
            "type": "string",
            "format": "uuid"
          },
          "first_name": {
            "type": "string"
          },
          "last_name": {
            "type": "string"
          },
          "dob": {
            "type": "string",
            "format": "date"
          },
          "age_group": {
            "type": "string"
          },
          "gender": {
            "type": "string"
          },
          "phone": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "location": {
            "type": "string"
          },
          "allergies": {
            "type": "string"
          },
          "current_medications": {
            "type": "string"
          },
          "medical_history_notes": {
            "type": "string"
          },
          "dental_history_notes": {
            "type": "string"
          },
          "patient_since": {
            "type": "string",
            "format": "date-time"
          },
          "is_active": {
            "type": "boolean"
          },
          "is_head_of_family": {
            "type": "boolean"
          },
          "emergency_contact_name": {
            "type": "string"
          },
          "emergency_contact_relationship": {
            "type": "string"
          },
          "emergency_contact_phone": {
            "type": "string"
          },
          "emergency_contact_email": {
            "type": "string"
          },
          "emergency_contact_location": {
            "type": "string"
          },
          "insurance_carrier_id": {
            "type": "string",
            "format": "uuid"
          },
          "insurance_provider": {
            "type": "string"
          },
          "insurance_policy_number": {
            "type": "string"
          },
          "insurance_group_number": {
            "type": "string"
          },
          "insurance_holder_name": {
            "type": "string"
          },
          "whatsapp_number": {
            "type": "string"
          },
          "whatsapp_opted_in": {
            "type": "boolean"
          },
          "whatsapp_consent_at": {
            "type": "string",
            "format": "date-time"
          },
          "reminders_email_opted_out": {
            "type": "boolean"
          },
          "reminders_whatsapp_opted_out": {
            "type": "boolean"
          }
        },
        "additionalProperties": false,
        "required": [
          "first_name",
          "last_name"
        ]
      },
      "patients_update": {
        "type": "object",
        "properties": {
          "branch_id": {
            "type": "string",
            "format": "uuid"
          },
          "family_id": {
            "type": "string",
            "format": "uuid"
          },
          "first_name": {
            "type": "string"
          },
          "last_name": {
            "type": "string"
          },
          "dob": {
            "type": "string",
            "format": "date"
          },
          "age_group": {
            "type": "string"
          },
          "gender": {
            "type": "string"
          },
          "phone": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "location": {
            "type": "string"
          },
          "allergies": {
            "type": "string"
          },
          "current_medications": {
            "type": "string"
          },
          "medical_history_notes": {
            "type": "string"
          },
          "dental_history_notes": {
            "type": "string"
          },
          "patient_since": {
            "type": "string",
            "format": "date-time"
          },
          "is_active": {
            "type": "boolean"
          },
          "is_head_of_family": {
            "type": "boolean"
          },
          "emergency_contact_name": {
            "type": "string"
          },
          "emergency_contact_relationship": {
            "type": "string"
          },
          "emergency_contact_phone": {
            "type": "string"
          },
          "emergency_contact_email": {
            "type": "string"
          },
          "emergency_contact_location": {
            "type": "string"
          },
          "insurance_carrier_id": {
            "type": "string",
            "format": "uuid"
          },
          "insurance_provider": {
            "type": "string"
          },
          "insurance_policy_number": {
            "type": "string"
          },
          "insurance_group_number": {
            "type": "string"
          },
          "insurance_holder_name": {
            "type": "string"
          },
          "whatsapp_number": {
            "type": "string"
          },
          "whatsapp_opted_in": {
            "type": "boolean"
          },
          "whatsapp_consent_at": {
            "type": "string",
            "format": "date-time"
          },
          "reminders_email_opted_out": {
            "type": "boolean"
          },
          "reminders_whatsapp_opted_out": {
            "type": "boolean"
          }
        },
        "additionalProperties": false,
        "minProperties": 1
      },
      "appointments": {
        "type": "object",
        "description": "A row of `appointments`.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "clinic_id": {
            "type": "string",
            "format": "uuid"
          },
          "branch_id": {
            "type": "string",
            "format": "uuid"
          },
          "patient_id": {
            "type": "string",
            "format": "uuid"
          },
          "staff_id": {
            "type": "string"
          },
          "chair_id": {
            "type": "string",
            "format": "uuid"
          },
          "scheduled_time": {
            "type": "string",
            "format": "date-time"
          },
          "duration_minutes": {
            "type": "integer"
          },
          "procedure_name": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "notes": {
            "type": "string"
          },
          "cancellation_reason": {
            "type": "string"
          },
          "rescheduled_from_id": {
            "type": "string",
            "format": "uuid"
          },
          "booked_via_portal": {
            "type": "boolean"
          },
          "dentist_id": {
            "type": "string",
            "format": "uuid",
            "readOnly": true,
            "description": "Legacy field. Returned for existing rows, rejected in request bodies."
          },
          "doctor_id": {
            "type": "string",
            "readOnly": true,
            "description": "Legacy field. Returned for existing rows, rejected in request bodies."
          },
          "import_report_id": {
            "type": "string",
            "format": "uuid"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "appointments_create": {
        "type": "object",
        "properties": {
          "branch_id": {
            "type": "string",
            "format": "uuid"
          },
          "patient_id": {
            "type": "string",
            "format": "uuid"
          },
          "staff_id": {
            "type": "string"
          },
          "chair_id": {
            "type": "string",
            "format": "uuid"
          },
          "scheduled_time": {
            "type": "string",
            "format": "date-time"
          },
          "duration_minutes": {
            "type": "integer"
          },
          "procedure_name": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "notes": {
            "type": "string"
          },
          "cancellation_reason": {
            "type": "string"
          },
          "rescheduled_from_id": {
            "type": "string",
            "format": "uuid"
          }
        },
        "additionalProperties": false,
        "required": [
          "patient_id",
          "scheduled_time",
          "branch_id"
        ]
      },
      "appointments_update": {
        "type": "object",
        "properties": {
          "branch_id": {
            "type": "string",
            "format": "uuid"
          },
          "patient_id": {
            "type": "string",
            "format": "uuid"
          },
          "staff_id": {
            "type": "string"
          },
          "chair_id": {
            "type": "string",
            "format": "uuid"
          },
          "scheduled_time": {
            "type": "string",
            "format": "date-time"
          },
          "duration_minutes": {
            "type": "integer"
          },
          "procedure_name": {
            "type": "string"
          },
          "notes": {
            "type": "string"
          },
          "cancellation_reason": {
            "type": "string"
          },
          "rescheduled_from_id": {
            "type": "string",
            "format": "uuid"
          }
        },
        "additionalProperties": false,
        "minProperties": 1,
        "description": "Note: some fields can be set at creation but not changed afterwards, so this list is narrower than the create body."
      },
      "treatment_plans": {
        "type": "object",
        "description": "A row of `treatment_plans`.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "clinic_id": {
            "type": "string",
            "format": "uuid"
          },
          "branch_id": {
            "type": "string",
            "format": "uuid"
          },
          "patient_id": {
            "type": "string",
            "format": "uuid"
          },
          "appointment_id": {
            "type": "string",
            "format": "uuid"
          },
          "dentist_id": {
            "type": "string",
            "format": "uuid"
          },
          "chair_id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string"
          },
          "payment_status": {
            "type": "string"
          },
          "clinical_notes": {
            "type": "string"
          },
          "teeth_codes": {
            "type": "string"
          },
          "tooth_notes": {
            "type": "object",
            "additionalProperties": true
          },
          "finalized_at": {
            "type": "string",
            "format": "date-time"
          },
          "import_report_id": {
            "type": "string",
            "format": "uuid"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "treatment_plans_create": {
        "type": "object",
        "properties": {
          "branch_id": {
            "type": "string",
            "format": "uuid"
          },
          "patient_id": {
            "type": "string",
            "format": "uuid"
          },
          "appointment_id": {
            "type": "string",
            "format": "uuid"
          },
          "dentist_id": {
            "type": "string",
            "format": "uuid"
          },
          "chair_id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string"
          },
          "clinical_notes": {
            "type": "string"
          },
          "teeth_codes": {
            "type": "string"
          },
          "tooth_notes": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "additionalProperties": false,
        "required": [
          "patient_id",
          "branch_id"
        ]
      },
      "treatment_plans_update": {
        "type": "object",
        "properties": {
          "branch_id": {
            "type": "string",
            "format": "uuid"
          },
          "patient_id": {
            "type": "string",
            "format": "uuid"
          },
          "appointment_id": {
            "type": "string",
            "format": "uuid"
          },
          "dentist_id": {
            "type": "string",
            "format": "uuid"
          },
          "chair_id": {
            "type": "string",
            "format": "uuid"
          },
          "clinical_notes": {
            "type": "string"
          },
          "teeth_codes": {
            "type": "string"
          },
          "tooth_notes": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "additionalProperties": false,
        "minProperties": 1,
        "description": "Note: some fields can be set at creation but not changed afterwards, so this list is narrower than the create body."
      },
      "treatment_items": {
        "type": "object",
        "description": "A row of `treatment_items`.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "clinic_id": {
            "type": "string",
            "format": "uuid"
          },
          "treatment_plan_id": {
            "type": "string",
            "format": "uuid"
          },
          "catalog_item_id": {
            "type": "string",
            "format": "uuid"
          },
          "catalog_procedure_id": {
            "type": "string",
            "format": "uuid"
          },
          "item_type": {
            "type": "string"
          },
          "item_name": {
            "type": "string"
          },
          "teeth_codes": {
            "type": "string"
          },
          "unit_price": {
            "type": "number"
          },
          "qty": {
            "type": "integer"
          },
          "discount": {
            "type": "number"
          },
          "final_price": {
            "type": "number"
          },
          "dosage_override": {
            "type": "string"
          },
          "clinical_status": {
            "type": "string"
          },
          "billed_at": {
            "type": "string",
            "format": "date-time"
          },
          "notes": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "medical_history": {
        "type": "object",
        "description": "A row of `medical_history`.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "clinic_id": {
            "type": "string",
            "format": "uuid"
          },
          "patient_id": {
            "type": "string",
            "format": "uuid"
          },
          "condition_type": {
            "type": "string"
          },
          "condition_name": {
            "type": "string"
          },
          "is_ongoing": {
            "type": "boolean"
          },
          "notes": {
            "type": "string"
          },
          "added_by_staff_id": {
            "type": "string",
            "format": "uuid"
          },
          "updated_by_staff_id": {
            "type": "string",
            "format": "uuid"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "medical_history_create": {
        "type": "object",
        "properties": {
          "patient_id": {
            "type": "string",
            "format": "uuid"
          },
          "condition_type": {
            "type": "string"
          },
          "condition_name": {
            "type": "string"
          },
          "notes": {
            "type": "string"
          },
          "is_ongoing": {
            "type": "boolean"
          },
          "added_by_staff_id": {
            "type": "string",
            "format": "uuid"
          },
          "updated_by_staff_id": {
            "type": "string",
            "format": "uuid"
          }
        },
        "additionalProperties": false,
        "required": [
          "patient_id",
          "condition_type",
          "condition_name"
        ]
      },
      "medical_history_update": {
        "type": "object",
        "properties": {
          "patient_id": {
            "type": "string",
            "format": "uuid"
          },
          "condition_type": {
            "type": "string"
          },
          "condition_name": {
            "type": "string"
          },
          "notes": {
            "type": "string"
          },
          "is_ongoing": {
            "type": "boolean"
          },
          "added_by_staff_id": {
            "type": "string",
            "format": "uuid"
          },
          "updated_by_staff_id": {
            "type": "string",
            "format": "uuid"
          }
        },
        "additionalProperties": false,
        "minProperties": 1
      },
      "patient_journey": {
        "type": "object",
        "description": "A row of `patient_journey`.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "clinic_id": {
            "type": "string",
            "format": "uuid"
          },
          "branch_id": {
            "type": "string",
            "format": "uuid"
          },
          "patient_id": {
            "type": "string",
            "format": "uuid"
          },
          "appointment_id": {
            "type": "string",
            "format": "uuid"
          },
          "treatment_plan_id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string"
          },
          "is_emergency": {
            "type": "boolean"
          },
          "entered_status_at": {
            "type": "string",
            "format": "date-time"
          },
          "exited_status_at": {
            "type": "string",
            "format": "date-time"
          },
          "duration_minutes": {
            "type": "number"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "families": {
        "type": "object",
        "description": "A row of `families`.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "clinic_id": {
            "type": "string",
            "format": "uuid"
          },
          "head_of_family_id": {
            "type": "string",
            "format": "uuid"
          },
          "family_name": {
            "type": "string"
          },
          "import_report_id": {
            "type": "string",
            "format": "uuid"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "families_create": {
        "type": "object",
        "properties": {
          "head_of_family_id": {
            "type": "string",
            "format": "uuid"
          },
          "family_name": {
            "type": "string"
          }
        },
        "additionalProperties": false,
        "required": [
          "head_of_family_id",
          "family_name"
        ]
      },
      "families_update": {
        "type": "object",
        "properties": {
          "head_of_family_id": {
            "type": "string",
            "format": "uuid"
          },
          "family_name": {
            "type": "string"
          }
        },
        "additionalProperties": false,
        "minProperties": 1
      },
      "patient_insurance": {
        "type": "object",
        "description": "A row of `patient_insurance`.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "clinic_id": {
            "type": "string",
            "format": "uuid"
          },
          "patient_id": {
            "type": "string",
            "format": "uuid"
          },
          "insurance_carrier_id": {
            "type": "string",
            "format": "uuid"
          },
          "provider_name": {
            "type": "string"
          },
          "policy_number": {
            "type": "string"
          },
          "group_number": {
            "type": "string"
          },
          "holder_name": {
            "type": "string"
          },
          "is_primary": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "patient_insurance_create": {
        "type": "object",
        "properties": {
          "patient_id": {
            "type": "string",
            "format": "uuid"
          },
          "insurance_carrier_id": {
            "type": "string",
            "format": "uuid"
          },
          "provider_name": {
            "type": "string"
          },
          "policy_number": {
            "type": "string"
          },
          "group_number": {
            "type": "string"
          },
          "holder_name": {
            "type": "string"
          },
          "is_primary": {
            "type": "boolean"
          }
        },
        "additionalProperties": false,
        "required": [
          "patient_id"
        ]
      },
      "patient_insurance_update": {
        "type": "object",
        "properties": {
          "patient_id": {
            "type": "string",
            "format": "uuid"
          },
          "insurance_carrier_id": {
            "type": "string",
            "format": "uuid"
          },
          "provider_name": {
            "type": "string"
          },
          "policy_number": {
            "type": "string"
          },
          "group_number": {
            "type": "string"
          },
          "holder_name": {
            "type": "string"
          },
          "is_primary": {
            "type": "boolean"
          }
        },
        "additionalProperties": false,
        "minProperties": 1
      },
      "billing": {
        "type": "object",
        "description": "A row of `billing`.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "clinic_id": {
            "type": "string",
            "format": "uuid"
          },
          "patient_id": {
            "type": "string",
            "format": "uuid"
          },
          "treatment_plan_id": {
            "type": "string",
            "format": "uuid"
          },
          "receipt_number": {
            "type": "string"
          },
          "total_amount": {
            "type": "number"
          },
          "discount_applied": {
            "type": "number"
          },
          "tax_applied": {
            "type": "number"
          },
          "final_amount_due": {
            "type": "number"
          },
          "amount_paid": {
            "type": "number"
          },
          "balance_due": {
            "type": "number"
          },
          "status": {
            "type": "string"
          },
          "is_finalized": {
            "type": "boolean"
          },
          "finalized_at": {
            "type": "string",
            "format": "date-time"
          },
          "import_report_id": {
            "type": "string",
            "format": "uuid"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "payments": {
        "type": "object",
        "description": "A row of `payments`.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "clinic_id": {
            "type": "string",
            "format": "uuid"
          },
          "branch_id": {
            "type": "string",
            "format": "uuid"
          },
          "billing_id": {
            "type": "string",
            "format": "uuid"
          },
          "patient_id": {
            "type": "string",
            "format": "uuid"
          },
          "received_by": {
            "type": "string",
            "format": "uuid"
          },
          "amount_paid": {
            "type": "number"
          },
          "payment_method": {
            "type": "string"
          },
          "payment_date": {
            "type": "string",
            "format": "date-time"
          },
          "is_installment": {
            "type": "boolean"
          },
          "is_initial_payment": {
            "type": "boolean"
          },
          "reference_number": {
            "type": "string"
          },
          "transaction_id": {
            "type": "string"
          },
          "card_last4": {
            "type": "string"
          },
          "cardholder_name": {
            "type": "string"
          },
          "mobile_money_number": {
            "type": "string"
          },
          "mobile_money_provider": {
            "type": "string"
          },
          "insurance_claim_ref": {
            "type": "string"
          },
          "notes": {
            "type": "string"
          },
          "import_report_id": {
            "type": "string",
            "format": "uuid"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "insurance_claims": {
        "type": "object",
        "description": "A row of `insurance_claims`.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "clinic_id": {
            "type": "string",
            "format": "uuid"
          },
          "patient_id": {
            "type": "string",
            "format": "uuid"
          },
          "billing_id": {
            "type": "string",
            "format": "uuid"
          },
          "provider_name": {
            "type": "string"
          },
          "policy_number": {
            "type": "string"
          },
          "claim_reference": {
            "type": "string"
          },
          "amount_claimed": {
            "type": "number"
          },
          "amount_approved": {
            "type": "number"
          },
          "status": {
            "type": "string"
          },
          "notes": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "insurance_carriers": {
        "type": "object",
        "description": "A row of `insurance_carriers`.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "clinic_id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "is_active": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "insurance_carriers_create": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "is_active": {
            "type": "boolean"
          }
        },
        "additionalProperties": false,
        "required": [
          "name"
        ]
      },
      "insurance_carriers_update": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "is_active": {
            "type": "boolean"
          }
        },
        "additionalProperties": false,
        "minProperties": 1
      },
      "lab_cases": {
        "type": "object",
        "description": "A row of `lab_cases`.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "clinic_id": {
            "type": "string",
            "format": "uuid"
          },
          "branch_id": {
            "type": "string",
            "format": "uuid"
          },
          "patient_id": {
            "type": "string",
            "format": "uuid"
          },
          "treatment_plan_id": {
            "type": "string",
            "format": "uuid"
          },
          "appointment_id": {
            "type": "string",
            "format": "uuid"
          },
          "laboratory_id": {
            "type": "string",
            "format": "uuid"
          },
          "doctor_id": {
            "type": "string",
            "format": "uuid"
          },
          "billing_item_id": {
            "type": "string",
            "format": "uuid"
          },
          "case_type": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "lab_payment_status": {
            "type": "string"
          },
          "teeth_codes": {
            "type": "string"
          },
          "sent_date": {
            "type": "string",
            "format": "date"
          },
          "expected_return_date": {
            "type": "string",
            "format": "date"
          },
          "received_date": {
            "type": "string",
            "format": "date"
          },
          "fitted_date": {
            "type": "string",
            "format": "date"
          },
          "lab_cost": {
            "type": "number"
          },
          "transport_cost": {
            "type": "number"
          },
          "other_costs": {
            "type": "number"
          },
          "patient_charge": {
            "type": "number"
          },
          "lab_invoice_ref": {
            "type": "string"
          },
          "tracking_reference": {
            "type": "string"
          },
          "notes": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "lab_case_procedures": {
        "type": "object",
        "description": "A row of `lab_case_procedures`.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "clinic_id": {
            "type": "string",
            "format": "uuid"
          },
          "lab_case_id": {
            "type": "string",
            "format": "uuid"
          },
          "catalog_item_id": {
            "type": "string",
            "format": "uuid"
          },
          "item_name": {
            "type": "string"
          },
          "unit_price": {
            "type": "number"
          },
          "qty": {
            "type": "integer"
          },
          "notes": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "laboratories": {
        "type": "object",
        "description": "A row of `laboratories`.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "clinic_id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "phone": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "notes": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "laboratories_create": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "phone": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "notes": {
            "type": "string"
          }
        },
        "additionalProperties": false,
        "required": [
          "name"
        ]
      },
      "laboratories_update": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "phone": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "notes": {
            "type": "string"
          }
        },
        "additionalProperties": false,
        "minProperties": 1
      },
      "inventory_items": {
        "type": "object",
        "description": "A row of `inventory_items`.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "clinic_id": {
            "type": "string",
            "format": "uuid"
          },
          "branch_id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "sku": {
            "type": "string"
          },
          "reorder_level": {
            "type": "number"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "inventory_items_create": {
        "type": "object",
        "properties": {
          "branch_id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "sku": {
            "type": "string"
          },
          "reorder_level": {
            "type": "number"
          }
        },
        "additionalProperties": false,
        "required": [
          "branch_id",
          "category",
          "name"
        ]
      },
      "inventory_items_update": {
        "type": "object",
        "properties": {
          "branch_id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "sku": {
            "type": "string"
          },
          "reorder_level": {
            "type": "number"
          }
        },
        "additionalProperties": false,
        "minProperties": 1
      },
      "inventory_batches": {
        "type": "object",
        "description": "A row of `inventory_batches`.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "clinic_id": {
            "type": "string",
            "format": "uuid"
          },
          "branch_id": {
            "type": "string",
            "format": "uuid"
          },
          "inventory_item_id": {
            "type": "string",
            "format": "uuid"
          },
          "batch_number": {
            "type": "string"
          },
          "supplier_name": {
            "type": "string"
          },
          "expiry_date": {
            "type": "string",
            "format": "date"
          },
          "quantity_received": {
            "type": "number"
          },
          "quantity_remaining": {
            "type": "number"
          },
          "cost_per_unit": {
            "type": "number"
          },
          "received_at": {
            "type": "string",
            "format": "date-time"
          },
          "write_off_quantity": {
            "type": "number"
          },
          "write_off_reason": {
            "type": "string"
          },
          "written_off_at": {
            "type": "string",
            "format": "date-time"
          },
          "written_off_by": {
            "type": "string",
            "format": "uuid"
          },
          "notes": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "inventory_transactions": {
        "type": "object",
        "description": "A row of `inventory_transactions`.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "clinic_id": {
            "type": "string",
            "format": "uuid"
          },
          "inventory_item_id": {
            "type": "string",
            "format": "uuid"
          },
          "type": {
            "type": "string"
          },
          "quantity": {
            "type": "number"
          },
          "notes": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "catalog_items": {
        "type": "object",
        "description": "A row of `catalog_items`.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "clinic_id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "unit_price": {
            "type": "number"
          },
          "linked_inventory_item_id": {
            "type": "string",
            "format": "uuid"
          },
          "linked_inventory_qty": {
            "type": "number"
          },
          "import_report_id": {
            "type": "string",
            "format": "uuid"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "catalog_items_create": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "unit_price": {
            "type": "number"
          },
          "linked_inventory_item_id": {
            "type": "string",
            "format": "uuid"
          },
          "linked_inventory_qty": {
            "type": "number"
          }
        },
        "additionalProperties": false,
        "required": [
          "name",
          "type",
          "unit_price"
        ]
      },
      "catalog_items_update": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "unit_price": {
            "type": "number"
          },
          "linked_inventory_item_id": {
            "type": "string",
            "format": "uuid"
          },
          "linked_inventory_qty": {
            "type": "number"
          }
        },
        "additionalProperties": false,
        "minProperties": 1
      },
      "branches": {
        "type": "object",
        "description": "A row of `branches`.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "clinic_id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "phone": {
            "type": "string"
          },
          "is_main_branch": {
            "type": "boolean"
          },
          "import_report_id": {
            "type": "string",
            "format": "uuid"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "dental_chairs": {
        "type": "object",
        "description": "A row of `dental_chairs`.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "clinic_id": {
            "type": "string",
            "format": "uuid"
          },
          "branch_id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "room_number": {
            "type": "string"
          },
          "is_occupied": {
            "type": "boolean"
          },
          "is_active": {
            "type": "boolean"
          },
          "import_report_id": {
            "type": "string",
            "format": "uuid"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "staff": {
        "type": "object",
        "description": "A row of `staff`.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "clinic_id": {
            "type": "string",
            "format": "uuid"
          },
          "branch_id": {
            "type": "string",
            "format": "uuid"
          },
          "working_branch_id": {
            "type": "string",
            "format": "uuid"
          },
          "staff_code": {
            "type": "string"
          },
          "salutation": {
            "type": "string"
          },
          "first_name": {
            "type": "string"
          },
          "last_name": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "role": {
            "type": "string"
          },
          "job_roles": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "work_email": {
            "type": "string"
          },
          "work_phone": {
            "type": "string"
          },
          "is_active": {
            "type": "boolean"
          },
          "hire_date": {
            "type": "string",
            "format": "date-time"
          },
          "import_report_id": {
            "type": "string",
            "format": "uuid"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      }
    }
  },
  "x-scopes": {
    "patients:read": {
      "maps_to_permission": "/patients"
    },
    "patients:write": {
      "maps_to_permission": "action:edit_patient"
    },
    "appointments:read": {
      "maps_to_permission": "/appointments"
    },
    "appointments:write": {
      "maps_to_permission": "action:manage_appointments"
    },
    "appointments:delete": {
      "maps_to_permission": "action:delete_appointments"
    },
    "clinical:read": {
      "maps_to_permission": "/patients"
    },
    "clinical:write": {
      "maps_to_permission": "action:edit_clinical"
    },
    "treatment:read": {
      "maps_to_permission": "/treatment-plans"
    },
    "treatment:write": {
      "maps_to_permission": "action:manage_treatment_items"
    },
    "billing:read": {
      "maps_to_permission": "/financials/overdue"
    },
    "billing:totals": {
      "maps_to_permission": "action:view_financial_summaries"
    },
    "inventory:read": {
      "maps_to_permission": "/inventory"
    },
    "inventory:write": {
      "maps_to_permission": "action:manage_inventory"
    },
    "catalog:read": {
      "maps_to_permission": "/settings/catalog"
    },
    "catalog:write": {
      "maps_to_permission": "action:manage_catalog"
    },
    "lab:read": {
      "maps_to_permission": "/lab-cases"
    },
    "lab:write": {
      "maps_to_permission": "action:manage_lab_cases"
    },
    "org:read": {
      "maps_to_permission": "/"
    },
    "export:read": {
      "maps_to_permission": "action:export_csv"
    },
    "imports:write": {
      "maps_to_permission": "action:edit_patient"
    },
    "imports:rollback": {
      "maps_to_permission": "action:edit_patient"
    }
  },
  "paths": {
    "/v1/patients": {
      "get": {
        "summary": "List patients",
        "operationId": "list_patients",
        "tags": [
          "patients"
        ],
        "security": [
          {
            "apiKey": [
              "patients:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size. Default 50, clamped to 200 rather than rejected.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque keyset cursor from `meta.next_cursor`. Do not construct one by hand. There is no offset parameter: PostgREST caps a range at 1000 rows and truncates silently.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "description": "Comma-separated subset of: id, clinic_id, branch_id, family_id, patient_code, first_name, last_name, dob, age_group, gender, phone, email, address, location, allergies, current_medications, medical_history_notes, dental_history_notes, patient_since, is_active, is_head_of_family, emergency_contact_name, emergency_contact_relationship, emergency_contact_phone, emergency_contact_email, emergency_contact_location, insurance_carrier_id, insurance_provider, insurance_policy_number, insurance_group_number, insurance_holder_name, whatsapp_number, whatsapp_opted_in, whatsapp_consent_at, reminders_email_opted_out, reminders_whatsapp_opted_out, import_report_id, created_at, updated_at.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sortable: created_at, updated_at, last_name, first_name, patient_since, dob. Prefix with `-` for descending. Default `-created_at`. An `id` tiebreak is always appended so the order is total.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_total",
            "in": "query",
            "required": false,
            "description": "Run an exact count and return it as `meta.total`. Expensive; counts double against the rate limit.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "include_deleted",
            "in": "query",
            "required": false,
            "description": "Include soft-deleted rows. `deleted_at` itself is never returned.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "exclude_migrated",
            "in": "query",
            "required": false,
            "description": "Exclude rows created by a bulk import (`import_report_id is null`).",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "description": "Filter on `id`. Also accepts `id[gte]`, `id[lte]`, `id[gt]`, `id[lt]`, `id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "branch_id",
            "in": "query",
            "required": false,
            "description": "Filter on `branch_id`. Also accepts `branch_id[gte]`, `branch_id[lte]`, `branch_id[gt]`, `branch_id[lt]`, `branch_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "family_id",
            "in": "query",
            "required": false,
            "description": "Filter on `family_id`. Also accepts `family_id[gte]`, `family_id[lte]`, `family_id[gt]`, `family_id[lt]`, `family_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "patient_code",
            "in": "query",
            "required": false,
            "description": "Filter on `patient_code`. Also accepts `patient_code[gte]`, `patient_code[lte]`, `patient_code[gt]`, `patient_code[lt]`, `patient_code[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "is_active",
            "in": "query",
            "required": false,
            "description": "Filter on `is_active`. Also accepts `is_active[gte]`, `is_active[lte]`, `is_active[gt]`, `is_active[lt]`, `is_active[in]` (comma-separated).",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "is_head_of_family",
            "in": "query",
            "required": false,
            "description": "Filter on `is_head_of_family`. Also accepts `is_head_of_family[gte]`, `is_head_of_family[lte]`, `is_head_of_family[gt]`, `is_head_of_family[lt]`, `is_head_of_family[in]` (comma-separated).",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "phone",
            "in": "query",
            "required": false,
            "description": "Filter on `phone`. Also accepts `phone[gte]`, `phone[lte]`, `phone[gt]`, `phone[lt]`, `phone[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "email",
            "in": "query",
            "required": false,
            "description": "Filter on `email`. Also accepts `email[gte]`, `email[lte]`, `email[gt]`, `email[lt]`, `email[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "dob",
            "in": "query",
            "required": false,
            "description": "Filter on `dob`. Also accepts `dob[gte]`, `dob[lte]`, `dob[gt]`, `dob[lt]`, `dob[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "age_group",
            "in": "query",
            "required": false,
            "description": "Filter on `age_group`. Also accepts `age_group[gte]`, `age_group[lte]`, `age_group[gt]`, `age_group[lt]`, `age_group[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "gender",
            "in": "query",
            "required": false,
            "description": "Filter on `gender`. Also accepts `gender[gte]`, `gender[lte]`, `gender[gt]`, `gender[lt]`, `gender[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "created_at",
            "in": "query",
            "required": false,
            "description": "Filter on `created_at`. Also accepts `created_at[gte]`, `created_at[lte]`, `created_at[gt]`, `created_at[lt]`, `created_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "updated_at",
            "in": "query",
            "required": false,
            "description": "Filter on `updated_at`. Also accepts `updated_at[gte]`, `updated_at[lte]`, `updated_at[gt]`, `updated_at[lt]`, `updated_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "patient_since",
            "in": "query",
            "required": false,
            "description": "Filter on `patient_since`. Also accepts `patient_since[gte]`, `patient_since[lte]`, `patient_since[gt]`, `patient_since[lt]`, `patient_since[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "insurance_carrier_id",
            "in": "query",
            "required": false,
            "description": "Filter on `insurance_carrier_id`. Also accepts `insurance_carrier_id[gte]`, `insurance_carrier_id[lte]`, `insurance_carrier_id[gt]`, `insurance_carrier_id[lt]`, `insurance_carrier_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of rows.",
            "headers": {
              "Link": {
                "description": "Contains `rel=\"next\"` when another page exists.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/patients"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Null means this was the last page. A FULL page always carries a cursor even if the next one turns out to be empty; never infer the end from a short page alone."
                        },
                        "total": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "Only with ?include_total=true."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown field in fields/sort/filter, or a malformed cursor.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `patients:read` scope.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a patient",
        "operationId": "create_patients",
        "tags": [
          "patients"
        ],
        "security": [
          {
            "apiKey": [
              "patients:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/patients_create"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created. The new row, under `data`.",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              },
              "ETag": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/patients"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Body is not JSON, or names a field that cannot be written. See `errors[]`; values are never echoed back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `patients:write`, the bound role may not write this, the branch is not allowed, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "An identical Idempotency-Key is still in flight.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "A required field is missing. See `errors[]`. Note that a field which simply cannot be written is a 400 `unknown_field`, not a 422.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/patients/{id}": {
      "get": {
        "summary": "Get a patient",
        "operationId": "get_patients",
        "tags": [
          "patients"
        ],
        "security": [
          {
            "apiKey": [
              "patients:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The row, under `data`.",
            "headers": {
              "ETag": {
                "description": "Weak validator for If-Match on a future write.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/patients"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `patients:read` scope, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row IN THIS CLINIC. A row belonging to another clinic also returns 404, never 403, so the API never confirms that an id exists elsewhere.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update a patient",
        "description": "Only the fields you send are changed.",
        "operationId": "update_patients",
        "tags": [
          "patients"
        ],
        "security": [
          {
            "apiKey": [
              "patients:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "The ETag from a previous GET. The write then applies only if nothing changed in between, otherwise 412. Not supported on resources with no updated_at column.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/patients_update"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated row, under `data`.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/patients"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Body is not JSON, or names a field that cannot be patched. See `errors[]`. `appointments.status` and `treatment_plans.status` report `create_only` here.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `patients:write`, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row in this clinic. Also returned for another clinic's row.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "412": {
            "description": "If-Match did not match, or the row changed between read and write.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Soft-delete a patient",
        "description": "Sets `deleted_at`. There is no hard delete in this API: the row stays restorable from Trash in the app.",
        "operationId": "delete_patients",
        "tags": [
          "patients"
        ],
        "security": [
          {
            "apiKey": [
              "patients:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "The ETag from a previous GET. The write then applies only if nothing changed in between, otherwise 412. Not supported on resources with no updated_at column.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Soft-deleted. No body."
          },
          "400": {
            "description": "Body is not JSON, or names a field that cannot be patched. See `errors[]`. `appointments.status` and `treatment_plans.status` report `create_only` here.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `patients:write`, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row in this clinic. Also returned for another clinic's row.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "412": {
            "description": "If-Match did not match, or the row changed between read and write.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/appointments": {
      "get": {
        "summary": "List appointments",
        "operationId": "list_appointments",
        "tags": [
          "appointments"
        ],
        "security": [
          {
            "apiKey": [
              "appointments:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size. Default 50, clamped to 200 rather than rejected.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque keyset cursor from `meta.next_cursor`. Do not construct one by hand. There is no offset parameter: PostgREST caps a range at 1000 rows and truncates silently.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "description": "Comma-separated subset of: id, clinic_id, branch_id, patient_id, staff_id, chair_id, scheduled_time, duration_minutes, procedure_name, status, notes, cancellation_reason, rescheduled_from_id, booked_via_portal, dentist_id, doctor_id, import_report_id, created_at, updated_at.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sortable: scheduled_time, created_at, updated_at. Prefix with `-` for descending. Default `-scheduled_time`. An `id` tiebreak is always appended so the order is total.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_total",
            "in": "query",
            "required": false,
            "description": "Run an exact count and return it as `meta.total`. Expensive; counts double against the rate limit.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "include_deleted",
            "in": "query",
            "required": false,
            "description": "Include soft-deleted rows. `deleted_at` itself is never returned.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "exclude_migrated",
            "in": "query",
            "required": false,
            "description": "Exclude rows created by a bulk import (`import_report_id is null`).",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "description": "Filter on `id`. Also accepts `id[gte]`, `id[lte]`, `id[gt]`, `id[lt]`, `id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "branch_id",
            "in": "query",
            "required": false,
            "description": "Filter on `branch_id`. Also accepts `branch_id[gte]`, `branch_id[lte]`, `branch_id[gt]`, `branch_id[lt]`, `branch_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "patient_id",
            "in": "query",
            "required": false,
            "description": "Filter on `patient_id`. Also accepts `patient_id[gte]`, `patient_id[lte]`, `patient_id[gt]`, `patient_id[lt]`, `patient_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "staff_id",
            "in": "query",
            "required": false,
            "description": "Filter on `staff_id`. Also accepts `staff_id[gte]`, `staff_id[lte]`, `staff_id[gt]`, `staff_id[lt]`, `staff_id[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "chair_id",
            "in": "query",
            "required": false,
            "description": "Filter on `chair_id`. Also accepts `chair_id[gte]`, `chair_id[lte]`, `chair_id[gt]`, `chair_id[lt]`, `chair_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter on `status`. Also accepts `status[gte]`, `status[lte]`, `status[gt]`, `status[lt]`, `status[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "scheduled_time",
            "in": "query",
            "required": false,
            "description": "Filter on `scheduled_time`. Also accepts `scheduled_time[gte]`, `scheduled_time[lte]`, `scheduled_time[gt]`, `scheduled_time[lt]`, `scheduled_time[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "booked_via_portal",
            "in": "query",
            "required": false,
            "description": "Filter on `booked_via_portal`. Also accepts `booked_via_portal[gte]`, `booked_via_portal[lte]`, `booked_via_portal[gt]`, `booked_via_portal[lt]`, `booked_via_portal[in]` (comma-separated).",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "created_at",
            "in": "query",
            "required": false,
            "description": "Filter on `created_at`. Also accepts `created_at[gte]`, `created_at[lte]`, `created_at[gt]`, `created_at[lt]`, `created_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "updated_at",
            "in": "query",
            "required": false,
            "description": "Filter on `updated_at`. Also accepts `updated_at[gte]`, `updated_at[lte]`, `updated_at[gt]`, `updated_at[lt]`, `updated_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of rows.",
            "headers": {
              "Link": {
                "description": "Contains `rel=\"next\"` when another page exists.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/appointments"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Null means this was the last page. A FULL page always carries a cursor even if the next one turns out to be empty; never infer the end from a short page alone."
                        },
                        "total": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "Only with ?include_total=true."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown field in fields/sort/filter, or a malformed cursor.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `appointments:read` scope.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create an appointment",
        "operationId": "create_appointments",
        "tags": [
          "appointments"
        ],
        "security": [
          {
            "apiKey": [
              "appointments:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/appointments_create"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created. The new row, under `data`.",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              },
              "ETag": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/appointments"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Body is not JSON, or names a field that cannot be written. See `errors[]`; values are never echoed back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `appointments:write`, the bound role may not write this, the branch is not allowed, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "An identical Idempotency-Key is still in flight.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "A required field is missing. See `errors[]`. Note that a field which simply cannot be written is a 400 `unknown_field`, not a 422.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/appointments/{id}": {
      "get": {
        "summary": "Get an appointment",
        "operationId": "get_appointments",
        "tags": [
          "appointments"
        ],
        "security": [
          {
            "apiKey": [
              "appointments:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The row, under `data`.",
            "headers": {
              "ETag": {
                "description": "Weak validator for If-Match on a future write.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/appointments"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `appointments:read` scope, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row IN THIS CLINIC. A row belonging to another clinic also returns 404, never 403, so the API never confirms that an id exists elsewhere.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update an appointment",
        "description": "Only the fields you send are changed.",
        "operationId": "update_appointments",
        "tags": [
          "appointments"
        ],
        "security": [
          {
            "apiKey": [
              "appointments:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "The ETag from a previous GET. The write then applies only if nothing changed in between, otherwise 412. Not supported on resources with no updated_at column.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/appointments_update"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated row, under `data`.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/appointments"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Body is not JSON, or names a field that cannot be patched. See `errors[]`. `appointments.status` and `treatment_plans.status` report `create_only` here.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `appointments:write`, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row in this clinic. Also returned for another clinic's row.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "412": {
            "description": "If-Match did not match, or the row changed between read and write.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Soft-delete an appointment",
        "description": "Sets `deleted_at`. There is no hard delete in this API: the row stays restorable from Trash in the app.",
        "operationId": "delete_appointments",
        "tags": [
          "appointments"
        ],
        "security": [
          {
            "apiKey": [
              "appointments:delete"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "The ETag from a previous GET. The write then applies only if nothing changed in between, otherwise 412. Not supported on resources with no updated_at column.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Soft-deleted. No body."
          },
          "400": {
            "description": "Body is not JSON, or names a field that cannot be patched. See `errors[]`. `appointments.status` and `treatment_plans.status` report `create_only` here.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `appointments:delete`, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row in this clinic. Also returned for another clinic's row.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "412": {
            "description": "If-Match did not match, or the row changed between read and write.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/treatment_plans": {
      "get": {
        "summary": "List treatment plans",
        "operationId": "list_treatment_plans",
        "tags": [
          "treatment_plans"
        ],
        "security": [
          {
            "apiKey": [
              "treatment:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size. Default 50, clamped to 200 rather than rejected.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque keyset cursor from `meta.next_cursor`. Do not construct one by hand. There is no offset parameter: PostgREST caps a range at 1000 rows and truncates silently.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "description": "Comma-separated subset of: id, clinic_id, branch_id, patient_id, appointment_id, dentist_id, chair_id, status, payment_status, clinical_notes, teeth_codes, tooth_notes, finalized_at, import_report_id, created_at, updated_at.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sortable: created_at, updated_at, finalized_at. Prefix with `-` for descending. Default `-created_at`. An `id` tiebreak is always appended so the order is total.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_total",
            "in": "query",
            "required": false,
            "description": "Run an exact count and return it as `meta.total`. Expensive; counts double against the rate limit.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "include_deleted",
            "in": "query",
            "required": false,
            "description": "Include soft-deleted rows. `deleted_at` itself is never returned.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "exclude_migrated",
            "in": "query",
            "required": false,
            "description": "Exclude rows created by a bulk import (`import_report_id is null`).",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "description": "Filter on `id`. Also accepts `id[gte]`, `id[lte]`, `id[gt]`, `id[lt]`, `id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "branch_id",
            "in": "query",
            "required": false,
            "description": "Filter on `branch_id`. Also accepts `branch_id[gte]`, `branch_id[lte]`, `branch_id[gt]`, `branch_id[lt]`, `branch_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "patient_id",
            "in": "query",
            "required": false,
            "description": "Filter on `patient_id`. Also accepts `patient_id[gte]`, `patient_id[lte]`, `patient_id[gt]`, `patient_id[lt]`, `patient_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "appointment_id",
            "in": "query",
            "required": false,
            "description": "Filter on `appointment_id`. Also accepts `appointment_id[gte]`, `appointment_id[lte]`, `appointment_id[gt]`, `appointment_id[lt]`, `appointment_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "dentist_id",
            "in": "query",
            "required": false,
            "description": "Filter on `dentist_id`. Also accepts `dentist_id[gte]`, `dentist_id[lte]`, `dentist_id[gt]`, `dentist_id[lt]`, `dentist_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "chair_id",
            "in": "query",
            "required": false,
            "description": "Filter on `chair_id`. Also accepts `chair_id[gte]`, `chair_id[lte]`, `chair_id[gt]`, `chair_id[lt]`, `chair_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter on `status`. Also accepts `status[gte]`, `status[lte]`, `status[gt]`, `status[lt]`, `status[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "payment_status",
            "in": "query",
            "required": false,
            "description": "Filter on `payment_status`. Also accepts `payment_status[gte]`, `payment_status[lte]`, `payment_status[gt]`, `payment_status[lt]`, `payment_status[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "finalized_at",
            "in": "query",
            "required": false,
            "description": "Filter on `finalized_at`. Also accepts `finalized_at[gte]`, `finalized_at[lte]`, `finalized_at[gt]`, `finalized_at[lt]`, `finalized_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "created_at",
            "in": "query",
            "required": false,
            "description": "Filter on `created_at`. Also accepts `created_at[gte]`, `created_at[lte]`, `created_at[gt]`, `created_at[lt]`, `created_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "updated_at",
            "in": "query",
            "required": false,
            "description": "Filter on `updated_at`. Also accepts `updated_at[gte]`, `updated_at[lte]`, `updated_at[gt]`, `updated_at[lt]`, `updated_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of rows.",
            "headers": {
              "Link": {
                "description": "Contains `rel=\"next\"` when another page exists.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/treatment_plans"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Null means this was the last page. A FULL page always carries a cursor even if the next one turns out to be empty; never infer the end from a short page alone."
                        },
                        "total": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "Only with ?include_total=true."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown field in fields/sort/filter, or a malformed cursor.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `treatment:read` scope.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a treatment plan",
        "operationId": "create_treatment_plans",
        "tags": [
          "treatment_plans"
        ],
        "security": [
          {
            "apiKey": [
              "treatment:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/treatment_plans_create"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created. The new row, under `data`.",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              },
              "ETag": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/treatment_plans"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Body is not JSON, or names a field that cannot be written. See `errors[]`; values are never echoed back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `treatment:write`, the bound role may not write this, the branch is not allowed, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "An identical Idempotency-Key is still in flight.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "A required field is missing. See `errors[]`. Note that a field which simply cannot be written is a 400 `unknown_field`, not a 422.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/treatment_plans/{id}": {
      "get": {
        "summary": "Get a treatment plan",
        "operationId": "get_treatment_plans",
        "tags": [
          "treatment_plans"
        ],
        "security": [
          {
            "apiKey": [
              "treatment:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The row, under `data`.",
            "headers": {
              "ETag": {
                "description": "Weak validator for If-Match on a future write.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/treatment_plans"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `treatment:read` scope, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row IN THIS CLINIC. A row belonging to another clinic also returns 404, never 403, so the API never confirms that an id exists elsewhere.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update a treatment plan",
        "description": "Only the fields you send are changed.",
        "operationId": "update_treatment_plans",
        "tags": [
          "treatment_plans"
        ],
        "security": [
          {
            "apiKey": [
              "treatment:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "The ETag from a previous GET. The write then applies only if nothing changed in between, otherwise 412. Not supported on resources with no updated_at column.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/treatment_plans_update"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated row, under `data`.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/treatment_plans"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Body is not JSON, or names a field that cannot be patched. See `errors[]`. `appointments.status` and `treatment_plans.status` report `create_only` here.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `treatment:write`, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row in this clinic. Also returned for another clinic's row.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "412": {
            "description": "If-Match did not match, or the row changed between read and write.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Soft-delete a treatment plan",
        "description": "Sets `deleted_at`. There is no hard delete in this API: the row stays restorable from Trash in the app.",
        "operationId": "delete_treatment_plans",
        "tags": [
          "treatment_plans"
        ],
        "security": [
          {
            "apiKey": [
              "treatment:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "The ETag from a previous GET. The write then applies only if nothing changed in between, otherwise 412. Not supported on resources with no updated_at column.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Soft-deleted. No body."
          },
          "400": {
            "description": "Body is not JSON, or names a field that cannot be patched. See `errors[]`. `appointments.status` and `treatment_plans.status` report `create_only` here.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `treatment:write`, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row in this clinic. Also returned for another clinic's row.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "412": {
            "description": "If-Match did not match, or the row changed between read and write.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/treatment_items": {
      "get": {
        "summary": "List treatment items",
        "operationId": "list_treatment_items",
        "tags": [
          "treatment_items"
        ],
        "security": [
          {
            "apiKey": [
              "treatment:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size. Default 50, clamped to 200 rather than rejected.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque keyset cursor from `meta.next_cursor`. Do not construct one by hand. There is no offset parameter: PostgREST caps a range at 1000 rows and truncates silently.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "description": "Comma-separated subset of: id, clinic_id, treatment_plan_id, catalog_item_id, catalog_procedure_id, item_type, item_name, teeth_codes, unit_price, qty, discount, final_price, dosage_override, clinical_status, billed_at, notes, created_at, updated_at.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sortable: created_at, updated_at. Prefix with `-` for descending. Default `-created_at`. An `id` tiebreak is always appended so the order is total.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_total",
            "in": "query",
            "required": false,
            "description": "Run an exact count and return it as `meta.total`. Expensive; counts double against the rate limit.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "include_deleted",
            "in": "query",
            "required": false,
            "description": "Include soft-deleted rows. `deleted_at` itself is never returned.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "description": "Filter on `id`. Also accepts `id[gte]`, `id[lte]`, `id[gt]`, `id[lt]`, `id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "treatment_plan_id",
            "in": "query",
            "required": false,
            "description": "Filter on `treatment_plan_id`. Also accepts `treatment_plan_id[gte]`, `treatment_plan_id[lte]`, `treatment_plan_id[gt]`, `treatment_plan_id[lt]`, `treatment_plan_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "catalog_item_id",
            "in": "query",
            "required": false,
            "description": "Filter on `catalog_item_id`. Also accepts `catalog_item_id[gte]`, `catalog_item_id[lte]`, `catalog_item_id[gt]`, `catalog_item_id[lt]`, `catalog_item_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "item_type",
            "in": "query",
            "required": false,
            "description": "Filter on `item_type`. Also accepts `item_type[gte]`, `item_type[lte]`, `item_type[gt]`, `item_type[lt]`, `item_type[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "clinical_status",
            "in": "query",
            "required": false,
            "description": "Filter on `clinical_status`. Also accepts `clinical_status[gte]`, `clinical_status[lte]`, `clinical_status[gt]`, `clinical_status[lt]`, `clinical_status[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "billed_at",
            "in": "query",
            "required": false,
            "description": "Filter on `billed_at`. Also accepts `billed_at[gte]`, `billed_at[lte]`, `billed_at[gt]`, `billed_at[lt]`, `billed_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "created_at",
            "in": "query",
            "required": false,
            "description": "Filter on `created_at`. Also accepts `created_at[gte]`, `created_at[lte]`, `created_at[gt]`, `created_at[lt]`, `created_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "updated_at",
            "in": "query",
            "required": false,
            "description": "Filter on `updated_at`. Also accepts `updated_at[gte]`, `updated_at[lte]`, `updated_at[gt]`, `updated_at[lt]`, `updated_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of rows.",
            "headers": {
              "Link": {
                "description": "Contains `rel=\"next\"` when another page exists.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/treatment_items"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Null means this was the last page. A FULL page always carries a cursor even if the next one turns out to be empty; never infer the end from a short page alone."
                        },
                        "total": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "Only with ?include_total=true."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown field in fields/sort/filter, or a malformed cursor.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `treatment:read` scope.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/treatment_items/{id}": {
      "get": {
        "summary": "Get a treatment item",
        "operationId": "get_treatment_items",
        "tags": [
          "treatment_items"
        ],
        "security": [
          {
            "apiKey": [
              "treatment:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The row, under `data`.",
            "headers": {
              "ETag": {
                "description": "Weak validator for If-Match on a future write.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/treatment_items"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `treatment:read` scope, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row IN THIS CLINIC. A row belonging to another clinic also returns 404, never 403, so the API never confirms that an id exists elsewhere.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/medical_history": {
      "get": {
        "summary": "List medical history entries",
        "operationId": "list_medical_history",
        "tags": [
          "medical_history"
        ],
        "security": [
          {
            "apiKey": [
              "clinical:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size. Default 50, clamped to 200 rather than rejected.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque keyset cursor from `meta.next_cursor`. Do not construct one by hand. There is no offset parameter: PostgREST caps a range at 1000 rows and truncates silently.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "description": "Comma-separated subset of: id, clinic_id, patient_id, condition_type, condition_name, is_ongoing, notes, added_by_staff_id, updated_by_staff_id, created_at, updated_at.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sortable: created_at, updated_at. Prefix with `-` for descending. Default `-created_at`. An `id` tiebreak is always appended so the order is total.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_total",
            "in": "query",
            "required": false,
            "description": "Run an exact count and return it as `meta.total`. Expensive; counts double against the rate limit.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "include_deleted",
            "in": "query",
            "required": false,
            "description": "Include soft-deleted rows. `deleted_at` itself is never returned.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "description": "Filter on `id`. Also accepts `id[gte]`, `id[lte]`, `id[gt]`, `id[lt]`, `id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "patient_id",
            "in": "query",
            "required": false,
            "description": "Filter on `patient_id`. Also accepts `patient_id[gte]`, `patient_id[lte]`, `patient_id[gt]`, `patient_id[lt]`, `patient_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "condition_type",
            "in": "query",
            "required": false,
            "description": "Filter on `condition_type`. Also accepts `condition_type[gte]`, `condition_type[lte]`, `condition_type[gt]`, `condition_type[lt]`, `condition_type[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "is_ongoing",
            "in": "query",
            "required": false,
            "description": "Filter on `is_ongoing`. Also accepts `is_ongoing[gte]`, `is_ongoing[lte]`, `is_ongoing[gt]`, `is_ongoing[lt]`, `is_ongoing[in]` (comma-separated).",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "created_at",
            "in": "query",
            "required": false,
            "description": "Filter on `created_at`. Also accepts `created_at[gte]`, `created_at[lte]`, `created_at[gt]`, `created_at[lt]`, `created_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "updated_at",
            "in": "query",
            "required": false,
            "description": "Filter on `updated_at`. Also accepts `updated_at[gte]`, `updated_at[lte]`, `updated_at[gt]`, `updated_at[lt]`, `updated_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of rows.",
            "headers": {
              "Link": {
                "description": "Contains `rel=\"next\"` when another page exists.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/medical_history"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Null means this was the last page. A FULL page always carries a cursor even if the next one turns out to be empty; never infer the end from a short page alone."
                        },
                        "total": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "Only with ?include_total=true."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown field in fields/sort/filter, or a malformed cursor.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `clinical:read` scope.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a medical history entry",
        "operationId": "create_medical_history",
        "tags": [
          "medical_history"
        ],
        "security": [
          {
            "apiKey": [
              "clinical:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/medical_history_create"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created. The new row, under `data`.",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              },
              "ETag": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/medical_history"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Body is not JSON, or names a field that cannot be written. See `errors[]`; values are never echoed back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `clinical:write`, the bound role may not write this, the branch is not allowed, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "An identical Idempotency-Key is still in flight.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "A required field is missing. See `errors[]`. Note that a field which simply cannot be written is a 400 `unknown_field`, not a 422.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/medical_history/{id}": {
      "get": {
        "summary": "Get a medical history entry",
        "operationId": "get_medical_history",
        "tags": [
          "medical_history"
        ],
        "security": [
          {
            "apiKey": [
              "clinical:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The row, under `data`.",
            "headers": {
              "ETag": {
                "description": "Weak validator for If-Match on a future write.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/medical_history"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `clinical:read` scope, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row IN THIS CLINIC. A row belonging to another clinic also returns 404, never 403, so the API never confirms that an id exists elsewhere.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update a medical history entry",
        "description": "Only the fields you send are changed.",
        "operationId": "update_medical_history",
        "tags": [
          "medical_history"
        ],
        "security": [
          {
            "apiKey": [
              "clinical:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "The ETag from a previous GET. The write then applies only if nothing changed in between, otherwise 412. Not supported on resources with no updated_at column.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/medical_history_update"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated row, under `data`.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/medical_history"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Body is not JSON, or names a field that cannot be patched. See `errors[]`. `appointments.status` and `treatment_plans.status` report `create_only` here.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `clinical:write`, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row in this clinic. Also returned for another clinic's row.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "412": {
            "description": "If-Match did not match, or the row changed between read and write.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Soft-delete a medical history entry",
        "description": "Sets `deleted_at`. There is no hard delete in this API: the row stays restorable from Trash in the app.",
        "operationId": "delete_medical_history",
        "tags": [
          "medical_history"
        ],
        "security": [
          {
            "apiKey": [
              "clinical:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "The ETag from a previous GET. The write then applies only if nothing changed in between, otherwise 412. Not supported on resources with no updated_at column.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Soft-deleted. No body."
          },
          "400": {
            "description": "Body is not JSON, or names a field that cannot be patched. See `errors[]`. `appointments.status` and `treatment_plans.status` report `create_only` here.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `clinical:write`, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row in this clinic. Also returned for another clinic's row.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "412": {
            "description": "If-Match did not match, or the row changed between read and write.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/patient_journey": {
      "get": {
        "summary": "List patient journey entries",
        "operationId": "list_patient_journey",
        "tags": [
          "patient_journey"
        ],
        "security": [
          {
            "apiKey": [
              "clinical:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size. Default 50, clamped to 200 rather than rejected.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque keyset cursor from `meta.next_cursor`. Do not construct one by hand. There is no offset parameter: PostgREST caps a range at 1000 rows and truncates silently.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "description": "Comma-separated subset of: id, clinic_id, branch_id, patient_id, appointment_id, treatment_plan_id, status, is_emergency, entered_status_at, exited_status_at, duration_minutes, created_at, updated_at.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sortable: entered_status_at, created_at, updated_at. Prefix with `-` for descending. Default `-entered_status_at`. An `id` tiebreak is always appended so the order is total.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_total",
            "in": "query",
            "required": false,
            "description": "Run an exact count and return it as `meta.total`. Expensive; counts double against the rate limit.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "include_deleted",
            "in": "query",
            "required": false,
            "description": "Include soft-deleted rows. `deleted_at` itself is never returned.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "description": "Filter on `id`. Also accepts `id[gte]`, `id[lte]`, `id[gt]`, `id[lt]`, `id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "branch_id",
            "in": "query",
            "required": false,
            "description": "Filter on `branch_id`. Also accepts `branch_id[gte]`, `branch_id[lte]`, `branch_id[gt]`, `branch_id[lt]`, `branch_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "patient_id",
            "in": "query",
            "required": false,
            "description": "Filter on `patient_id`. Also accepts `patient_id[gte]`, `patient_id[lte]`, `patient_id[gt]`, `patient_id[lt]`, `patient_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "appointment_id",
            "in": "query",
            "required": false,
            "description": "Filter on `appointment_id`. Also accepts `appointment_id[gte]`, `appointment_id[lte]`, `appointment_id[gt]`, `appointment_id[lt]`, `appointment_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "treatment_plan_id",
            "in": "query",
            "required": false,
            "description": "Filter on `treatment_plan_id`. Also accepts `treatment_plan_id[gte]`, `treatment_plan_id[lte]`, `treatment_plan_id[gt]`, `treatment_plan_id[lt]`, `treatment_plan_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter on `status`. Also accepts `status[gte]`, `status[lte]`, `status[gt]`, `status[lt]`, `status[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "is_emergency",
            "in": "query",
            "required": false,
            "description": "Filter on `is_emergency`. Also accepts `is_emergency[gte]`, `is_emergency[lte]`, `is_emergency[gt]`, `is_emergency[lt]`, `is_emergency[in]` (comma-separated).",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "entered_status_at",
            "in": "query",
            "required": false,
            "description": "Filter on `entered_status_at`. Also accepts `entered_status_at[gte]`, `entered_status_at[lte]`, `entered_status_at[gt]`, `entered_status_at[lt]`, `entered_status_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "created_at",
            "in": "query",
            "required": false,
            "description": "Filter on `created_at`. Also accepts `created_at[gte]`, `created_at[lte]`, `created_at[gt]`, `created_at[lt]`, `created_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of rows.",
            "headers": {
              "Link": {
                "description": "Contains `rel=\"next\"` when another page exists.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/patient_journey"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Null means this was the last page. A FULL page always carries a cursor even if the next one turns out to be empty; never infer the end from a short page alone."
                        },
                        "total": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "Only with ?include_total=true."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown field in fields/sort/filter, or a malformed cursor.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `clinical:read` scope.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/patient_journey/{id}": {
      "get": {
        "summary": "Get a patient journey entry",
        "operationId": "get_patient_journey",
        "tags": [
          "patient_journey"
        ],
        "security": [
          {
            "apiKey": [
              "clinical:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The row, under `data`.",
            "headers": {
              "ETag": {
                "description": "Weak validator for If-Match on a future write.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/patient_journey"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `clinical:read` scope, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row IN THIS CLINIC. A row belonging to another clinic also returns 404, never 403, so the API never confirms that an id exists elsewhere.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/families": {
      "get": {
        "summary": "List families",
        "operationId": "list_families",
        "tags": [
          "families"
        ],
        "security": [
          {
            "apiKey": [
              "patients:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size. Default 50, clamped to 200 rather than rejected.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque keyset cursor from `meta.next_cursor`. Do not construct one by hand. There is no offset parameter: PostgREST caps a range at 1000 rows and truncates silently.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "description": "Comma-separated subset of: id, clinic_id, head_of_family_id, family_name, import_report_id, created_at, updated_at.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sortable: created_at, updated_at, family_name. Prefix with `-` for descending. Default `-created_at`. An `id` tiebreak is always appended so the order is total.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_total",
            "in": "query",
            "required": false,
            "description": "Run an exact count and return it as `meta.total`. Expensive; counts double against the rate limit.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "include_deleted",
            "in": "query",
            "required": false,
            "description": "Include soft-deleted rows. `deleted_at` itself is never returned.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "exclude_migrated",
            "in": "query",
            "required": false,
            "description": "Exclude rows created by a bulk import (`import_report_id is null`).",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "description": "Filter on `id`. Also accepts `id[gte]`, `id[lte]`, `id[gt]`, `id[lt]`, `id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "head_of_family_id",
            "in": "query",
            "required": false,
            "description": "Filter on `head_of_family_id`. Also accepts `head_of_family_id[gte]`, `head_of_family_id[lte]`, `head_of_family_id[gt]`, `head_of_family_id[lt]`, `head_of_family_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "family_name",
            "in": "query",
            "required": false,
            "description": "Filter on `family_name`. Also accepts `family_name[gte]`, `family_name[lte]`, `family_name[gt]`, `family_name[lt]`, `family_name[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "created_at",
            "in": "query",
            "required": false,
            "description": "Filter on `created_at`. Also accepts `created_at[gte]`, `created_at[lte]`, `created_at[gt]`, `created_at[lt]`, `created_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "updated_at",
            "in": "query",
            "required": false,
            "description": "Filter on `updated_at`. Also accepts `updated_at[gte]`, `updated_at[lte]`, `updated_at[gt]`, `updated_at[lt]`, `updated_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of rows.",
            "headers": {
              "Link": {
                "description": "Contains `rel=\"next\"` when another page exists.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/families"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Null means this was the last page. A FULL page always carries a cursor even if the next one turns out to be empty; never infer the end from a short page alone."
                        },
                        "total": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "Only with ?include_total=true."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown field in fields/sort/filter, or a malformed cursor.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `patients:read` scope.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a family",
        "operationId": "create_families",
        "tags": [
          "families"
        ],
        "security": [
          {
            "apiKey": [
              "patients:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/families_create"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created. The new row, under `data`.",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              },
              "ETag": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/families"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Body is not JSON, or names a field that cannot be written. See `errors[]`; values are never echoed back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `patients:write`, the bound role may not write this, the branch is not allowed, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "An identical Idempotency-Key is still in flight.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "A required field is missing. See `errors[]`. Note that a field which simply cannot be written is a 400 `unknown_field`, not a 422.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/families/{id}": {
      "get": {
        "summary": "Get a family",
        "operationId": "get_families",
        "tags": [
          "families"
        ],
        "security": [
          {
            "apiKey": [
              "patients:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The row, under `data`.",
            "headers": {
              "ETag": {
                "description": "Weak validator for If-Match on a future write.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/families"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `patients:read` scope, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row IN THIS CLINIC. A row belonging to another clinic also returns 404, never 403, so the API never confirms that an id exists elsewhere.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update a family",
        "description": "Only the fields you send are changed.",
        "operationId": "update_families",
        "tags": [
          "families"
        ],
        "security": [
          {
            "apiKey": [
              "patients:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "The ETag from a previous GET. The write then applies only if nothing changed in between, otherwise 412. Not supported on resources with no updated_at column.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/families_update"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated row, under `data`.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/families"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Body is not JSON, or names a field that cannot be patched. See `errors[]`. `appointments.status` and `treatment_plans.status` report `create_only` here.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `patients:write`, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row in this clinic. Also returned for another clinic's row.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "412": {
            "description": "If-Match did not match, or the row changed between read and write.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Soft-delete a family",
        "description": "Sets `deleted_at`. There is no hard delete in this API: the row stays restorable from Trash in the app.",
        "operationId": "delete_families",
        "tags": [
          "families"
        ],
        "security": [
          {
            "apiKey": [
              "patients:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "The ETag from a previous GET. The write then applies only if nothing changed in between, otherwise 412. Not supported on resources with no updated_at column.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Soft-deleted. No body."
          },
          "400": {
            "description": "Body is not JSON, or names a field that cannot be patched. See `errors[]`. `appointments.status` and `treatment_plans.status` report `create_only` here.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `patients:write`, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row in this clinic. Also returned for another clinic's row.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "412": {
            "description": "If-Match did not match, or the row changed between read and write.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/patient_insurance": {
      "get": {
        "summary": "List patient insurance policies",
        "operationId": "list_patient_insurance",
        "tags": [
          "patient_insurance"
        ],
        "security": [
          {
            "apiKey": [
              "patients:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size. Default 50, clamped to 200 rather than rejected.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque keyset cursor from `meta.next_cursor`. Do not construct one by hand. There is no offset parameter: PostgREST caps a range at 1000 rows and truncates silently.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "description": "Comma-separated subset of: id, clinic_id, patient_id, insurance_carrier_id, provider_name, policy_number, group_number, holder_name, is_primary, created_at, updated_at.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sortable: created_at, updated_at. Prefix with `-` for descending. Default `-created_at`. An `id` tiebreak is always appended so the order is total.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_total",
            "in": "query",
            "required": false,
            "description": "Run an exact count and return it as `meta.total`. Expensive; counts double against the rate limit.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "include_deleted",
            "in": "query",
            "required": false,
            "description": "Include soft-deleted rows. `deleted_at` itself is never returned.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "description": "Filter on `id`. Also accepts `id[gte]`, `id[lte]`, `id[gt]`, `id[lt]`, `id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "patient_id",
            "in": "query",
            "required": false,
            "description": "Filter on `patient_id`. Also accepts `patient_id[gte]`, `patient_id[lte]`, `patient_id[gt]`, `patient_id[lt]`, `patient_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "insurance_carrier_id",
            "in": "query",
            "required": false,
            "description": "Filter on `insurance_carrier_id`. Also accepts `insurance_carrier_id[gte]`, `insurance_carrier_id[lte]`, `insurance_carrier_id[gt]`, `insurance_carrier_id[lt]`, `insurance_carrier_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "is_primary",
            "in": "query",
            "required": false,
            "description": "Filter on `is_primary`. Also accepts `is_primary[gte]`, `is_primary[lte]`, `is_primary[gt]`, `is_primary[lt]`, `is_primary[in]` (comma-separated).",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "created_at",
            "in": "query",
            "required": false,
            "description": "Filter on `created_at`. Also accepts `created_at[gte]`, `created_at[lte]`, `created_at[gt]`, `created_at[lt]`, `created_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "updated_at",
            "in": "query",
            "required": false,
            "description": "Filter on `updated_at`. Also accepts `updated_at[gte]`, `updated_at[lte]`, `updated_at[gt]`, `updated_at[lt]`, `updated_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of rows.",
            "headers": {
              "Link": {
                "description": "Contains `rel=\"next\"` when another page exists.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/patient_insurance"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Null means this was the last page. A FULL page always carries a cursor even if the next one turns out to be empty; never infer the end from a short page alone."
                        },
                        "total": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "Only with ?include_total=true."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown field in fields/sort/filter, or a malformed cursor.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `patients:read` scope.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a patient insurance policy",
        "operationId": "create_patient_insurance",
        "tags": [
          "patient_insurance"
        ],
        "security": [
          {
            "apiKey": [
              "patients:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/patient_insurance_create"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created. The new row, under `data`.",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              },
              "ETag": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/patient_insurance"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Body is not JSON, or names a field that cannot be written. See `errors[]`; values are never echoed back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `patients:write`, the bound role may not write this, the branch is not allowed, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "An identical Idempotency-Key is still in flight.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "A required field is missing. See `errors[]`. Note that a field which simply cannot be written is a 400 `unknown_field`, not a 422.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/patient_insurance/{id}": {
      "get": {
        "summary": "Get a patient insurance policy",
        "operationId": "get_patient_insurance",
        "tags": [
          "patient_insurance"
        ],
        "security": [
          {
            "apiKey": [
              "patients:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The row, under `data`.",
            "headers": {
              "ETag": {
                "description": "Weak validator for If-Match on a future write.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/patient_insurance"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `patients:read` scope, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row IN THIS CLINIC. A row belonging to another clinic also returns 404, never 403, so the API never confirms that an id exists elsewhere.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update a patient insurance policy",
        "description": "Only the fields you send are changed.",
        "operationId": "update_patient_insurance",
        "tags": [
          "patient_insurance"
        ],
        "security": [
          {
            "apiKey": [
              "patients:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "The ETag from a previous GET. The write then applies only if nothing changed in between, otherwise 412. Not supported on resources with no updated_at column.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/patient_insurance_update"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated row, under `data`.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/patient_insurance"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Body is not JSON, or names a field that cannot be patched. See `errors[]`. `appointments.status` and `treatment_plans.status` report `create_only` here.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `patients:write`, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row in this clinic. Also returned for another clinic's row.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "412": {
            "description": "If-Match did not match, or the row changed between read and write.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Soft-delete a patient insurance policy",
        "description": "Sets `deleted_at`. There is no hard delete in this API: the row stays restorable from Trash in the app.",
        "operationId": "delete_patient_insurance",
        "tags": [
          "patient_insurance"
        ],
        "security": [
          {
            "apiKey": [
              "patients:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "The ETag from a previous GET. The write then applies only if nothing changed in between, otherwise 412. Not supported on resources with no updated_at column.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Soft-deleted. No body."
          },
          "400": {
            "description": "Body is not JSON, or names a field that cannot be patched. See `errors[]`. `appointments.status` and `treatment_plans.status` report `create_only` here.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `patients:write`, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row in this clinic. Also returned for another clinic's row.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "412": {
            "description": "If-Match did not match, or the row changed between read and write.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/billing": {
      "get": {
        "summary": "List billing records",
        "operationId": "list_billing",
        "tags": [
          "billing"
        ],
        "security": [
          {
            "apiKey": [
              "billing:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size. Default 50, clamped to 200 rather than rejected.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque keyset cursor from `meta.next_cursor`. Do not construct one by hand. There is no offset parameter: PostgREST caps a range at 1000 rows and truncates silently.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "description": "Comma-separated subset of: id, clinic_id, patient_id, treatment_plan_id, receipt_number, total_amount, discount_applied, tax_applied, final_amount_due, amount_paid, balance_due, status, is_finalized, finalized_at, import_report_id, created_at, updated_at.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sortable: created_at, updated_at, finalized_at. Prefix with `-` for descending. Default `-created_at`. An `id` tiebreak is always appended so the order is total.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_total",
            "in": "query",
            "required": false,
            "description": "Run an exact count and return it as `meta.total`. Expensive; counts double against the rate limit.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "include_deleted",
            "in": "query",
            "required": false,
            "description": "Include soft-deleted rows. `deleted_at` itself is never returned.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "exclude_migrated",
            "in": "query",
            "required": false,
            "description": "Exclude rows created by a bulk import (`import_report_id is null`).",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "description": "Filter on `id`. Also accepts `id[gte]`, `id[lte]`, `id[gt]`, `id[lt]`, `id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "patient_id",
            "in": "query",
            "required": false,
            "description": "Filter on `patient_id`. Also accepts `patient_id[gte]`, `patient_id[lte]`, `patient_id[gt]`, `patient_id[lt]`, `patient_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "treatment_plan_id",
            "in": "query",
            "required": false,
            "description": "Filter on `treatment_plan_id`. Also accepts `treatment_plan_id[gte]`, `treatment_plan_id[lte]`, `treatment_plan_id[gt]`, `treatment_plan_id[lt]`, `treatment_plan_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter on `status`. Also accepts `status[gte]`, `status[lte]`, `status[gt]`, `status[lt]`, `status[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "is_finalized",
            "in": "query",
            "required": false,
            "description": "Filter on `is_finalized`. Also accepts `is_finalized[gte]`, `is_finalized[lte]`, `is_finalized[gt]`, `is_finalized[lt]`, `is_finalized[in]` (comma-separated).",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "receipt_number",
            "in": "query",
            "required": false,
            "description": "Filter on `receipt_number`. Also accepts `receipt_number[gte]`, `receipt_number[lte]`, `receipt_number[gt]`, `receipt_number[lt]`, `receipt_number[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "finalized_at",
            "in": "query",
            "required": false,
            "description": "Filter on `finalized_at`. Also accepts `finalized_at[gte]`, `finalized_at[lte]`, `finalized_at[gt]`, `finalized_at[lt]`, `finalized_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "created_at",
            "in": "query",
            "required": false,
            "description": "Filter on `created_at`. Also accepts `created_at[gte]`, `created_at[lte]`, `created_at[gt]`, `created_at[lt]`, `created_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "updated_at",
            "in": "query",
            "required": false,
            "description": "Filter on `updated_at`. Also accepts `updated_at[gte]`, `updated_at[lte]`, `updated_at[gt]`, `updated_at[lt]`, `updated_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of rows.",
            "headers": {
              "Link": {
                "description": "Contains `rel=\"next\"` when another page exists.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/billing"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Null means this was the last page. A FULL page always carries a cursor even if the next one turns out to be empty; never infer the end from a short page alone."
                        },
                        "total": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "Only with ?include_total=true."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown field in fields/sort/filter, or a malformed cursor.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `billing:read` scope.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/billing/{id}": {
      "get": {
        "summary": "Get a billing record",
        "operationId": "get_billing",
        "tags": [
          "billing"
        ],
        "security": [
          {
            "apiKey": [
              "billing:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The row, under `data`.",
            "headers": {
              "ETag": {
                "description": "Weak validator for If-Match on a future write.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/billing"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `billing:read` scope, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row IN THIS CLINIC. A row belonging to another clinic also returns 404, never 403, so the API never confirms that an id exists elsewhere.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/payments": {
      "get": {
        "summary": "List payments",
        "operationId": "list_payments",
        "tags": [
          "payments"
        ],
        "security": [
          {
            "apiKey": [
              "billing:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size. Default 50, clamped to 200 rather than rejected.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque keyset cursor from `meta.next_cursor`. Do not construct one by hand. There is no offset parameter: PostgREST caps a range at 1000 rows and truncates silently.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "description": "Comma-separated subset of: id, clinic_id, branch_id, billing_id, patient_id, received_by, amount_paid, payment_method, payment_date, is_installment, is_initial_payment, reference_number, transaction_id, card_last4, cardholder_name, mobile_money_number, mobile_money_provider, insurance_claim_ref, notes, import_report_id, created_at, updated_at.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sortable: payment_date, created_at, updated_at. Prefix with `-` for descending. Default `-payment_date`. An `id` tiebreak is always appended so the order is total.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_total",
            "in": "query",
            "required": false,
            "description": "Run an exact count and return it as `meta.total`. Expensive; counts double against the rate limit.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "include_deleted",
            "in": "query",
            "required": false,
            "description": "Include soft-deleted rows. `deleted_at` itself is never returned.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "exclude_migrated",
            "in": "query",
            "required": false,
            "description": "Exclude rows created by a bulk import (`import_report_id is null`).",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "description": "Filter on `id`. Also accepts `id[gte]`, `id[lte]`, `id[gt]`, `id[lt]`, `id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "branch_id",
            "in": "query",
            "required": false,
            "description": "Filter on `branch_id`. Also accepts `branch_id[gte]`, `branch_id[lte]`, `branch_id[gt]`, `branch_id[lt]`, `branch_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "billing_id",
            "in": "query",
            "required": false,
            "description": "Filter on `billing_id`. Also accepts `billing_id[gte]`, `billing_id[lte]`, `billing_id[gt]`, `billing_id[lt]`, `billing_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "patient_id",
            "in": "query",
            "required": false,
            "description": "Filter on `patient_id`. Also accepts `patient_id[gte]`, `patient_id[lte]`, `patient_id[gt]`, `patient_id[lt]`, `patient_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "received_by",
            "in": "query",
            "required": false,
            "description": "Filter on `received_by`. Also accepts `received_by[gte]`, `received_by[lte]`, `received_by[gt]`, `received_by[lt]`, `received_by[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "payment_method",
            "in": "query",
            "required": false,
            "description": "Filter on `payment_method`. Also accepts `payment_method[gte]`, `payment_method[lte]`, `payment_method[gt]`, `payment_method[lt]`, `payment_method[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "is_installment",
            "in": "query",
            "required": false,
            "description": "Filter on `is_installment`. Also accepts `is_installment[gte]`, `is_installment[lte]`, `is_installment[gt]`, `is_installment[lt]`, `is_installment[in]` (comma-separated).",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "payment_date",
            "in": "query",
            "required": false,
            "description": "Filter on `payment_date`. Also accepts `payment_date[gte]`, `payment_date[lte]`, `payment_date[gt]`, `payment_date[lt]`, `payment_date[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "reference_number",
            "in": "query",
            "required": false,
            "description": "Filter on `reference_number`. Also accepts `reference_number[gte]`, `reference_number[lte]`, `reference_number[gt]`, `reference_number[lt]`, `reference_number[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "created_at",
            "in": "query",
            "required": false,
            "description": "Filter on `created_at`. Also accepts `created_at[gte]`, `created_at[lte]`, `created_at[gt]`, `created_at[lt]`, `created_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "updated_at",
            "in": "query",
            "required": false,
            "description": "Filter on `updated_at`. Also accepts `updated_at[gte]`, `updated_at[lte]`, `updated_at[gt]`, `updated_at[lt]`, `updated_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of rows.",
            "headers": {
              "Link": {
                "description": "Contains `rel=\"next\"` when another page exists.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/payments"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Null means this was the last page. A FULL page always carries a cursor even if the next one turns out to be empty; never infer the end from a short page alone."
                        },
                        "total": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "Only with ?include_total=true."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown field in fields/sort/filter, or a malformed cursor.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `billing:read` scope.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/payments/{id}": {
      "get": {
        "summary": "Get a payment",
        "operationId": "get_payments",
        "tags": [
          "payments"
        ],
        "security": [
          {
            "apiKey": [
              "billing:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The row, under `data`.",
            "headers": {
              "ETag": {
                "description": "Weak validator for If-Match on a future write.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/payments"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `billing:read` scope, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row IN THIS CLINIC. A row belonging to another clinic also returns 404, never 403, so the API never confirms that an id exists elsewhere.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/insurance_claims": {
      "get": {
        "summary": "List insurance claims",
        "operationId": "list_insurance_claims",
        "tags": [
          "insurance_claims"
        ],
        "security": [
          {
            "apiKey": [
              "billing:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size. Default 50, clamped to 200 rather than rejected.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque keyset cursor from `meta.next_cursor`. Do not construct one by hand. There is no offset parameter: PostgREST caps a range at 1000 rows and truncates silently.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "description": "Comma-separated subset of: id, clinic_id, patient_id, billing_id, provider_name, policy_number, claim_reference, amount_claimed, amount_approved, status, notes, created_at, updated_at.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sortable: created_at, updated_at. Prefix with `-` for descending. Default `-created_at`. An `id` tiebreak is always appended so the order is total.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_total",
            "in": "query",
            "required": false,
            "description": "Run an exact count and return it as `meta.total`. Expensive; counts double against the rate limit.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "include_deleted",
            "in": "query",
            "required": false,
            "description": "Include soft-deleted rows. `deleted_at` itself is never returned.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "description": "Filter on `id`. Also accepts `id[gte]`, `id[lte]`, `id[gt]`, `id[lt]`, `id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "patient_id",
            "in": "query",
            "required": false,
            "description": "Filter on `patient_id`. Also accepts `patient_id[gte]`, `patient_id[lte]`, `patient_id[gt]`, `patient_id[lt]`, `patient_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "billing_id",
            "in": "query",
            "required": false,
            "description": "Filter on `billing_id`. Also accepts `billing_id[gte]`, `billing_id[lte]`, `billing_id[gt]`, `billing_id[lt]`, `billing_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter on `status`. Also accepts `status[gte]`, `status[lte]`, `status[gt]`, `status[lt]`, `status[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "claim_reference",
            "in": "query",
            "required": false,
            "description": "Filter on `claim_reference`. Also accepts `claim_reference[gte]`, `claim_reference[lte]`, `claim_reference[gt]`, `claim_reference[lt]`, `claim_reference[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "created_at",
            "in": "query",
            "required": false,
            "description": "Filter on `created_at`. Also accepts `created_at[gte]`, `created_at[lte]`, `created_at[gt]`, `created_at[lt]`, `created_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "updated_at",
            "in": "query",
            "required": false,
            "description": "Filter on `updated_at`. Also accepts `updated_at[gte]`, `updated_at[lte]`, `updated_at[gt]`, `updated_at[lt]`, `updated_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of rows.",
            "headers": {
              "Link": {
                "description": "Contains `rel=\"next\"` when another page exists.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/insurance_claims"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Null means this was the last page. A FULL page always carries a cursor even if the next one turns out to be empty; never infer the end from a short page alone."
                        },
                        "total": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "Only with ?include_total=true."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown field in fields/sort/filter, or a malformed cursor.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `billing:read` scope.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/insurance_claims/{id}": {
      "get": {
        "summary": "Get an insurance claim",
        "operationId": "get_insurance_claims",
        "tags": [
          "insurance_claims"
        ],
        "security": [
          {
            "apiKey": [
              "billing:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The row, under `data`.",
            "headers": {
              "ETag": {
                "description": "Weak validator for If-Match on a future write.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/insurance_claims"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `billing:read` scope, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row IN THIS CLINIC. A row belonging to another clinic also returns 404, never 403, so the API never confirms that an id exists elsewhere.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/insurance_carriers": {
      "get": {
        "summary": "List insurance carriers",
        "operationId": "list_insurance_carriers",
        "tags": [
          "insurance_carriers"
        ],
        "security": [
          {
            "apiKey": [
              "billing:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size. Default 50, clamped to 200 rather than rejected.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque keyset cursor from `meta.next_cursor`. Do not construct one by hand. There is no offset parameter: PostgREST caps a range at 1000 rows and truncates silently.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "description": "Comma-separated subset of: id, clinic_id, name, is_active, created_at.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sortable: created_at, name. Prefix with `-` for descending. Default `-created_at`. An `id` tiebreak is always appended so the order is total.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_total",
            "in": "query",
            "required": false,
            "description": "Run an exact count and return it as `meta.total`. Expensive; counts double against the rate limit.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "include_deleted",
            "in": "query",
            "required": false,
            "description": "Include soft-deleted rows. `deleted_at` itself is never returned.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "description": "Filter on `id`. Also accepts `id[gte]`, `id[lte]`, `id[gt]`, `id[lt]`, `id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "description": "Filter on `name`. Also accepts `name[gte]`, `name[lte]`, `name[gt]`, `name[lt]`, `name[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "is_active",
            "in": "query",
            "required": false,
            "description": "Filter on `is_active`. Also accepts `is_active[gte]`, `is_active[lte]`, `is_active[gt]`, `is_active[lt]`, `is_active[in]` (comma-separated).",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "created_at",
            "in": "query",
            "required": false,
            "description": "Filter on `created_at`. Also accepts `created_at[gte]`, `created_at[lte]`, `created_at[gt]`, `created_at[lt]`, `created_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of rows.",
            "headers": {
              "Link": {
                "description": "Contains `rel=\"next\"` when another page exists.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/insurance_carriers"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Null means this was the last page. A FULL page always carries a cursor even if the next one turns out to be empty; never infer the end from a short page alone."
                        },
                        "total": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "Only with ?include_total=true."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown field in fields/sort/filter, or a malformed cursor.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `billing:read` scope.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create an insurance carrier",
        "operationId": "create_insurance_carriers",
        "tags": [
          "insurance_carriers"
        ],
        "security": [
          {
            "apiKey": [
              "catalog:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/insurance_carriers_create"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created. The new row, under `data`.",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              },
              "ETag": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/insurance_carriers"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Body is not JSON, or names a field that cannot be written. See `errors[]`; values are never echoed back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `catalog:write`, the bound role may not write this, the branch is not allowed, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "An identical Idempotency-Key is still in flight.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "A required field is missing. See `errors[]`. Note that a field which simply cannot be written is a 400 `unknown_field`, not a 422.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/insurance_carriers/{id}": {
      "get": {
        "summary": "Get an insurance carrier",
        "operationId": "get_insurance_carriers",
        "tags": [
          "insurance_carriers"
        ],
        "security": [
          {
            "apiKey": [
              "billing:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The row, under `data`.",
            "headers": {
              "ETag": {
                "description": "Weak validator for If-Match on a future write.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/insurance_carriers"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `billing:read` scope, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row IN THIS CLINIC. A row belonging to another clinic also returns 404, never 403, so the API never confirms that an id exists elsewhere.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update an insurance carrier",
        "description": "Only the fields you send are changed.",
        "operationId": "update_insurance_carriers",
        "tags": [
          "insurance_carriers"
        ],
        "security": [
          {
            "apiKey": [
              "catalog:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "The ETag from a previous GET. The write then applies only if nothing changed in between, otherwise 412. Not supported on resources with no updated_at column.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/insurance_carriers_update"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated row, under `data`.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/insurance_carriers"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Body is not JSON, or names a field that cannot be patched. See `errors[]`. `appointments.status` and `treatment_plans.status` report `create_only` here.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `catalog:write`, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row in this clinic. Also returned for another clinic's row.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "412": {
            "description": "If-Match did not match, or the row changed between read and write.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Soft-delete an insurance carrier",
        "description": "Sets `deleted_at`. There is no hard delete in this API: the row stays restorable from Trash in the app.",
        "operationId": "delete_insurance_carriers",
        "tags": [
          "insurance_carriers"
        ],
        "security": [
          {
            "apiKey": [
              "catalog:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "The ETag from a previous GET. The write then applies only if nothing changed in between, otherwise 412. Not supported on resources with no updated_at column.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Soft-deleted. No body."
          },
          "400": {
            "description": "Body is not JSON, or names a field that cannot be patched. See `errors[]`. `appointments.status` and `treatment_plans.status` report `create_only` here.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `catalog:write`, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row in this clinic. Also returned for another clinic's row.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "412": {
            "description": "If-Match did not match, or the row changed between read and write.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/lab_cases": {
      "get": {
        "summary": "List lab cases",
        "operationId": "list_lab_cases",
        "tags": [
          "lab_cases"
        ],
        "security": [
          {
            "apiKey": [
              "lab:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size. Default 50, clamped to 200 rather than rejected.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque keyset cursor from `meta.next_cursor`. Do not construct one by hand. There is no offset parameter: PostgREST caps a range at 1000 rows and truncates silently.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "description": "Comma-separated subset of: id, clinic_id, branch_id, patient_id, treatment_plan_id, appointment_id, laboratory_id, doctor_id, billing_item_id, case_type, status, lab_payment_status, teeth_codes, sent_date, expected_return_date, received_date, fitted_date, lab_cost, transport_cost, other_costs, patient_charge, lab_invoice_ref, tracking_reference, notes, created_at, updated_at.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sortable: sent_date, expected_return_date, created_at, updated_at. Prefix with `-` for descending. Default `-created_at`. An `id` tiebreak is always appended so the order is total.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_total",
            "in": "query",
            "required": false,
            "description": "Run an exact count and return it as `meta.total`. Expensive; counts double against the rate limit.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "include_deleted",
            "in": "query",
            "required": false,
            "description": "Include soft-deleted rows. `deleted_at` itself is never returned.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "description": "Filter on `id`. Also accepts `id[gte]`, `id[lte]`, `id[gt]`, `id[lt]`, `id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "branch_id",
            "in": "query",
            "required": false,
            "description": "Filter on `branch_id`. Also accepts `branch_id[gte]`, `branch_id[lte]`, `branch_id[gt]`, `branch_id[lt]`, `branch_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "patient_id",
            "in": "query",
            "required": false,
            "description": "Filter on `patient_id`. Also accepts `patient_id[gte]`, `patient_id[lte]`, `patient_id[gt]`, `patient_id[lt]`, `patient_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "treatment_plan_id",
            "in": "query",
            "required": false,
            "description": "Filter on `treatment_plan_id`. Also accepts `treatment_plan_id[gte]`, `treatment_plan_id[lte]`, `treatment_plan_id[gt]`, `treatment_plan_id[lt]`, `treatment_plan_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "laboratory_id",
            "in": "query",
            "required": false,
            "description": "Filter on `laboratory_id`. Also accepts `laboratory_id[gte]`, `laboratory_id[lte]`, `laboratory_id[gt]`, `laboratory_id[lt]`, `laboratory_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "doctor_id",
            "in": "query",
            "required": false,
            "description": "Filter on `doctor_id`. Also accepts `doctor_id[gte]`, `doctor_id[lte]`, `doctor_id[gt]`, `doctor_id[lt]`, `doctor_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "case_type",
            "in": "query",
            "required": false,
            "description": "Filter on `case_type`. Also accepts `case_type[gte]`, `case_type[lte]`, `case_type[gt]`, `case_type[lt]`, `case_type[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter on `status`. Also accepts `status[gte]`, `status[lte]`, `status[gt]`, `status[lt]`, `status[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lab_payment_status",
            "in": "query",
            "required": false,
            "description": "Filter on `lab_payment_status`. Also accepts `lab_payment_status[gte]`, `lab_payment_status[lte]`, `lab_payment_status[gt]`, `lab_payment_status[lt]`, `lab_payment_status[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sent_date",
            "in": "query",
            "required": false,
            "description": "Filter on `sent_date`. Also accepts `sent_date[gte]`, `sent_date[lte]`, `sent_date[gt]`, `sent_date[lt]`, `sent_date[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "expected_return_date",
            "in": "query",
            "required": false,
            "description": "Filter on `expected_return_date`. Also accepts `expected_return_date[gte]`, `expected_return_date[lte]`, `expected_return_date[gt]`, `expected_return_date[lt]`, `expected_return_date[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "created_at",
            "in": "query",
            "required": false,
            "description": "Filter on `created_at`. Also accepts `created_at[gte]`, `created_at[lte]`, `created_at[gt]`, `created_at[lt]`, `created_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "updated_at",
            "in": "query",
            "required": false,
            "description": "Filter on `updated_at`. Also accepts `updated_at[gte]`, `updated_at[lte]`, `updated_at[gt]`, `updated_at[lt]`, `updated_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of rows.",
            "headers": {
              "Link": {
                "description": "Contains `rel=\"next\"` when another page exists.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/lab_cases"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Null means this was the last page. A FULL page always carries a cursor even if the next one turns out to be empty; never infer the end from a short page alone."
                        },
                        "total": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "Only with ?include_total=true."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown field in fields/sort/filter, or a malformed cursor.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `lab:read` scope.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/lab_cases/{id}": {
      "get": {
        "summary": "Get a lab case",
        "operationId": "get_lab_cases",
        "tags": [
          "lab_cases"
        ],
        "security": [
          {
            "apiKey": [
              "lab:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The row, under `data`.",
            "headers": {
              "ETag": {
                "description": "Weak validator for If-Match on a future write.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/lab_cases"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `lab:read` scope, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row IN THIS CLINIC. A row belonging to another clinic also returns 404, never 403, so the API never confirms that an id exists elsewhere.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/lab_case_procedures": {
      "get": {
        "summary": "List lab case procedures",
        "operationId": "list_lab_case_procedures",
        "tags": [
          "lab_case_procedures"
        ],
        "security": [
          {
            "apiKey": [
              "lab:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size. Default 50, clamped to 200 rather than rejected.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque keyset cursor from `meta.next_cursor`. Do not construct one by hand. There is no offset parameter: PostgREST caps a range at 1000 rows and truncates silently.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "description": "Comma-separated subset of: id, clinic_id, lab_case_id, catalog_item_id, item_name, unit_price, qty, notes, created_at.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sortable: created_at. Prefix with `-` for descending. Default `-created_at`. An `id` tiebreak is always appended so the order is total.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_total",
            "in": "query",
            "required": false,
            "description": "Run an exact count and return it as `meta.total`. Expensive; counts double against the rate limit.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "description": "Filter on `id`. Also accepts `id[gte]`, `id[lte]`, `id[gt]`, `id[lt]`, `id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "lab_case_id",
            "in": "query",
            "required": false,
            "description": "Filter on `lab_case_id`. Also accepts `lab_case_id[gte]`, `lab_case_id[lte]`, `lab_case_id[gt]`, `lab_case_id[lt]`, `lab_case_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "catalog_item_id",
            "in": "query",
            "required": false,
            "description": "Filter on `catalog_item_id`. Also accepts `catalog_item_id[gte]`, `catalog_item_id[lte]`, `catalog_item_id[gt]`, `catalog_item_id[lt]`, `catalog_item_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "created_at",
            "in": "query",
            "required": false,
            "description": "Filter on `created_at`. Also accepts `created_at[gte]`, `created_at[lte]`, `created_at[gt]`, `created_at[lt]`, `created_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of rows.",
            "headers": {
              "Link": {
                "description": "Contains `rel=\"next\"` when another page exists.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/lab_case_procedures"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Null means this was the last page. A FULL page always carries a cursor even if the next one turns out to be empty; never infer the end from a short page alone."
                        },
                        "total": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "Only with ?include_total=true."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown field in fields/sort/filter, or a malformed cursor.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `lab:read` scope.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/lab_case_procedures/{id}": {
      "get": {
        "summary": "Get a lab case procedure",
        "operationId": "get_lab_case_procedures",
        "tags": [
          "lab_case_procedures"
        ],
        "security": [
          {
            "apiKey": [
              "lab:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The row, under `data`.",
            "headers": {
              "ETag": {
                "description": "Weak validator for If-Match on a future write.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/lab_case_procedures"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `lab:read` scope, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row IN THIS CLINIC. A row belonging to another clinic also returns 404, never 403, so the API never confirms that an id exists elsewhere.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/laboratories": {
      "get": {
        "summary": "List laboratories",
        "operationId": "list_laboratories",
        "tags": [
          "laboratories"
        ],
        "security": [
          {
            "apiKey": [
              "lab:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size. Default 50, clamped to 200 rather than rejected.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque keyset cursor from `meta.next_cursor`. Do not construct one by hand. There is no offset parameter: PostgREST caps a range at 1000 rows and truncates silently.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "description": "Comma-separated subset of: id, clinic_id, name, phone, email, address, status, notes, created_at, updated_at.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sortable: created_at, updated_at, name. Prefix with `-` for descending. Default `-created_at`. An `id` tiebreak is always appended so the order is total.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_total",
            "in": "query",
            "required": false,
            "description": "Run an exact count and return it as `meta.total`. Expensive; counts double against the rate limit.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "include_deleted",
            "in": "query",
            "required": false,
            "description": "Include soft-deleted rows. `deleted_at` itself is never returned.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "description": "Filter on `id`. Also accepts `id[gte]`, `id[lte]`, `id[gt]`, `id[lt]`, `id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "description": "Filter on `name`. Also accepts `name[gte]`, `name[lte]`, `name[gt]`, `name[lt]`, `name[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter on `status`. Also accepts `status[gte]`, `status[lte]`, `status[gt]`, `status[lt]`, `status[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "created_at",
            "in": "query",
            "required": false,
            "description": "Filter on `created_at`. Also accepts `created_at[gte]`, `created_at[lte]`, `created_at[gt]`, `created_at[lt]`, `created_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "updated_at",
            "in": "query",
            "required": false,
            "description": "Filter on `updated_at`. Also accepts `updated_at[gte]`, `updated_at[lte]`, `updated_at[gt]`, `updated_at[lt]`, `updated_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of rows.",
            "headers": {
              "Link": {
                "description": "Contains `rel=\"next\"` when another page exists.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/laboratories"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Null means this was the last page. A FULL page always carries a cursor even if the next one turns out to be empty; never infer the end from a short page alone."
                        },
                        "total": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "Only with ?include_total=true."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown field in fields/sort/filter, or a malformed cursor.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `lab:read` scope.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a laboratory",
        "operationId": "create_laboratories",
        "tags": [
          "laboratories"
        ],
        "security": [
          {
            "apiKey": [
              "lab:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/laboratories_create"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created. The new row, under `data`.",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              },
              "ETag": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/laboratories"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Body is not JSON, or names a field that cannot be written. See `errors[]`; values are never echoed back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `lab:write`, the bound role may not write this, the branch is not allowed, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "An identical Idempotency-Key is still in flight.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "A required field is missing. See `errors[]`. Note that a field which simply cannot be written is a 400 `unknown_field`, not a 422.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/laboratories/{id}": {
      "get": {
        "summary": "Get a laboratory",
        "operationId": "get_laboratories",
        "tags": [
          "laboratories"
        ],
        "security": [
          {
            "apiKey": [
              "lab:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The row, under `data`.",
            "headers": {
              "ETag": {
                "description": "Weak validator for If-Match on a future write.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/laboratories"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `lab:read` scope, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row IN THIS CLINIC. A row belonging to another clinic also returns 404, never 403, so the API never confirms that an id exists elsewhere.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update a laboratory",
        "description": "Only the fields you send are changed.",
        "operationId": "update_laboratories",
        "tags": [
          "laboratories"
        ],
        "security": [
          {
            "apiKey": [
              "lab:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "The ETag from a previous GET. The write then applies only if nothing changed in between, otherwise 412. Not supported on resources with no updated_at column.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/laboratories_update"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated row, under `data`.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/laboratories"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Body is not JSON, or names a field that cannot be patched. See `errors[]`. `appointments.status` and `treatment_plans.status` report `create_only` here.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `lab:write`, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row in this clinic. Also returned for another clinic's row.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "412": {
            "description": "If-Match did not match, or the row changed between read and write.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Soft-delete a laboratory",
        "description": "Sets `deleted_at`. There is no hard delete in this API: the row stays restorable from Trash in the app.",
        "operationId": "delete_laboratories",
        "tags": [
          "laboratories"
        ],
        "security": [
          {
            "apiKey": [
              "lab:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "The ETag from a previous GET. The write then applies only if nothing changed in between, otherwise 412. Not supported on resources with no updated_at column.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Soft-deleted. No body."
          },
          "400": {
            "description": "Body is not JSON, or names a field that cannot be patched. See `errors[]`. `appointments.status` and `treatment_plans.status` report `create_only` here.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `lab:write`, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row in this clinic. Also returned for another clinic's row.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "412": {
            "description": "If-Match did not match, or the row changed between read and write.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/inventory_items": {
      "get": {
        "summary": "List inventory items",
        "operationId": "list_inventory_items",
        "tags": [
          "inventory_items"
        ],
        "security": [
          {
            "apiKey": [
              "inventory:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size. Default 50, clamped to 200 rather than rejected.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque keyset cursor from `meta.next_cursor`. Do not construct one by hand. There is no offset parameter: PostgREST caps a range at 1000 rows and truncates silently.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "description": "Comma-separated subset of: id, clinic_id, branch_id, name, category, sku, reorder_level, created_at, updated_at.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sortable: created_at, updated_at, name. Prefix with `-` for descending. Default `-created_at`. An `id` tiebreak is always appended so the order is total.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_total",
            "in": "query",
            "required": false,
            "description": "Run an exact count and return it as `meta.total`. Expensive; counts double against the rate limit.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "include_deleted",
            "in": "query",
            "required": false,
            "description": "Include soft-deleted rows. `deleted_at` itself is never returned.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "description": "Filter on `id`. Also accepts `id[gte]`, `id[lte]`, `id[gt]`, `id[lt]`, `id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "branch_id",
            "in": "query",
            "required": false,
            "description": "Filter on `branch_id`. Also accepts `branch_id[gte]`, `branch_id[lte]`, `branch_id[gt]`, `branch_id[lt]`, `branch_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "description": "Filter on `name`. Also accepts `name[gte]`, `name[lte]`, `name[gt]`, `name[lt]`, `name[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Filter on `category`. Also accepts `category[gte]`, `category[lte]`, `category[gt]`, `category[lt]`, `category[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sku",
            "in": "query",
            "required": false,
            "description": "Filter on `sku`. Also accepts `sku[gte]`, `sku[lte]`, `sku[gt]`, `sku[lt]`, `sku[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "created_at",
            "in": "query",
            "required": false,
            "description": "Filter on `created_at`. Also accepts `created_at[gte]`, `created_at[lte]`, `created_at[gt]`, `created_at[lt]`, `created_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "updated_at",
            "in": "query",
            "required": false,
            "description": "Filter on `updated_at`. Also accepts `updated_at[gte]`, `updated_at[lte]`, `updated_at[gt]`, `updated_at[lt]`, `updated_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of rows.",
            "headers": {
              "Link": {
                "description": "Contains `rel=\"next\"` when another page exists.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/inventory_items"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Null means this was the last page. A FULL page always carries a cursor even if the next one turns out to be empty; never infer the end from a short page alone."
                        },
                        "total": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "Only with ?include_total=true."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown field in fields/sort/filter, or a malformed cursor.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `inventory:read` scope.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create an inventory item",
        "operationId": "create_inventory_items",
        "tags": [
          "inventory_items"
        ],
        "security": [
          {
            "apiKey": [
              "inventory:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inventory_items_create"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created. The new row, under `data`.",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              },
              "ETag": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/inventory_items"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Body is not JSON, or names a field that cannot be written. See `errors[]`; values are never echoed back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `inventory:write`, the bound role may not write this, the branch is not allowed, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "An identical Idempotency-Key is still in flight.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "A required field is missing. See `errors[]`. Note that a field which simply cannot be written is a 400 `unknown_field`, not a 422.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/inventory_items/{id}": {
      "get": {
        "summary": "Get an inventory item",
        "operationId": "get_inventory_items",
        "tags": [
          "inventory_items"
        ],
        "security": [
          {
            "apiKey": [
              "inventory:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The row, under `data`.",
            "headers": {
              "ETag": {
                "description": "Weak validator for If-Match on a future write.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/inventory_items"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `inventory:read` scope, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row IN THIS CLINIC. A row belonging to another clinic also returns 404, never 403, so the API never confirms that an id exists elsewhere.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update an inventory item",
        "description": "Only the fields you send are changed.",
        "operationId": "update_inventory_items",
        "tags": [
          "inventory_items"
        ],
        "security": [
          {
            "apiKey": [
              "inventory:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "The ETag from a previous GET. The write then applies only if nothing changed in between, otherwise 412. Not supported on resources with no updated_at column.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inventory_items_update"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated row, under `data`.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/inventory_items"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Body is not JSON, or names a field that cannot be patched. See `errors[]`. `appointments.status` and `treatment_plans.status` report `create_only` here.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `inventory:write`, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row in this clinic. Also returned for another clinic's row.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "412": {
            "description": "If-Match did not match, or the row changed between read and write.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Soft-delete an inventory item",
        "description": "Sets `deleted_at`. There is no hard delete in this API: the row stays restorable from Trash in the app.",
        "operationId": "delete_inventory_items",
        "tags": [
          "inventory_items"
        ],
        "security": [
          {
            "apiKey": [
              "inventory:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "The ETag from a previous GET. The write then applies only if nothing changed in between, otherwise 412. Not supported on resources with no updated_at column.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Soft-deleted. No body."
          },
          "400": {
            "description": "Body is not JSON, or names a field that cannot be patched. See `errors[]`. `appointments.status` and `treatment_plans.status` report `create_only` here.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `inventory:write`, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row in this clinic. Also returned for another clinic's row.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "412": {
            "description": "If-Match did not match, or the row changed between read and write.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/inventory_batches": {
      "get": {
        "summary": "List inventory batches",
        "operationId": "list_inventory_batches",
        "tags": [
          "inventory_batches"
        ],
        "security": [
          {
            "apiKey": [
              "inventory:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size. Default 50, clamped to 200 rather than rejected.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque keyset cursor from `meta.next_cursor`. Do not construct one by hand. There is no offset parameter: PostgREST caps a range at 1000 rows and truncates silently.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "description": "Comma-separated subset of: id, clinic_id, branch_id, inventory_item_id, batch_number, supplier_name, expiry_date, quantity_received, quantity_remaining, cost_per_unit, received_at, write_off_quantity, write_off_reason, written_off_at, written_off_by, notes, created_at, updated_at.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sortable: expiry_date, received_at, created_at, updated_at. Prefix with `-` for descending. Default `expiry_date`. An `id` tiebreak is always appended so the order is total.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_total",
            "in": "query",
            "required": false,
            "description": "Run an exact count and return it as `meta.total`. Expensive; counts double against the rate limit.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "include_deleted",
            "in": "query",
            "required": false,
            "description": "Include soft-deleted rows. `deleted_at` itself is never returned.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "description": "Filter on `id`. Also accepts `id[gte]`, `id[lte]`, `id[gt]`, `id[lt]`, `id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "branch_id",
            "in": "query",
            "required": false,
            "description": "Filter on `branch_id`. Also accepts `branch_id[gte]`, `branch_id[lte]`, `branch_id[gt]`, `branch_id[lt]`, `branch_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "inventory_item_id",
            "in": "query",
            "required": false,
            "description": "Filter on `inventory_item_id`. Also accepts `inventory_item_id[gte]`, `inventory_item_id[lte]`, `inventory_item_id[gt]`, `inventory_item_id[lt]`, `inventory_item_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "batch_number",
            "in": "query",
            "required": false,
            "description": "Filter on `batch_number`. Also accepts `batch_number[gte]`, `batch_number[lte]`, `batch_number[gt]`, `batch_number[lt]`, `batch_number[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "expiry_date",
            "in": "query",
            "required": false,
            "description": "Filter on `expiry_date`. Also accepts `expiry_date[gte]`, `expiry_date[lte]`, `expiry_date[gt]`, `expiry_date[lt]`, `expiry_date[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "received_at",
            "in": "query",
            "required": false,
            "description": "Filter on `received_at`. Also accepts `received_at[gte]`, `received_at[lte]`, `received_at[gt]`, `received_at[lt]`, `received_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "created_at",
            "in": "query",
            "required": false,
            "description": "Filter on `created_at`. Also accepts `created_at[gte]`, `created_at[lte]`, `created_at[gt]`, `created_at[lt]`, `created_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "updated_at",
            "in": "query",
            "required": false,
            "description": "Filter on `updated_at`. Also accepts `updated_at[gte]`, `updated_at[lte]`, `updated_at[gt]`, `updated_at[lt]`, `updated_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of rows.",
            "headers": {
              "Link": {
                "description": "Contains `rel=\"next\"` when another page exists.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/inventory_batches"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Null means this was the last page. A FULL page always carries a cursor even if the next one turns out to be empty; never infer the end from a short page alone."
                        },
                        "total": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "Only with ?include_total=true."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown field in fields/sort/filter, or a malformed cursor.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `inventory:read` scope.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/inventory_batches/{id}": {
      "get": {
        "summary": "Get an inventory batch",
        "operationId": "get_inventory_batches",
        "tags": [
          "inventory_batches"
        ],
        "security": [
          {
            "apiKey": [
              "inventory:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The row, under `data`.",
            "headers": {
              "ETag": {
                "description": "Weak validator for If-Match on a future write.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/inventory_batches"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `inventory:read` scope, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row IN THIS CLINIC. A row belonging to another clinic also returns 404, never 403, so the API never confirms that an id exists elsewhere.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/inventory_transactions": {
      "get": {
        "summary": "List inventory transactions",
        "operationId": "list_inventory_transactions",
        "tags": [
          "inventory_transactions"
        ],
        "security": [
          {
            "apiKey": [
              "inventory:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size. Default 50, clamped to 200 rather than rejected.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque keyset cursor from `meta.next_cursor`. Do not construct one by hand. There is no offset parameter: PostgREST caps a range at 1000 rows and truncates silently.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "description": "Comma-separated subset of: id, clinic_id, inventory_item_id, type, quantity, notes, created_at, updated_at.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sortable: created_at, updated_at. Prefix with `-` for descending. Default `-created_at`. An `id` tiebreak is always appended so the order is total.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_total",
            "in": "query",
            "required": false,
            "description": "Run an exact count and return it as `meta.total`. Expensive; counts double against the rate limit.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "include_deleted",
            "in": "query",
            "required": false,
            "description": "Include soft-deleted rows. `deleted_at` itself is never returned.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "description": "Filter on `id`. Also accepts `id[gte]`, `id[lte]`, `id[gt]`, `id[lt]`, `id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "inventory_item_id",
            "in": "query",
            "required": false,
            "description": "Filter on `inventory_item_id`. Also accepts `inventory_item_id[gte]`, `inventory_item_id[lte]`, `inventory_item_id[gt]`, `inventory_item_id[lt]`, `inventory_item_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Filter on `type`. Also accepts `type[gte]`, `type[lte]`, `type[gt]`, `type[lt]`, `type[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "created_at",
            "in": "query",
            "required": false,
            "description": "Filter on `created_at`. Also accepts `created_at[gte]`, `created_at[lte]`, `created_at[gt]`, `created_at[lt]`, `created_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "updated_at",
            "in": "query",
            "required": false,
            "description": "Filter on `updated_at`. Also accepts `updated_at[gte]`, `updated_at[lte]`, `updated_at[gt]`, `updated_at[lt]`, `updated_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of rows.",
            "headers": {
              "Link": {
                "description": "Contains `rel=\"next\"` when another page exists.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/inventory_transactions"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Null means this was the last page. A FULL page always carries a cursor even if the next one turns out to be empty; never infer the end from a short page alone."
                        },
                        "total": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "Only with ?include_total=true."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown field in fields/sort/filter, or a malformed cursor.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `inventory:read` scope.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/inventory_transactions/{id}": {
      "get": {
        "summary": "Get an inventory transaction",
        "operationId": "get_inventory_transactions",
        "tags": [
          "inventory_transactions"
        ],
        "security": [
          {
            "apiKey": [
              "inventory:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The row, under `data`.",
            "headers": {
              "ETag": {
                "description": "Weak validator for If-Match on a future write.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/inventory_transactions"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `inventory:read` scope, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row IN THIS CLINIC. A row belonging to another clinic also returns 404, never 403, so the API never confirms that an id exists elsewhere.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/catalog_items": {
      "get": {
        "summary": "List catalog items",
        "operationId": "list_catalog_items",
        "tags": [
          "catalog_items"
        ],
        "security": [
          {
            "apiKey": [
              "catalog:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size. Default 50, clamped to 200 rather than rejected.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque keyset cursor from `meta.next_cursor`. Do not construct one by hand. There is no offset parameter: PostgREST caps a range at 1000 rows and truncates silently.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "description": "Comma-separated subset of: id, clinic_id, name, type, unit_price, linked_inventory_item_id, linked_inventory_qty, import_report_id, created_at, updated_at.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sortable: created_at, updated_at, name. Prefix with `-` for descending. Default `name`. An `id` tiebreak is always appended so the order is total.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_total",
            "in": "query",
            "required": false,
            "description": "Run an exact count and return it as `meta.total`. Expensive; counts double against the rate limit.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "include_deleted",
            "in": "query",
            "required": false,
            "description": "Include soft-deleted rows. `deleted_at` itself is never returned.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "exclude_migrated",
            "in": "query",
            "required": false,
            "description": "Exclude rows created by a bulk import (`import_report_id is null`).",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "description": "Filter on `id`. Also accepts `id[gte]`, `id[lte]`, `id[gt]`, `id[lt]`, `id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "description": "Filter on `name`. Also accepts `name[gte]`, `name[lte]`, `name[gt]`, `name[lt]`, `name[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Filter on `type`. Also accepts `type[gte]`, `type[lte]`, `type[gt]`, `type[lt]`, `type[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "linked_inventory_item_id",
            "in": "query",
            "required": false,
            "description": "Filter on `linked_inventory_item_id`. Also accepts `linked_inventory_item_id[gte]`, `linked_inventory_item_id[lte]`, `linked_inventory_item_id[gt]`, `linked_inventory_item_id[lt]`, `linked_inventory_item_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "created_at",
            "in": "query",
            "required": false,
            "description": "Filter on `created_at`. Also accepts `created_at[gte]`, `created_at[lte]`, `created_at[gt]`, `created_at[lt]`, `created_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "updated_at",
            "in": "query",
            "required": false,
            "description": "Filter on `updated_at`. Also accepts `updated_at[gte]`, `updated_at[lte]`, `updated_at[gt]`, `updated_at[lt]`, `updated_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of rows.",
            "headers": {
              "Link": {
                "description": "Contains `rel=\"next\"` when another page exists.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/catalog_items"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Null means this was the last page. A FULL page always carries a cursor even if the next one turns out to be empty; never infer the end from a short page alone."
                        },
                        "total": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "Only with ?include_total=true."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown field in fields/sort/filter, or a malformed cursor.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `catalog:read` scope.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a catalog item",
        "operationId": "create_catalog_items",
        "tags": [
          "catalog_items"
        ],
        "security": [
          {
            "apiKey": [
              "catalog:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/catalog_items_create"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created. The new row, under `data`.",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              },
              "ETag": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/catalog_items"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Body is not JSON, or names a field that cannot be written. See `errors[]`; values are never echoed back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `catalog:write`, the bound role may not write this, the branch is not allowed, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "An identical Idempotency-Key is still in flight.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "A required field is missing. See `errors[]`. Note that a field which simply cannot be written is a 400 `unknown_field`, not a 422.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/catalog_items/{id}": {
      "get": {
        "summary": "Get a catalog item",
        "operationId": "get_catalog_items",
        "tags": [
          "catalog_items"
        ],
        "security": [
          {
            "apiKey": [
              "catalog:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The row, under `data`.",
            "headers": {
              "ETag": {
                "description": "Weak validator for If-Match on a future write.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/catalog_items"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `catalog:read` scope, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row IN THIS CLINIC. A row belonging to another clinic also returns 404, never 403, so the API never confirms that an id exists elsewhere.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update a catalog item",
        "description": "Only the fields you send are changed.",
        "operationId": "update_catalog_items",
        "tags": [
          "catalog_items"
        ],
        "security": [
          {
            "apiKey": [
              "catalog:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "The ETag from a previous GET. The write then applies only if nothing changed in between, otherwise 412. Not supported on resources with no updated_at column.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/catalog_items_update"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated row, under `data`.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/catalog_items"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Body is not JSON, or names a field that cannot be patched. See `errors[]`. `appointments.status` and `treatment_plans.status` report `create_only` here.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `catalog:write`, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row in this clinic. Also returned for another clinic's row.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "412": {
            "description": "If-Match did not match, or the row changed between read and write.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Soft-delete a catalog item",
        "description": "Sets `deleted_at`. There is no hard delete in this API: the row stays restorable from Trash in the app.",
        "operationId": "delete_catalog_items",
        "tags": [
          "catalog_items"
        ],
        "security": [
          {
            "apiKey": [
              "catalog:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "The ETag from a previous GET. The write then applies only if nothing changed in between, otherwise 412. Not supported on resources with no updated_at column.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Soft-deleted. No body."
          },
          "400": {
            "description": "Body is not JSON, or names a field that cannot be patched. See `errors[]`. `appointments.status` and `treatment_plans.status` report `create_only` here.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `catalog:write`, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row in this clinic. Also returned for another clinic's row.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "412": {
            "description": "If-Match did not match, or the row changed between read and write.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/branches": {
      "get": {
        "summary": "List branches",
        "operationId": "list_branches",
        "tags": [
          "branches"
        ],
        "security": [
          {
            "apiKey": [
              "org:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size. Default 50, clamped to 200 rather than rejected.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque keyset cursor from `meta.next_cursor`. Do not construct one by hand. There is no offset parameter: PostgREST caps a range at 1000 rows and truncates silently.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "description": "Comma-separated subset of: id, clinic_id, name, address, phone, is_main_branch, import_report_id, created_at, updated_at.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sortable: created_at, updated_at, name. Prefix with `-` for descending. Default `name`. An `id` tiebreak is always appended so the order is total.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_total",
            "in": "query",
            "required": false,
            "description": "Run an exact count and return it as `meta.total`. Expensive; counts double against the rate limit.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "include_deleted",
            "in": "query",
            "required": false,
            "description": "Include soft-deleted rows. `deleted_at` itself is never returned.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "exclude_migrated",
            "in": "query",
            "required": false,
            "description": "Exclude rows created by a bulk import (`import_report_id is null`).",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "description": "Filter on `id`. Also accepts `id[gte]`, `id[lte]`, `id[gt]`, `id[lt]`, `id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "description": "Filter on `name`. Also accepts `name[gte]`, `name[lte]`, `name[gt]`, `name[lt]`, `name[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "is_main_branch",
            "in": "query",
            "required": false,
            "description": "Filter on `is_main_branch`. Also accepts `is_main_branch[gte]`, `is_main_branch[lte]`, `is_main_branch[gt]`, `is_main_branch[lt]`, `is_main_branch[in]` (comma-separated).",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "created_at",
            "in": "query",
            "required": false,
            "description": "Filter on `created_at`. Also accepts `created_at[gte]`, `created_at[lte]`, `created_at[gt]`, `created_at[lt]`, `created_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "updated_at",
            "in": "query",
            "required": false,
            "description": "Filter on `updated_at`. Also accepts `updated_at[gte]`, `updated_at[lte]`, `updated_at[gt]`, `updated_at[lt]`, `updated_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of rows.",
            "headers": {
              "Link": {
                "description": "Contains `rel=\"next\"` when another page exists.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/branches"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Null means this was the last page. A FULL page always carries a cursor even if the next one turns out to be empty; never infer the end from a short page alone."
                        },
                        "total": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "Only with ?include_total=true."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown field in fields/sort/filter, or a malformed cursor.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `org:read` scope.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/branches/{id}": {
      "get": {
        "summary": "Get a branch",
        "operationId": "get_branches",
        "tags": [
          "branches"
        ],
        "security": [
          {
            "apiKey": [
              "org:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The row, under `data`.",
            "headers": {
              "ETag": {
                "description": "Weak validator for If-Match on a future write.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/branches"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `org:read` scope, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row IN THIS CLINIC. A row belonging to another clinic also returns 404, never 403, so the API never confirms that an id exists elsewhere.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/dental_chairs": {
      "get": {
        "summary": "List dental chairs",
        "operationId": "list_dental_chairs",
        "tags": [
          "dental_chairs"
        ],
        "security": [
          {
            "apiKey": [
              "org:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size. Default 50, clamped to 200 rather than rejected.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque keyset cursor from `meta.next_cursor`. Do not construct one by hand. There is no offset parameter: PostgREST caps a range at 1000 rows and truncates silently.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "description": "Comma-separated subset of: id, clinic_id, branch_id, name, room_number, is_occupied, is_active, import_report_id, created_at, updated_at.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sortable: created_at, updated_at, name. Prefix with `-` for descending. Default `name`. An `id` tiebreak is always appended so the order is total.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_total",
            "in": "query",
            "required": false,
            "description": "Run an exact count and return it as `meta.total`. Expensive; counts double against the rate limit.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "include_deleted",
            "in": "query",
            "required": false,
            "description": "Include soft-deleted rows. `deleted_at` itself is never returned.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "exclude_migrated",
            "in": "query",
            "required": false,
            "description": "Exclude rows created by a bulk import (`import_report_id is null`).",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "description": "Filter on `id`. Also accepts `id[gte]`, `id[lte]`, `id[gt]`, `id[lt]`, `id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "branch_id",
            "in": "query",
            "required": false,
            "description": "Filter on `branch_id`. Also accepts `branch_id[gte]`, `branch_id[lte]`, `branch_id[gt]`, `branch_id[lt]`, `branch_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "description": "Filter on `name`. Also accepts `name[gte]`, `name[lte]`, `name[gt]`, `name[lt]`, `name[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "is_active",
            "in": "query",
            "required": false,
            "description": "Filter on `is_active`. Also accepts `is_active[gte]`, `is_active[lte]`, `is_active[gt]`, `is_active[lt]`, `is_active[in]` (comma-separated).",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "is_occupied",
            "in": "query",
            "required": false,
            "description": "Filter on `is_occupied`. Also accepts `is_occupied[gte]`, `is_occupied[lte]`, `is_occupied[gt]`, `is_occupied[lt]`, `is_occupied[in]` (comma-separated).",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "created_at",
            "in": "query",
            "required": false,
            "description": "Filter on `created_at`. Also accepts `created_at[gte]`, `created_at[lte]`, `created_at[gt]`, `created_at[lt]`, `created_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "updated_at",
            "in": "query",
            "required": false,
            "description": "Filter on `updated_at`. Also accepts `updated_at[gte]`, `updated_at[lte]`, `updated_at[gt]`, `updated_at[lt]`, `updated_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of rows.",
            "headers": {
              "Link": {
                "description": "Contains `rel=\"next\"` when another page exists.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/dental_chairs"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Null means this was the last page. A FULL page always carries a cursor even if the next one turns out to be empty; never infer the end from a short page alone."
                        },
                        "total": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "Only with ?include_total=true."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown field in fields/sort/filter, or a malformed cursor.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `org:read` scope.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/dental_chairs/{id}": {
      "get": {
        "summary": "Get a dental chair",
        "operationId": "get_dental_chairs",
        "tags": [
          "dental_chairs"
        ],
        "security": [
          {
            "apiKey": [
              "org:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The row, under `data`.",
            "headers": {
              "ETag": {
                "description": "Weak validator for If-Match on a future write.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/dental_chairs"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `org:read` scope, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row IN THIS CLINIC. A row belonging to another clinic also returns 404, never 403, so the API never confirms that an id exists elsewhere.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/staff": {
      "get": {
        "summary": "List staff",
        "operationId": "list_staff",
        "tags": [
          "staff"
        ],
        "security": [
          {
            "apiKey": [
              "org:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size. Default 50, clamped to 200 rather than rejected.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque keyset cursor from `meta.next_cursor`. Do not construct one by hand. There is no offset parameter: PostgREST caps a range at 1000 rows and truncates silently.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "description": "Comma-separated subset of: id, clinic_id, branch_id, working_branch_id, staff_code, salutation, first_name, last_name, title, role, job_roles, work_email, work_phone, is_active, hire_date, import_report_id, created_at, updated_at.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sortable: created_at, updated_at, last_name, first_name. Prefix with `-` for descending. Default `last_name`. An `id` tiebreak is always appended so the order is total.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_total",
            "in": "query",
            "required": false,
            "description": "Run an exact count and return it as `meta.total`. Expensive; counts double against the rate limit.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "include_deleted",
            "in": "query",
            "required": false,
            "description": "Include soft-deleted rows. `deleted_at` itself is never returned.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "exclude_migrated",
            "in": "query",
            "required": false,
            "description": "Exclude rows created by a bulk import (`import_report_id is null`).",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "description": "Filter on `id`. Also accepts `id[gte]`, `id[lte]`, `id[gt]`, `id[lt]`, `id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "branch_id",
            "in": "query",
            "required": false,
            "description": "Filter on `branch_id`. Also accepts `branch_id[gte]`, `branch_id[lte]`, `branch_id[gt]`, `branch_id[lt]`, `branch_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "working_branch_id",
            "in": "query",
            "required": false,
            "description": "Filter on `working_branch_id`. Also accepts `working_branch_id[gte]`, `working_branch_id[lte]`, `working_branch_id[gt]`, `working_branch_id[lt]`, `working_branch_id[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "role",
            "in": "query",
            "required": false,
            "description": "Filter on `role`. Also accepts `role[gte]`, `role[lte]`, `role[gt]`, `role[lt]`, `role[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "is_active",
            "in": "query",
            "required": false,
            "description": "Filter on `is_active`. Also accepts `is_active[gte]`, `is_active[lte]`, `is_active[gt]`, `is_active[lt]`, `is_active[in]` (comma-separated).",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "staff_code",
            "in": "query",
            "required": false,
            "description": "Filter on `staff_code`. Also accepts `staff_code[gte]`, `staff_code[lte]`, `staff_code[gt]`, `staff_code[lt]`, `staff_code[in]` (comma-separated).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "created_at",
            "in": "query",
            "required": false,
            "description": "Filter on `created_at`. Also accepts `created_at[gte]`, `created_at[lte]`, `created_at[gt]`, `created_at[lt]`, `created_at[in]` (comma-separated).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of rows.",
            "headers": {
              "Link": {
                "description": "Contains `rel=\"next\"` when another page exists.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/staff"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Null means this was the last page. A FULL page always carries a cursor even if the next one turns out to be empty; never infer the end from a short page alone."
                        },
                        "total": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "Only with ?include_total=true."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown field in fields/sort/filter, or a malformed cursor.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `org:read` scope.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/staff/{id}": {
      "get": {
        "summary": "Get a staff member",
        "operationId": "get_staff",
        "tags": [
          "staff"
        ],
        "security": [
          {
            "apiKey": [
              "org:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The row, under `data`.",
            "headers": {
              "ETag": {
                "description": "Weak validator for If-Match on a future write.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/staff"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks the `org:read` scope, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such row IN THIS CLINIC. A row belonging to another clinic also returns 404, never 403, so the API never confirms that an id exists elsewhere.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. See Retry-After.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/imports": {
      "post": {
        "summary": "Start a bulk import",
        "operationId": "create_import",
        "tags": [
          "imports"
        ],
        "description": "Creates a report that every subsequent batch is stamped against, and that rollback acts on. Refused with 409 if this clinic started another import in the last 6 hours, so two concurrent migrations cannot make per-row failures unattributable or rollback ambiguous.",
        "security": [
          {
            "apiKey": [
              "imports:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "entity"
                ],
                "properties": {
                  "entity": {
                    "type": "string",
                    "enum": [
                      "patients",
                      "appointments",
                      "families",
                      "catalog_items"
                    ],
                    "description": "Only entities that are both writable AND rollback-supported."
                  },
                  "source_label": {
                    "type": "string",
                    "maxLength": 200,
                    "description": "Free text shown in the app's Import Reports tab."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Import created. `data` carries its id.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "entity": {
                          "type": "string"
                        },
                        "title": {
                          "type": "string"
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `imports:write`, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Another import was started for this clinic within the last 6 hours.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Unsupported entity.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/imports/{id}/batches": {
      "post": {
        "summary": "Push a batch of rows",
        "operationId": "push_import_batch",
        "tags": [
          "imports"
        ],
        "description": "Up to 500 rows and 4 MiB per call, synchronous. Returns a PER-ROW result with a 200, not a 207. A chunk that fails is retried row by row, so one bad row fails only itself; the worst case is one round trip per row. `Idempotency-Key` is REQUIRED here: a retried batch without one would insert the same rows twice.",
        "security": [
          {
            "apiKey": [
              "imports:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The import report id returned by POST /v1/imports.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "rows"
                ],
                "properties": {
                  "rows": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 500,
                    "items": {
                      "type": "object"
                    }
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Per-row results under `data`, totals under `meta`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "index": {
                            "type": "integer"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "inserted",
                              "failed"
                            ]
                          },
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "error": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "inserted": {
                          "type": "integer"
                        },
                        "failed": {
                          "type": "integer"
                        },
                        "batch_size": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Body is not JSON, too large, or Idempotency-Key is missing.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `imports:write`, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such import report in this clinic.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "An identical Idempotency-Key is still in flight.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "rows is not an array, is empty, is over 500, or would exceed the 500,000-row ceiling.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/imports/{id}": {
      "get": {
        "summary": "Inspect an import",
        "operationId": "get_import",
        "tags": [
          "imports"
        ],
        "security": [
          {
            "apiKey": [
              "imports:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The import report id returned by POST /v1/imports.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Under `data`: the report, how many of its rows are still present and whether the 7-day rollback window is still open.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "title": {
                          "type": "string"
                        },
                        "entity": {
                          "type": "string"
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "summary": {
                          "type": "object"
                        },
                        "anomalies": {
                          "type": [
                            "object",
                            "array",
                            "null"
                          ]
                        },
                        "rows_present": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "rollback_available": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `imports:write`, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such import report in this clinic.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/imports/{id}/rollback": {
      "post": {
        "summary": "Roll back an import",
        "operationId": "rollback_import",
        "tags": [
          "imports"
        ],
        "description": "Deletes rows this import created, within 7 days. Rows that anything now references, or that have been edited since, are SKIPPED rather than deleted, and counted in `skipped`. Requires a key bound to an Administrator.",
        "security": [
          {
            "apiKey": [
              "imports:rollback"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The import report id returned by POST /v1/imports.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replay protection. Resending the SAME key with the SAME body returns the first response instead of acting twice; the same key with a DIFFERENT body is rejected with 422. The window is 24 hours.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Counts of what was deleted and what was skipped, under `data`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "deleted": {
                          "type": "integer"
                        },
                        "skipped": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Key lacks `imports:rollback`, or the clinic is read-only.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such import report in this clinic.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "The 7-day rollback window has passed.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/meta/whoami": {
      "get": {
        "summary": "Describe the calling key",
        "operationId": "meta_whoami",
        "tags": [
          "meta"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "The key, its bound role, scopes and branch restriction, under `data`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "clinic_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "key_name": {
                          "type": "string"
                        },
                        "key_prefix": {
                          "type": "string"
                        },
                        "role": {
                          "type": "string"
                        },
                        "scopes": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "branch_ids": {
                          "type": [
                            "array",
                            "null"
                          ],
                          "items": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "description": "Null means every branch."
                        },
                        "clinic_timezone": {
                          "type": "string",
                          "description": "IANA name. Every date-only parameter is in this zone."
                        },
                        "writable": {
                          "type": "boolean",
                          "description": "False when the subscription is read-only; writes then 403."
                        },
                        "rate_limit": {
                          "type": "object",
                          "properties": {
                            "per_minute": {
                              "type": "integer"
                            },
                            "per_day": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired key.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    }
  }
}
