AlayaCare Medication Administration API

openapi: 3.2.0
info:
  version: 1.0.4
  title: External Clinical Medication Administration API
  description: "External Clinical API\n\n**Internal IDs**\nThe following terms are used to reference IDs that identify resources in AlayaCare:\n- id\n- created_by\n- client_id\n- risk_id\n- medication_id\n- admin_id\n- vital_id\n\n**External IDs**\nThe following terms are used to reference IDs that identify resources systems external to AlayaCare:\n- external_id\n- external_client_id\n\nExternal IDs are required to be unique.\nNo other assumptions are made regarding their format they are treated as strings.\n\n**Remarks**\n- All dates must be in ISO 8601 format.\n- Required fields marked with `*` cannot be null.\n\n**Progress Notes**\n  API for creating and viewing client progress notes.\n\n**Risks**\nAPI for creating, viewing, updating, and removing client risks.\n\n**Medication**\n  API for creating, editing, and viewing medications and medication administrations.\n\n**Vitals**\n  API for creating, editing and viewing vitals.\n\nEach individual vital type is identified by a `name`. Dependent vitals are given the same `group`. Currently this is only used to link names `pressure_min` and `pressure_max` with the group `blood_pressure`, as these values should be recorded together.\n\nThe metadata of the vitals includes the configuration and thresholds, the default and available units, and any other required options for each vital type.\n"
servers:
- url: https://homecare.alayacare.ca/ext/api/v2/clinical
tags:
- name: Medication Administration
paths:
  /medications/{medication_id}/administrations:
    parameters:
    - description: Medication ID
      name: medication_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Medication Administration
      summary: Get a list of medication administrations
      description: The fields that are populated on the when administering a medication depend on the medication `delivery_mode`.
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/count'
      responses:
        200:
          description: A list of medication administrations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MedicationAdministrationList'
        401:
          $ref: '#/components/responses/AuthChallenge'
        400:
          $ref: '#/components/responses/InvalidRequest'
        404:
          $ref: '#/components/responses/NotFound'
    post:
      tags:
      - Medication Administration
      summary: Create a medication administration.
      responses:
        201:
          description: Administration created successfully
          content:
            application/json:
              schema:
                type: object
                description: Success returned from the API when creating or updating an entity.
                properties:
                  id:
                    type: string
                    description: The entity ID.
                    example: 70ad613a-376c-4389-bb45-78374dddd03e
        401:
          $ref: '#/components/responses/AuthChallenge'
        400:
          $ref: '#/components/responses/InvalidRequest'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MedicationAdministrationCreate'
        description: Medication administration data
        required: true
  /medications/{medication_id}/administrations/{admin_id}:
    parameters:
    - description: Medication ID
      name: medication_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    - description: Medication Administration ID
      name: admin_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Medication Administration
      summary: Get details of a medication administration
      responses:
        200:
          description: Medication administration details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MedicationAdministration'
        401:
          $ref: '#/components/responses/AuthChallenge'
        400:
          $ref: '#/components/responses/InvalidRequest'
        404:
          $ref: '#/components/responses/NotFound'
components:
  responses:
    NotFound:
      description: Not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 404
            message: Progress note not found
    AuthChallenge:
      description: Authentication required.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 401
            message: Please verify your access level for this url.
    InvalidRequest:
      description: Invalid data.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 400
            message: Invalid request
  schemas:
    MedicationAdministrationCreate:
      type: object
      description: Medication admninistration details
      required:
      - medication_id
      - created_employee_id
      - updated_employee_id
      properties:
        amount_given:
          type:
          - string
          - 'null'
        bolus_dose:
          type:
          - string
          - 'null'
        bolus_dose_lockout:
          type:
          - string
          - 'null'
        bolus_doses_attempted:
          type:
          - string
          - 'null'
        bolus_doses_given:
          type:
          - string
          - 'null'
        comments:
          type:
          - string
          - 'null'
          description: Any additional comments for the administration.
        concentration:
          type:
          - string
          - 'null'
        created_employee_id:
          type: integer
          description: The ID of the employee that created the entity.
        date_complete:
          type: string
          description: The date that the medication was administered using ISO 8601 date-time formatting. The default is now.
          example: '2018-01-01T00:30:00+00:00'
        delivery_cycle:
          type:
          - string
          - 'null'
        delivery_mode:
          type:
          - string
          - 'null'
        delivery_period:
          type:
          - string
          - 'null'
        device_type:
          type:
          - string
          - 'null'
        did_not_administer:
          type: boolean
          description: Whether the medication was held. The default is `false`.
          example: false
        dose:
          type:
          - string
          - 'null'
        dose_volume:
          type:
          - string
          - 'null'
        duration:
          type:
          - string
          - 'null'
        hourly_rate:
          type:
          - string
          - 'null'
        id:
          type: string
        infusion_duration:
          type:
          - string
          - 'null'
        initial_rate:
          type:
          - string
          - 'null'
        kvo_rate:
          type:
          - string
          - 'null'
        line_primed:
          $ref: '#/components/schemas/YesNo'
        lock_level:
          type:
          - string
          - 'null'
        max_bolus_dose:
          type:
          - string
          - 'null'
        medication_id:
          type: string
          description: The ID of the medication being administered.
          example: 7f835fe4-4485-44de-a6b8-00a0c1438327
        next_dose_start_time:
          type:
          - string
          - 'null'
          description: The start time of the next dose using ISO 8601 date-time formatting.
        plateau_rate:
          type:
          - string
          - 'null'
        rate:
          type:
          - string
          - 'null'
        rate_increment:
          type:
          - string
          - 'null'
        reservoir_bag_change:
          $ref: '#/components/schemas/YesNo'
        residual_volume:
          type:
          - string
          - 'null'
        route:
          type:
          - string
          - 'null'
          example: The route that was used in the administration.
        step_duration:
          type:
          - string
          - 'null'
        taper:
          type:
          - string
          - 'null'
        total_given:
          type:
          - string
          - 'null'
        updated_employee_id:
          type: integer
          description: The ID of the employee that last updated the entity.
    ErrorResponse:
      description: Error response
      type: object
      properties:
        code:
          type: integer
          description: Response code
        message:
          type: string
          description: Detailed error message
      required:
      - code
      - message
    YesNo:
      type:
      - string
      - 'null'
      description: Whether the action was performed.
      enum:
      - true
      - false
      example: true
    PaginatedList:
      description: Base model of all paginated lists
      type: object
      properties:
        count:
          type: integer
          description: Number of items in the response
          example: 1
        page:
          type: integer
          description: Current page number
          example: 1
        total_pages:
          type: integer
          description: Total number of pages availbale
          example: 1
        items:
          type: array
          items:
            type: object
      required:
      - count
      - page
      - total_pages
      - items
    MedicationAdministration:
      allOf:
      - $ref: '#/components/schemas/MedicationAdministrationCreate'
      type: object
      description: Medication admninistration details
      required:
      - medication_id
      - created_employee_id
      - date_complete
      - id
      - updated_employee_id
    MedicationAdministrationList:
      allOf:
      - $ref: '#/components/schemas/PaginatedList'
      description: Paginated list of the medication administration
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/MedicationAdministration'
  parameters:
    count:
      name: count
      in: query
      required: false
      description: Number of items per page. If not specified will default to 100.
      schema:
        type: integer
        default: 100
    page:
      name: page
      in: query
      required: false
      description: Filter by page number. If not specified will default to 1.
      schema:
        type: integer
        default: 1
  securitySchemes:
    basic_auth:
      type: http
      scheme: basic
      description: Basic HTTP auth over https