openapi: 3.0.0
paths:
  /auth/token/exchange:
    post:
      description: >

        <p>Exchange a long-lived API key for a short-lived JWT access token (15
        minutes).</p>

        <p>This provides enhanced security by minimizing API key exposure.</p>


        <p><strong>Permissions and Scope:</strong></p>

        <ul>
          <li>All permissions, scopes, and home access are automatically determined by the API key</li>
          <li>No need to specify permissions in the request body</li>
          <li>The generated token will have all permissions associated with the API key</li>
        </ul>


        <p><strong>Rate Limits:</strong></p>

        <ul>
          <li>Tracked per client IP address, independent of API key</li>
          <li>10 requests per minute, applied consistently across all environments</li>
        </ul>


        <p><strong>Security Features:</strong></p>

        <ul>
          <li>Tokens expire automatically after 15 minutes</li>
          <li>IP-based monitoring and abuse detection</li>
          <li>Comprehensive audit logging</li>
        </ul>


        <p><strong>Usage Pattern:</strong></p>

        <ol>
          <li>Exchange API key for access token at secure endpoint</li>
          <li>Use access token for API calls (never use API key directly)</li>
          <li>Re-exchange when token expires (every 15 minutes)</li>
        </ol>


        <p>This follows OAuth 2.0 Token Exchange (RFC 8693) patterns.</p>
      operationId: exchangeToken
      parameters:
        - name: User-Agent
          in: header
          description: Client identification for security monitoring
          required: false
          schema:
            type: string
        - name: X-Forwarded-For
          in: header
          description: Client IP address for rate limiting and monitoring
          required: false
          schema:
            type: string
      requestBody:
        required: true
        description: Token exchange request parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenExchangeRequestDto'
      responses:
        '200':
          description: Token exchange successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenExchangeResponseDto'
        '400':
          description: Invalid request (bad API key, invalid scope, etc.)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenExchangeErrorDto'
        '429':
          description: Rate limit exceeded for this endpoint or API key
      summary: Exchange API key for short-lived access token
      tags:
        - token-exchange
  /health:
    get:
      description: >

        <p>Health check endpoint that returns the application status, uptime,
        and version information.</p>

        <p>This endpoint is used by load balancers and monitoring systems.</p>

        <p><strong>Note:</strong> This endpoint does not require
        authentication.</p>
      operationId: getHealth
      parameters: []
      responses:
        '200':
          description: Application is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - ok
                      - error
                    example: ok
                  timestamp:
                    type: string
                    format: date-time
                    example: '2024-09-10T10:30:00.000Z'
                  uptime:
                    type: number
                    example: 3600000
                    description: Application uptime in milliseconds
                  version:
                    type: string
                    example: 1.0.0
                    description: Application version from package.json
                  commitSha:
                    type: string
                    example: 9f8e7d6a1b2c3d4e5f60718293a4b5c6d7e8f901
                    description: Git commit SHA the running build was built from
                  databaseSource:
                    type: string
                    enum:
                      - mongo
                    example: mongo
                    description: Active database source implementation
      summary: Health check
      tags:
        - health
  /openapi/health:
    get:
      operationId: getHealthLegacy
      parameters: []
      responses:
        '200':
          description: ''
      tags:
        - health
  /api/residents:
    get:
      description: >

        <p>Retrieves residents with personal details, medical history, room
        location, and care preferences.</p>

        <p><strong>Filters:</strong></p>

        <ul>
          <li><code>homeId</code> - Filter by specific care home</li>
          <li><code>residentId</code> - Filter by specific resident</li>
          <li><code>startDate</code>, <code>endDate</code> - Date range filtering</li>
          <li><code>dateField</code> - Date field to filter on (e.g., createdOn, admissionDate)</li>
          <li><code>page</code>, <code>limit</code> - Pagination controls (default: page=1, limit=10, max=100)</li>
        </ul>
      operationId: getResidents
      parameters:
        - name: startDate
          required: false
          in: query
          description: Start date for filtering (inclusive)
          schema:
            format: date
            example: '2026-01-01'
            type: string
        - name: endDate
          required: false
          in: query
          description: End date for filtering (inclusive)
          schema:
            format: date
            example: '2026-12-31'
            type: string
        - name: page
          required: false
          in: query
          description: Page number (1-based)
          schema:
            minimum: 1
            default: 1
            example: 1
            type: number
        - name: limit
          required: false
          in: query
          description: Number of records per page
          schema:
            minimum: 1
            maximum: 100
            default: 10
            example: 10
            type: number
        - name: homeId
          required: false
          in: query
          description: Filter by home ID
          schema:
            example: home-123-abc
            type: string
        - name: residentId
          required: false
          in: query
          description: Filter by resident ID
          schema:
            example: resident-456-def
            type: string
        - name: dateField
          required: false
          in: query
          description: Date field to filter on
          schema:
            example: created_on
            type: string
            enum:
              - created_on
              - date_of_birth
              - admission_date
              - status_changed_on
              - ingested_on
      responses:
        '200':
          description: Successfully retrieved records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResidentResponseDto'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: Invalid query parameters
                  details:
                    field: startDate
                    provided: invalid-date
                    expected: ISO 8601 format (YYYY-MM-DD)
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12345
        '401':
          description: Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: AUTHENTICATION_REQUIRED
                  message: Invalid or expired JWT token
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12346
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12347
      security:
        - bearer: []
      summary: Get residents
      tags:
        - Modules / Residents
    post:
      operationId: createResident
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateResidentDto'
      responses:
        '201':
          description: Successfully created resident
          content:
            application/json:
              schema:
                example:
                  id: 69613fc010eecc5386f987ae
                  name:
                    first: Margaret
                    last: Thompson
                  email: margaret.thompson@example.com
                  gender: female
                  dateOfBirth: '1945-06-15T00:00:00.000Z'
                  createdOn: '2026-01-15T09:30:00.000Z'
                  admissionDate: '2026-01-10T00:00:00.000Z'
                  preferredName: Maggie
                  status: active
                  statusChangedOn: '2026-01-20T10:00:00.000Z'
                  isInactive: false
                  home:
                    id: 66e2aeef14dce156439010d5
                    name: Sunrise Care Home
                  location:
                    roomName: Room 12
                    unit: Oak Wing
                    floor: '1'
                  nhsNumber: 999 000 0001
                  bloodType: O+
                  allergies: Penicillin
                  hasAllergies: true
                  noKnownAllergies: false
                  residentAllergies:
                    - Penicillin
                    - Latex
                  medicalHistory: Hypertension, Type 2 diabetes
                  height: 165cm
                  gpCode: G1234567
                  gpName: Dr. Sarah Williams
                  gpEmail: sarah.williams@nhs.example.com
                  gpTelephone: +44 1632 960123
                  gpAddress:
                    street1: 1 Example Lane
                    suburb: Exampletown
                    postcode: EX1 1CD
                    country: United Kingdom
                  gpSurgeryName: Example Medical Practice
                  phones:
                    - number: +44 7700 900123
                      type: mobile
                  addresses:
                    - street1: 45 Example Avenue
                      suburb: Exampletown
                      postcode: EX1 1EF
                      country: United Kingdom
                      isCurrent: true
                      isPrevious: false
                  importantContacts:
                    - name:
                        first: Robert
                        last: Thompson
                      relationship: Son
                      nextOfKin: true
                      lpa: true
                      phone: +44 7700 900456
                      email: robert.thompson@example.com
                      addresses:
                        - street1: 1 Example Street
                          suburb: Leeds
                          postcode: EX1 1EX
                          country: United Kingdom
                  preferredContactMethod: noPreference
                  religion: Christian
                  ethnicity: White British
                  nationality: British
                  nationalities:
                    - British
                  languagesSpoken:
                    - English
                  maritalStatus: widowed
                  birthplace: York
                  sexualPreference: heterosexual
                  carePackage:
                    fundingSource: localAuthority
                    fundingSourceNotes: Funded by York City Council
                    fundingSourceOther: ''
                  fundingSource: localAuthority
                  fundingSourceNotes: Funded by York City Council
                  fundingSourceOther: ''
                  keyworkers:
                    - 68406c31e55ca6b6d2262f56
                  carerPreferences:
                    gender: female
                    language: English
                  preferredDrink: Tea with milk
                  preferredAdminRoute: oral
                  dols:
                    status: authorised
                    startDate: '2026-02-01T00:00:00.000Z'
                    endDate: '2026-08-01T00:00:00.000Z'
                    reviewDate: '2026-05-01T00:00:00.000Z'
                    applicationDate: '2026-01-15T00:00:00.000Z'
                  dolsStartDate: '2026-02-01T00:00:00.000Z'
                  dolsEndDate: '2026-08-01T00:00:00.000Z'
                  dolsReviewDate: '2026-05-01T00:00:00.000Z'
                  dolsApplicationDate: '2026-01-15T00:00:00.000Z'
                  dnacpr:
                    hasDnacpr: true
                    details: DNACPR in place, reviewed by GP
                    reviewDate: '2026-06-01T00:00:00.000Z'
                    formPhysicalLocation: Front of care file
                  dnacprDetails: DNACPR in place, reviewed by GP
                  dnacprReviewDate: '2026-06-01T00:00:00.000Z'
                  dnacprFormPhysicalLocation: Front of care file
                  recentMustScore: '1'
                  recentWaterlowScore: '12'
                  recentDrinkConsumption: 1500ml
                  hasChokingRisk: false
                  prnMedsNote: Paracetamol PRN for pain
                  nationalInsurance: QQ123456C
                  summary: >-
                    Margaret is a friendly resident who enjoys gardening and
                    reading.
                  otherIdentifiers:
                    - type: localAuthorityRef
                      value: LA-2026-0042
                  customId: example-resident-id-123
                  ageYears: 80
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: Invalid query parameters
                  details:
                    field: startDate
                    provided: invalid-date
                    expected: ISO 8601 format (YYYY-MM-DD)
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12345
        '401':
          description: Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: AUTHENTICATION_REQUIRED
                  message: Invalid or expired JWT token
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12346
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: FORBIDDEN
                  message: Insufficient permissions to access this resource
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12349
        '409':
          description: Resident with this externalSource already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12347
      security:
        - bearer: []
      summary: Create resident
      tags:
        - Modules / Residents
  /api/residents/{id}:
    get:
      description: >

        <p>Retrieves complete resident information including medical history,
        allergies, GP details, care preferences, and room location.</p>
      operationId: getResidentById
      parameters:
        - name: id
          required: true
          in: path
          description: Unique identifier of the resident
          schema:
            example: 64f8a1b23d4e5f6a7b8c9d0e
            type: string
      responses:
        '200':
          description: Successfully retrieved resident
          content:
            application/json:
              schema:
                example:
                  id: 69613fc010eecc5386f987ae
                  name:
                    first: Margaret
                    last: Thompson
                  email: margaret.thompson@example.com
                  gender: female
                  dateOfBirth: '1945-06-15T00:00:00.000Z'
                  createdOn: '2026-01-15T09:30:00.000Z'
                  admissionDate: '2026-01-10T00:00:00.000Z'
                  preferredName: Maggie
                  status: active
                  statusChangedOn: '2026-01-20T10:00:00.000Z'
                  isInactive: false
                  home:
                    id: 66e2aeef14dce156439010d5
                    name: Sunrise Care Home
                  location:
                    roomName: Room 12
                    unit: Oak Wing
                    floor: '1'
                  nhsNumber: 999 000 0001
                  bloodType: O+
                  allergies: Penicillin
                  hasAllergies: true
                  noKnownAllergies: false
                  residentAllergies:
                    - Penicillin
                    - Latex
                  medicalHistory: Hypertension, Type 2 diabetes
                  height: 165cm
                  gpCode: G1234567
                  gpName: Dr. Sarah Williams
                  gpEmail: sarah.williams@nhs.example.com
                  gpTelephone: +44 1632 960123
                  gpAddress:
                    street1: 1 Example Lane
                    suburb: Exampletown
                    postcode: EX1 1CD
                    country: United Kingdom
                  gpSurgeryName: Example Medical Practice
                  phones:
                    - number: +44 7700 900123
                      type: mobile
                  addresses:
                    - street1: 45 Example Avenue
                      suburb: Exampletown
                      postcode: EX1 1EF
                      country: United Kingdom
                      isCurrent: true
                      isPrevious: false
                  importantContacts:
                    - name:
                        first: Robert
                        last: Thompson
                      relationship: Son
                      nextOfKin: true
                      lpa: true
                      phone: +44 7700 900456
                      email: robert.thompson@example.com
                      addresses:
                        - street1: 1 Example Street
                          suburb: Leeds
                          postcode: EX1 1EX
                          country: United Kingdom
                  preferredContactMethod: noPreference
                  religion: Christian
                  ethnicity: White British
                  nationality: British
                  nationalities:
                    - British
                  languagesSpoken:
                    - English
                  maritalStatus: widowed
                  birthplace: York
                  sexualPreference: heterosexual
                  carePackage:
                    fundingSource: localAuthority
                    fundingSourceNotes: Funded by York City Council
                    fundingSourceOther: ''
                  fundingSource: localAuthority
                  fundingSourceNotes: Funded by York City Council
                  fundingSourceOther: ''
                  keyworkers:
                    - 68406c31e55ca6b6d2262f56
                  carerPreferences:
                    gender: female
                    language: English
                  preferredDrink: Tea with milk
                  preferredAdminRoute: oral
                  dols:
                    status: authorised
                    startDate: '2026-02-01T00:00:00.000Z'
                    endDate: '2026-08-01T00:00:00.000Z'
                    reviewDate: '2026-05-01T00:00:00.000Z'
                    applicationDate: '2026-01-15T00:00:00.000Z'
                  dolsStartDate: '2026-02-01T00:00:00.000Z'
                  dolsEndDate: '2026-08-01T00:00:00.000Z'
                  dolsReviewDate: '2026-05-01T00:00:00.000Z'
                  dolsApplicationDate: '2026-01-15T00:00:00.000Z'
                  dnacpr:
                    hasDnacpr: true
                    details: DNACPR in place, reviewed by GP
                    reviewDate: '2026-06-01T00:00:00.000Z'
                    formPhysicalLocation: Front of care file
                  dnacprDetails: DNACPR in place, reviewed by GP
                  dnacprReviewDate: '2026-06-01T00:00:00.000Z'
                  dnacprFormPhysicalLocation: Front of care file
                  recentMustScore: '1'
                  recentWaterlowScore: '12'
                  recentDrinkConsumption: 1500ml
                  hasChokingRisk: false
                  prnMedsNote: Paracetamol PRN for pain
                  nationalInsurance: QQ123456C
                  summary: >-
                    Margaret is a friendly resident who enjoys gardening and
                    reading.
                  otherIdentifiers:
                    - type: localAuthorityRef
                      value: LA-2026-0042
                  customId: example-resident-id-123
                  ageYears: 80
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: Invalid query parameters
                  details:
                    field: startDate
                    provided: invalid-date
                    expected: ISO 8601 format (YYYY-MM-DD)
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12345
        '401':
          description: Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: AUTHENTICATION_REQUIRED
                  message: Invalid or expired JWT token
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12346
        '404':
          description: Resident not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: NOT_FOUND
                  message: Resident with ID '64f8a1b23d4e5f6a7b8c9d0e' not found
                  details:
                    field: id
                    provided: 64f8a1b23d4e5f6a7b8c9d0e
                    expected: Valid resident ID
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12348
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12347
      security:
        - bearer: []
      summary: Get resident by ID
      tags:
        - Modules / Residents
    put:
      operationId: updateResident
      parameters:
        - name: id
          required: true
          in: path
          description: Unique identifier of the resident
          schema:
            example: 64f8a1b23d4e5f6a7b8c9d0e
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateResidentDto'
      responses:
        '200':
          description: Successfully updated resident
          content:
            application/json:
              schema:
                example:
                  id: 69613fc010eecc5386f987ae
                  name:
                    first: Margaret
                    last: Thompson
                  email: margaret.thompson@example.com
                  gender: female
                  dateOfBirth: '1945-06-15T00:00:00.000Z'
                  createdOn: '2026-01-15T09:30:00.000Z'
                  admissionDate: '2026-01-10T00:00:00.000Z'
                  preferredName: Maggie
                  status: active
                  statusChangedOn: '2026-01-20T10:00:00.000Z'
                  isInactive: false
                  home:
                    id: 66e2aeef14dce156439010d5
                    name: Sunrise Care Home
                  location:
                    roomName: Room 12
                    unit: Oak Wing
                    floor: '1'
                  nhsNumber: 999 000 0001
                  bloodType: O+
                  allergies: Penicillin
                  hasAllergies: true
                  noKnownAllergies: false
                  residentAllergies:
                    - Penicillin
                    - Latex
                  medicalHistory: Hypertension, Type 2 diabetes
                  height: 165cm
                  gpCode: G1234567
                  gpName: Dr. Sarah Williams
                  gpEmail: sarah.williams@nhs.example.com
                  gpTelephone: +44 1632 960123
                  gpAddress:
                    street1: 1 Example Lane
                    suburb: Exampletown
                    postcode: EX1 1CD
                    country: United Kingdom
                  gpSurgeryName: Example Medical Practice
                  phones:
                    - number: +44 7700 900123
                      type: mobile
                  addresses:
                    - street1: 45 Example Avenue
                      suburb: Exampletown
                      postcode: EX1 1EF
                      country: United Kingdom
                      isCurrent: true
                      isPrevious: false
                  importantContacts:
                    - name:
                        first: Robert
                        last: Thompson
                      relationship: Son
                      nextOfKin: true
                      lpa: true
                      phone: +44 7700 900456
                      email: robert.thompson@example.com
                      addresses:
                        - street1: 1 Example Street
                          suburb: Leeds
                          postcode: EX1 1EX
                          country: United Kingdom
                  preferredContactMethod: noPreference
                  religion: Christian
                  ethnicity: White British
                  nationality: British
                  nationalities:
                    - British
                  languagesSpoken:
                    - English
                  maritalStatus: widowed
                  birthplace: York
                  sexualPreference: heterosexual
                  carePackage:
                    fundingSource: localAuthority
                    fundingSourceNotes: Funded by York City Council
                    fundingSourceOther: ''
                  fundingSource: localAuthority
                  fundingSourceNotes: Funded by York City Council
                  fundingSourceOther: ''
                  keyworkers:
                    - 68406c31e55ca6b6d2262f56
                  carerPreferences:
                    gender: female
                    language: English
                  preferredDrink: Tea with milk
                  preferredAdminRoute: oral
                  dols:
                    status: authorised
                    startDate: '2026-02-01T00:00:00.000Z'
                    endDate: '2026-08-01T00:00:00.000Z'
                    reviewDate: '2026-05-01T00:00:00.000Z'
                    applicationDate: '2026-01-15T00:00:00.000Z'
                  dolsStartDate: '2026-02-01T00:00:00.000Z'
                  dolsEndDate: '2026-08-01T00:00:00.000Z'
                  dolsReviewDate: '2026-05-01T00:00:00.000Z'
                  dolsApplicationDate: '2026-01-15T00:00:00.000Z'
                  dnacpr:
                    hasDnacpr: true
                    details: DNACPR in place, reviewed by GP
                    reviewDate: '2026-06-01T00:00:00.000Z'
                    formPhysicalLocation: Front of care file
                  dnacprDetails: DNACPR in place, reviewed by GP
                  dnacprReviewDate: '2026-06-01T00:00:00.000Z'
                  dnacprFormPhysicalLocation: Front of care file
                  recentMustScore: '1'
                  recentWaterlowScore: '12'
                  recentDrinkConsumption: 1500ml
                  hasChokingRisk: false
                  prnMedsNote: Paracetamol PRN for pain
                  nationalInsurance: QQ123456C
                  summary: >-
                    Margaret is a friendly resident who enjoys gardening and
                    reading.
                  otherIdentifiers:
                    - type: localAuthorityRef
                      value: LA-2026-0042
                  customId: example-resident-id-123
                  ageYears: 80
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: Invalid query parameters
                  details:
                    field: startDate
                    provided: invalid-date
                    expected: ISO 8601 format (YYYY-MM-DD)
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12345
        '401':
          description: Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: AUTHENTICATION_REQUIRED
                  message: Invalid or expired JWT token
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12346
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: FORBIDDEN
                  message: Insufficient permissions to access this resource
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12349
        '404':
          description: Resident not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: NOT_FOUND
                  message: Resident with ID '64f8a1b23d4e5f6a7b8c9d0e' not found
                  details:
                    field: id
                    provided: 64f8a1b23d4e5f6a7b8c9d0e
                    expected: Valid resident ID
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12348
        '409':
          description: Resident with this externalSource already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12347
      security:
        - bearer: []
      summary: Update resident
      tags:
        - Modules / Residents
  /api/users:
    get:
      description: >

        <p>Retrieves users with their roles, permissions, and homeIds. Password
        fields are excluded for security.</p>

        <p><strong>Filters:</strong></p>

        <ul>
          <li><code>homeId</code> - Filter by specific care home</li>
          <li><code>startDate</code>, <code>endDate</code> - Date range filtering</li>
          <li><code>dateField</code> - Date field to filter on (default: createdOn)</li>
          <li><code>page</code>, <code>limit</code> - Pagination controls</li>
        </ul>
      operationId: getUsers
      parameters:
        - name: startDate
          required: false
          in: query
          description: Start date for filtering (inclusive)
          schema:
            format: date
            example: '2026-01-01'
            type: string
        - name: endDate
          required: false
          in: query
          description: End date for filtering (inclusive)
          schema:
            format: date
            example: '2026-12-31'
            type: string
        - name: page
          required: false
          in: query
          description: Page number (1-based)
          schema:
            minimum: 1
            default: 1
            example: 1
            type: number
        - name: limit
          required: false
          in: query
          description: Number of records per page
          schema:
            minimum: 1
            maximum: 100
            default: 10
            example: 10
            type: number
        - name: dateField
          required: false
          in: query
          description: Date field to filter on
          schema:
            default: created_on
            example: created_on
            type: string
            enum:
              - created_on
              - start_date
              - end_date
              - last_seen_on
              - first_login_on
              - ingested_on
      responses:
        '200':
          description: Successfully retrieved records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponseDto'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: Invalid query parameters
                  details:
                    field: startDate
                    provided: invalid-date
                    expected: ISO 8601 format (YYYY-MM-DD)
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12345
        '401':
          description: Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: AUTHENTICATION_REQUIRED
                  message: Invalid or expired JWT token
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12346
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12347
      security:
        - bearer: []
      summary: Get users
      tags:
        - Modules / Users
    post:
      operationId: createUser
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserDto'
      responses:
        '201':
          description: Successfully created user
          content:
            application/json:
              schema:
                example:
                  id: 68406c31e55ca6b6d2262f56
                  name:
                    first: Jane
                    last: Smith
                    full: Jane Smith
                  email: jane.smith@example.co.uk
                  role: carehome-admin
                  cernerRole: standard
                  active: true
                  deleted: false
                  dateOfBirth: '1985-03-22T00:00:00.000Z'
                  startDate: '2026-01-02T00:00:00.000Z'
                  endDate: null
                  createdOn: '2026-01-15T09:00:00.000Z'
                  lastSeen: '2026-02-10T16:45:00.000Z'
                  firstLogin: '2026-01-15T09:18:06.809Z'
                  phoneNumber: +44 7700 900789
                  address:
                    name: ''
                    number: '10'
                    street1: Example Road
                    street2: ''
                    suburb: York
                    state: ''
                    postcode: EX1 1AB
                  allergies: None
                  hasAllergies: 'no'
                  home: 5a1174a35dcb0e004030a28d
                  homes:
                    - 5a1174a35dcb0e004030a28d
                  permissions:
                    - residents:read
                    - logs:read
                  permissionsTemplate: care-home-admin
                  medicationPermission: true
                  gpConnectPermission: false
                  zones:
                    - Oak Wing
                  allZones: false
                  workProfile:
                    contractType: fullTime
                    contractedHoursPerWeek: 37.5
                    contractNotes: ''
                    rotaPreferenceNotes: Prefers day shifts
                    canDoOvertime: true
                    availableTransportation:
                      - car
                    availability: {}
                  hasRequestedDemo: false
                  picture: >-
                    https://lmc-care-uploads.s3.eu-west-2.amazonaws.com/photos/users/example-user-id/avatar.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=EXAMPLE%2F20260115%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20260115T090000Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=examplesignature
                  summary: Experienced care home administrator.
                  customId: example-admin-id-123
                  resident: null
                  emergencyContactName:
                    first: John
                    last: Smith
                  emergencyContactRelation: Spouse
                  emergencyContactNumber: +44 7700 900999
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: Invalid query parameters
                  details:
                    field: startDate
                    provided: invalid-date
                    expected: ISO 8601 format (YYYY-MM-DD)
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12345
        '401':
          description: Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: AUTHENTICATION_REQUIRED
                  message: Invalid or expired JWT token
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12346
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: FORBIDDEN
                  message: Insufficient permissions to access this resource
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12349
        '409':
          description: User with this email or externalSource already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12347
      security:
        - bearer: []
      summary: Create user
      tags:
        - Modules / Users
  /api/users/{id}:
    get:
      description: >

        <p>Retrieves a complete user profile including roles, permissions,
        homeIds, and employment details. Password fields are excluded for
        security.</p>
      operationId: getUserById
      parameters:
        - name: id
          required: true
          in: path
          description: Unique identifier of the user
          schema:
            example: 64f8a1b23d4e5f6a7b8c9d0e
            type: string
      responses:
        '200':
          description: Successfully retrieved user
          content:
            application/json:
              schema:
                example:
                  id: 68406c31e55ca6b6d2262f56
                  name:
                    first: Jane
                    last: Smith
                    full: Jane Smith
                  email: jane.smith@example.co.uk
                  role: carehome-admin
                  cernerRole: standard
                  active: true
                  deleted: false
                  dateOfBirth: '1985-03-22T00:00:00.000Z'
                  startDate: '2026-01-02T00:00:00.000Z'
                  endDate: null
                  createdOn: '2026-01-15T09:00:00.000Z'
                  lastSeen: '2026-02-10T16:45:00.000Z'
                  firstLogin: '2026-01-15T09:18:06.809Z'
                  phoneNumber: +44 7700 900789
                  address:
                    name: ''
                    number: '10'
                    street1: Example Road
                    street2: ''
                    suburb: York
                    state: ''
                    postcode: EX1 1AB
                  allergies: None
                  hasAllergies: 'no'
                  home: 5a1174a35dcb0e004030a28d
                  homes:
                    - 5a1174a35dcb0e004030a28d
                  permissions:
                    - residents:read
                    - logs:read
                  permissionsTemplate: care-home-admin
                  medicationPermission: true
                  gpConnectPermission: false
                  zones:
                    - Oak Wing
                  allZones: false
                  workProfile:
                    contractType: fullTime
                    contractedHoursPerWeek: 37.5
                    contractNotes: ''
                    rotaPreferenceNotes: Prefers day shifts
                    canDoOvertime: true
                    availableTransportation:
                      - car
                    availability: {}
                  hasRequestedDemo: false
                  picture: >-
                    https://lmc-care-uploads.s3.eu-west-2.amazonaws.com/photos/users/example-user-id/avatar.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=EXAMPLE%2F20260115%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20260115T090000Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=examplesignature
                  summary: Experienced care home administrator.
                  customId: example-admin-id-123
                  resident: null
                  emergencyContactName:
                    first: John
                    last: Smith
                  emergencyContactRelation: Spouse
                  emergencyContactNumber: +44 7700 900999
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: Invalid query parameters
                  details:
                    field: startDate
                    provided: invalid-date
                    expected: ISO 8601 format (YYYY-MM-DD)
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12345
        '401':
          description: Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: AUTHENTICATION_REQUIRED
                  message: Invalid or expired JWT token
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12346
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: NOT_FOUND
                  message: User with ID '64f8a1b23d4e5f6a7b8c9d0e' not found
                  details:
                    field: id
                    provided: 64f8a1b23d4e5f6a7b8c9d0e
                    expected: Valid user ID
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12348
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12347
      security:
        - bearer: []
      summary: Get user by ID
      tags:
        - Modules / Users
    put:
      operationId: updateUser
      parameters:
        - name: id
          required: true
          in: path
          description: Unique identifier of the user
          schema:
            example: 64f8a1b23d4e5f6a7b8c9d0e
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserDto'
      responses:
        '200':
          description: Successfully updated user
          content:
            application/json:
              schema:
                example:
                  id: 68406c31e55ca6b6d2262f56
                  name:
                    first: Jane
                    last: Smith
                    full: Jane Smith
                  email: jane.smith@example.co.uk
                  role: carehome-admin
                  cernerRole: standard
                  active: true
                  deleted: false
                  dateOfBirth: '1985-03-22T00:00:00.000Z'
                  startDate: '2026-01-02T00:00:00.000Z'
                  endDate: null
                  createdOn: '2026-01-15T09:00:00.000Z'
                  lastSeen: '2026-02-10T16:45:00.000Z'
                  firstLogin: '2026-01-15T09:18:06.809Z'
                  phoneNumber: +44 7700 900789
                  address:
                    name: ''
                    number: '10'
                    street1: Example Road
                    street2: ''
                    suburb: York
                    state: ''
                    postcode: EX1 1AB
                  allergies: None
                  hasAllergies: 'no'
                  home: 5a1174a35dcb0e004030a28d
                  homes:
                    - 5a1174a35dcb0e004030a28d
                  permissions:
                    - residents:read
                    - logs:read
                  permissionsTemplate: care-home-admin
                  medicationPermission: true
                  gpConnectPermission: false
                  zones:
                    - Oak Wing
                  allZones: false
                  workProfile:
                    contractType: fullTime
                    contractedHoursPerWeek: 37.5
                    contractNotes: ''
                    rotaPreferenceNotes: Prefers day shifts
                    canDoOvertime: true
                    availableTransportation:
                      - car
                    availability: {}
                  hasRequestedDemo: false
                  picture: >-
                    https://lmc-care-uploads.s3.eu-west-2.amazonaws.com/photos/users/example-user-id/avatar.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=EXAMPLE%2F20260115%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20260115T090000Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=examplesignature
                  summary: Experienced care home administrator.
                  customId: example-admin-id-123
                  resident: null
                  emergencyContactName:
                    first: John
                    last: Smith
                  emergencyContactRelation: Spouse
                  emergencyContactNumber: +44 7700 900999
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: Invalid query parameters
                  details:
                    field: startDate
                    provided: invalid-date
                    expected: ISO 8601 format (YYYY-MM-DD)
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12345
        '401':
          description: Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: AUTHENTICATION_REQUIRED
                  message: Invalid or expired JWT token
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12346
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: FORBIDDEN
                  message: Insufficient permissions to access this resource
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12349
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: NOT_FOUND
                  message: User with ID '64f8a1b23d4e5f6a7b8c9d0e' not found
                  details:
                    field: id
                    provided: 64f8a1b23d4e5f6a7b8c9d0e
                    expected: Valid user ID
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12348
        '409':
          description: User with this email or externalSource already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12347
      security:
        - bearer: []
      summary: Update user
      tags:
        - Modules / Users
  /api/careplans:
    get:
      description: >

        <p>Retrieves care plans with goals, assessments, documents, and tracking
        information.</p>

        <p><strong>Filters:</strong></p>

        <ul>
          <li><code>homeId</code> - Filter by specific care home</li>
          <li><code>residentId</code> - Filter by specific resident</li>
          <li><code>carePlanId</code> - Filter by care plan ID</li>
          <li><code>startDate</code>, <code>endDate</code> - Date range filtering</li>
          <li><code>dateField</code> - Date field to filter on (default: createdOn)</li>
          <li><code>page</code>, <code>limit</code> - Pagination controls</li>
        </ul>
      operationId: getCarePlans
      parameters:
        - name: startDate
          required: false
          in: query
          description: Start date for filtering (inclusive)
          schema:
            format: date
            example: '2026-01-01'
            type: string
        - name: endDate
          required: false
          in: query
          description: End date for filtering (inclusive)
          schema:
            format: date
            example: '2026-12-31'
            type: string
        - name: page
          required: false
          in: query
          description: Page number (1-based)
          schema:
            minimum: 1
            default: 1
            example: 1
            type: number
        - name: limit
          required: false
          in: query
          description: Number of records per page
          schema:
            minimum: 1
            maximum: 100
            default: 10
            example: 10
            type: number
        - name: homeId
          required: false
          in: query
          description: Filter by home ID
          schema:
            example: home-123-abc
            type: string
        - name: residentId
          required: false
          in: query
          description: Filter by resident ID
          schema:
            example: resident-456-def
            type: string
        - name: dateField
          required: false
          in: query
          description: Date field to filter on for care plan records
          schema:
            $ref: '#/components/schemas/CarePlanDateField'
        - name: carePlanId
          required: false
          in: query
          description: Filter care plans by care plan ID
          schema:
            maxLength: 100
            example: CP-2024-001
            type: string
      responses:
        '200':
          description: Successfully retrieved records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarePlanResponseDto'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: Invalid query parameters
                  details:
                    field: startDate
                    provided: invalid-date
                    expected: ISO 8601 format (YYYY-MM-DD)
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12345
        '401':
          description: Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: AUTHENTICATION_REQUIRED
                  message: Invalid or expired JWT token
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12346
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12347
      security:
        - bearer: []
      summary: Get care plans
      tags:
        - Modules / Care Plans
  /api/careplans/{id}:
    get:
      description: >

        <p>Retrieves a complete care plan including goals, assessments,
        documents, risk assessments, and review history.</p>
      operationId: getCarePlanById
      parameters:
        - name: id
          required: true
          in: path
          description: Unique identifier of the care plan
          schema:
            example: 64f8a1b23d4e5f6a7b8c9d0e
            type: string
      responses:
        '200':
          description: Successfully retrieved care plan
          content:
            application/json:
              schema:
                example:
                  id: 697b6a5b943a178423a9264b
                  name: Enhanced Mobility Care Plan
                  home:
                    id: 66e2aeef14dce156439010d5
                    name: Sunrise Care Home
                  resident:
                    id: 69613fc010eecc5386f987ae
                    name:
                      first: Margaret
                      last: Thompson
                      full: Margaret Thompson
                    preferredName: Maggie
                  editedBy:
                    id: 68406c31e55ca6b6d2262f56
                    name:
                      first: Sarah
                      last: Manager
                      full: Sarah Manager
                  goals:
                    - 6968bf21c441cf6fb4ac9a3e
                  needs: Requires support with mobility and transfers.
                  strengths: >-
                    Motivated to remain independent; engages well with
                    physiotherapy.
                  reviewComment: Progressing well, continue current plan.
                  nextReviewDate: '2026-04-29T00:00:00.000Z'
                  editedOn: '2026-02-01T11:00:00.000Z'
                  createdOn: '2026-01-29T14:10:35.209Z'
                  isCustom: true
                  outcomes: Maintain independent mobility within the home.
                  sections:
                    - title: Mobility
                      needs: >-
                        Requires assistance with transfers and walking longer
                        distances.
                      strengths: Able to walk short distances with a frame.
                      outcomes: Walk to the dining room with minimal assistance.
                  documents:
                    - 6977686fc18f55207654e609
                  revisions: 1
                  carePlanId: 5f213e77cdd809d04ba664be
                  isRevision: false
                  skillNeeds:
                    - 68cae49a5df0b900121771f2
                  subActivity: Transfers
                  fluidTracking:
                    enabled: true
                    intakeTarget: 1500
                  riskAssessments:
                    - 696f910b62d69cb14944bd29
                  noIdentifiedNeed: false
                  noFurtherSupportRequired: false
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: Invalid query parameters
                  details:
                    field: startDate
                    provided: invalid-date
                    expected: ISO 8601 format (YYYY-MM-DD)
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12345
        '401':
          description: Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: AUTHENTICATION_REQUIRED
                  message: Invalid or expired JWT token
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12346
        '404':
          description: Care Plan not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: NOT_FOUND
                  message: Care Plan with ID '64f8a1b23d4e5f6a7b8c9d0e' not found
                  details:
                    field: id
                    provided: 64f8a1b23d4e5f6a7b8c9d0e
                    expected: Valid care plan ID
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12348
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12347
      security:
        - bearer: []
      summary: Get care plan by ID
      tags:
        - Modules / Care Plans
  /api/homes:
    get:
      description: >

        <p>Retrieves care homes with facility details, ODS code, address, bed
        capacity, features, and home group.</p>

        <p><strong>Filters:</strong></p>

        <ul>
          <li><code>page</code>, <code>limit</code> - Pagination controls</li>
        </ul>
      operationId: getHomes
      parameters:
        - name: page
          required: false
          in: query
          description: Page number (1-based)
          schema:
            minimum: 1
            default: 1
            example: 1
            type: number
        - name: limit
          required: false
          in: query
          description: Number of records per page
          schema:
            minimum: 1
            maximum: 100
            default: 10
            example: 10
            type: number
      responses:
        '200':
          description: Successfully retrieved records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HomeResponseDto'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: Invalid query parameters
                  details:
                    field: startDate
                    provided: invalid-date
                    expected: ISO 8601 format (YYYY-MM-DD)
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12345
        '401':
          description: Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: AUTHENTICATION_REQUIRED
                  message: Invalid or expired JWT token
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12346
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: FORBIDDEN
                  message: Insufficient permissions to access this resource
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12349
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12347
      security:
        - bearer: []
      summary: Get homes
      tags:
        - Modules / Homes
  /api/homes/{id}:
    get:
      description: >

        <p>Retrieves complete care home information including ODS code, address,
        bed capacity, home group, rota settings, and feature flags.</p>
      operationId: getHomeById
      parameters:
        - name: id
          required: true
          in: path
          description: Unique identifier of the home
          schema:
            example: 64f8a1b23d4e5f6a7b8c9d0e
            type: string
      responses:
        '200':
          description: Successfully retrieved home
          content:
            application/json:
              schema:
                example:
                  id: 66e2aeef14dce156439010d5
                  name: Sunrise Care Home
                  active: true
                  address:
                    postcode: EX1 1AB
                    state: null
                    street1: 123 Example Street
                    suburb: Exampletown
                    isPrevious: false
                    isCurrent: true
                    country: United Kingdom
                  odsCode: EX001
                  incidentSeverity:
                    '1': Minor
                    '2': Moderate
                    '3': Significant
                    '4': Serious
                    '5': Major
                  telephone: +44 1632 960456
                  bedCapacity: 45
                  countryCode: ENG
                  preferredPeopleNominative: Residents
                  preferredCarePlansNominative: Care Plans
                  customId: example-home-id-123
                  homeGroup:
                    id: 5f155c4ac49007031a671d4e
                    name: Sunrise Care Group
                  logCategoryItems:
                    - id: 5e81db67b1b4e673bc2bb8cc
                      name: Catheter
                  familyLogCategoryItems:
                    - id: 68cae49a5df0b900121771f2
                      name: Activities
                  picture: >-
                    https://lmc-care-uploads.s3.eu-west-2.amazonaws.com/photos/home/example-home-id/home.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=EXAMPLE%2F20260720%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20260720T085642Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=examplesignature
                  showAllResidentsButton: true
                  visitBasedAccessControl: false
                  startAccessTimeValue: 1
                  startAccessTimeUnit: hours
                  endAccessTimeValue: 1
                  endAccessTimeUnit: hours
                  sortByRoomNumber: true
                  familyCarePlans: true
                  familyDocuments: true
                  familyShowNames: true
                  familyShowDates: true
                  locations:
                    - Oak Wing
                    - Maple Wing
                  tier: premium
                  careSetting: residential
                  serviceUserType: olderPeople
                  secondaryCareSetting: nursing
                  secondaryServiceUserType: dementia
                  rotaSettings:
                    flexiVisits: false
                    fundingTypesCount: 3
                    contractTypesCount: 2
                    absenceTypesCount: 4
                    shiftTypesCount: 5
                    visitTypesCount: 0
                  privacyOfficers:
                    - id: 507f1f77bcf86cd799439022
                      name: Jane Smith
                      email: jane.smith@example.com
                      startDate: '2026-01-15T00:00:00.000Z'
                  features:
                    deviceAccessControl:
                      granted: true
                      enabled: true
                    eMAR:
                      granted: true
                      enabled: false
                    family:
                      granted: true
                      enabled: true
                    geoLocation:
                      granted: false
                      enabled: false
                    rota:
                      granted: true
                      enabled: true
                    noticeBoard:
                      granted: true
                      enabled: true
                    positiveBehaviour:
                      granted: false
                      enabled: false
                  createdOn: '2026-07-20T08:56:42.725Z'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: Invalid query parameters
                  details:
                    field: startDate
                    provided: invalid-date
                    expected: ISO 8601 format (YYYY-MM-DD)
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12345
        '401':
          description: Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: AUTHENTICATION_REQUIRED
                  message: Invalid or expired JWT token
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12346
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: FORBIDDEN
                  message: Insufficient permissions to access this resource
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12349
        '404':
          description: Home not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: NOT_FOUND
                  message: Home with ID '64f8a1b23d4e5f6a7b8c9d0e' not found
                  details:
                    field: id
                    provided: 64f8a1b23d4e5f6a7b8c9d0e
                    expected: Valid home ID
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12348
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12347
      security:
        - bearer: []
      summary: Get home by ID
      tags:
        - Modules / Homes
  /api/incident-reports:
    get:
      description: >

        <p>Retrieves incident reports with severity, status, case details, and
        investigation notes.</p>

        <p><strong>Filters:</strong></p>

        <ul>
          <li><code>homeId</code> - Filter by specific care home</li>
          <li><code>residentId</code> - Filter by specific resident</li>
          <li><code>severity</code> - Filter by severity level (1=lowest, 5=highest)</li>
          <li><code>startDate</code>, <code>endDate</code> - Date range filtering</li>
          <li><code>dateField</code> - Date field to filter on (created_on, closed_on, reviewed_on, or ingested_on)</li>
          <li><code>page</code>, <code>limit</code> - Pagination controls</li>
        </ul>
      operationId: getIncidentReports
      parameters:
        - name: startDate
          required: false
          in: query
          description: Start date for filtering (inclusive)
          schema:
            format: date
            example: '2026-01-01'
            type: string
        - name: endDate
          required: false
          in: query
          description: End date for filtering (inclusive)
          schema:
            format: date
            example: '2026-12-31'
            type: string
        - name: page
          required: false
          in: query
          description: Page number (1-based)
          schema:
            minimum: 1
            default: 1
            example: 1
            type: number
        - name: limit
          required: false
          in: query
          description: Number of records per page
          schema:
            minimum: 1
            maximum: 100
            default: 10
            example: 10
            type: number
        - name: homeId
          required: false
          in: query
          description: Filter by home ID
          schema:
            example: home-123-abc
            type: string
        - name: residentId
          required: false
          in: query
          description: Filter by resident ID
          schema:
            example: resident-456-def
            type: string
        - name: severity
          required: false
          in: query
          description: Filter by severity level (1=lowest, 5=highest)
          schema:
            example: 2
            type: number
            enum:
              - 1
              - 2
              - 3
              - 4
              - 5
        - name: dateField
          required: false
          in: query
          description: >-
            Date field to filter on (created_on, closed_on, reviewed_on, or
            ingested_on)
          schema:
            default: ingested_on
            example: ingested_on
            type: string
            enum:
              - created_on
              - closed_on
              - reviewed_on
              - ingested_on
      responses:
        '200':
          description: Successfully retrieved records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentReportResponseDto'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: Invalid query parameters
                  details:
                    field: startDate
                    provided: invalid-date
                    expected: ISO 8601 format (YYYY-MM-DD)
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12345
        '401':
          description: Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: AUTHENTICATION_REQUIRED
                  message: Invalid or expired JWT token
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12346
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: FORBIDDEN
                  message: Insufficient permissions to access this resource
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12349
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12347
      security:
        - bearer: []
      summary: Get incident reports
      tags:
        - Modules / Incident Reports
  /api/incident-reports/{id}:
    get:
      description: >

        <p>Retrieves complete incident details including log, case information,
        witnesses, actions taken, and closure notes.</p>
      operationId: getIncidentReportById
      parameters:
        - name: id
          required: true
          in: path
          description: Unique identifier of the incident report
          schema:
            example: 64f8a1b23d4e5f6a7b8c9d0e
            type: string
      responses:
        '200':
          description: Successfully retrieved incident report
          content:
            application/json:
              schema:
                example:
                  id: 6980aa75a5429846498a40da
                  createdOn: '2026-04-09T18:48:00.000Z'
                  log:
                    title: Safeguarding
                    description: >-
                      Resident reported feeling unsafe in the garden area. Staff
                      responded immediately and documented the incident.
                    timeLogged: '2026-04-09T18:48:00.000Z'
                    location: Garden
                  case: null
                  home:
                    id: 66e2aeef14dce156439010d5
                    name: Sunrise Care Home
                  resident:
                    id: 69613fc010eecc5386f987b2
                    name:
                      first: David
                      last: Williams
                      full: David Williams
                  status: needsReview
                  closedBy: null
                  closedOn: null
                  severity: 2
                  isDeleted: false
                  reviewedOn: null
                  closeComment: null
                  category:
                    id: 5e867702b349f776c8d48c34
                    name: Incident
                    icon: >-
                      https://lmc-data-production.s3.eu-west-2.amazonaws.com/icons/qXxuGVYsSRgAcXoZ.png
                    color: '#FF3366'
                  item:
                    id: 68cae49a5df0b900121771f2
                    name: Safeguarding
                    icon: >-
                      https://lmc-data-production.s3.eu-west-2.amazonaws.com/icons/DrpQZb2rGf1HHvuI.png
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: Invalid query parameters
                  details:
                    field: startDate
                    provided: invalid-date
                    expected: ISO 8601 format (YYYY-MM-DD)
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12345
        '401':
          description: Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: AUTHENTICATION_REQUIRED
                  message: Invalid or expired JWT token
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12346
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: FORBIDDEN
                  message: Insufficient permissions to access this resource
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12349
        '404':
          description: Incident Report not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: NOT_FOUND
                  message: Incident Report with ID '64f8a1b23d4e5f6a7b8c9d0e' not found
                  details:
                    field: id
                    provided: 64f8a1b23d4e5f6a7b8c9d0e
                    expected: Valid incident report ID
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12348
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12347
      security:
        - bearer: []
      summary: Get incident report by ID
      tags:
        - Modules / Incident Reports
  /api/goals:
    get:
      description: >

        <p>Retrieves care goals with objectives, progress tracking, action
        plans, success measurements, and review history.</p>

        <p><strong>Filters:</strong></p>

        <ul>
          <li><code>homeId</code> - Filter by specific care home</li>
          <li><code>residentId</code> - Filter by specific resident</li>
          <li><code>startDate</code>, <code>endDate</code> - Date range filtering</li>
          <li><code>page</code>, <code>limit</code> - Pagination controls</li>
        </ul>
      operationId: getGoals
      parameters:
        - name: startDate
          required: false
          in: query
          description: Start date for filtering (inclusive)
          schema:
            format: date
            example: '2026-01-01'
            type: string
        - name: endDate
          required: false
          in: query
          description: End date for filtering (inclusive)
          schema:
            format: date
            example: '2026-12-31'
            type: string
        - name: page
          required: false
          in: query
          description: Page number (1-based)
          schema:
            minimum: 1
            default: 1
            example: 1
            type: number
        - name: limit
          required: false
          in: query
          description: Number of records per page
          schema:
            minimum: 1
            maximum: 100
            default: 10
            example: 10
            type: number
        - name: homeId
          required: false
          in: query
          description: Filter by home ID
          schema:
            example: home-123-abc
            type: string
        - name: residentId
          required: false
          in: query
          description: Filter by resident ID
          schema:
            example: resident-456-def
            type: string
        - name: dateField
          required: false
          in: query
          description: Date field to filter on
          schema:
            default: created_on
            example: created_on
            type: string
            enum:
              - created_on
              - edited_on
              - start_date
              - end_date
              - ingested_on
      responses:
        '200':
          description: Successfully retrieved records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoalResponseDto'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: Invalid query parameters
                  details:
                    field: startDate
                    provided: invalid-date
                    expected: ISO 8601 format (YYYY-MM-DD)
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12345
        '401':
          description: Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: AUTHENTICATION_REQUIRED
                  message: Invalid or expired JWT token
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12346
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: FORBIDDEN
                  message: Insufficient permissions to access this resource
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12349
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12347
      security:
        - bearer: []
      summary: Get goals
      tags:
        - Modules / Goals
  /api/goals/{id}:
    get:
      description: >

        <p>Retrieves complete goal details including objectives, progress
        history, action plans, logs, and success measurements.</p>
      operationId: getGoalById
      parameters:
        - name: id
          required: true
          in: path
          description: Unique identifier of the goal
          schema:
            example: 64f8a1b23d4e5f6a7b8c9d0e
            type: string
      responses:
        '200':
          description: Successfully retrieved goal
          content:
            application/json:
              schema:
                example:
                  id: 6968bf21c441cf6fb4ac9a3e
                  home:
                    id: home-123-abc
                    name: Sunrise Care Home
                  resident:
                    id: resident_id_123
                    name:
                      first: John
                      last: Doe
                      full: John Doe
                  createdBy:
                    id: user_id_789
                    name:
                      first: Sarah
                      last: Manager
                      full: Sarah Manager
                  editedBy:
                    id: user_id_790
                    name:
                      first: Jane
                      last: Smith
                      full: Jane Smith
                  logs:
                    - 6968bf21c441cf6fb4ac9a3f
                    - 696f874462d69cb149439f25
                  title: Improve Mobility
                  seenBy: []
                  status: notStarted
                  actions: []
                  endDate: '2026-06-30T00:00:00.000Z'
                  editedOn: '2026-01-23T14:18:42.514Z'
                  createdOn: '2026-01-15T10:30:00.000Z'
                  startDate: '2026-01-15T00:00:00.000Z'
                  importance: 8
                  description: Increase independent walking distance to 50 meters
                  nextReviewDate: '2026-03-30T00:00:00.000Z'
                  progressHistory:
                    - date: '2026-01-15T10:19:13.900Z'
                      progress: 0
                  successMeasurement: Able to walk 50 meters independently
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: Invalid query parameters
                  details:
                    field: startDate
                    provided: invalid-date
                    expected: ISO 8601 format (YYYY-MM-DD)
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12345
        '401':
          description: Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: AUTHENTICATION_REQUIRED
                  message: Invalid or expired JWT token
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12346
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: FORBIDDEN
                  message: Insufficient permissions to access this resource
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12349
        '404':
          description: Goal not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: NOT_FOUND
                  message: Goal with ID '64f8a1b23d4e5f6a7b8c9d0e' not found
                  details:
                    field: id
                    provided: 64f8a1b23d4e5f6a7b8c9d0e
                    expected: Valid goal ID
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12348
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12347
      security:
        - bearer: []
      summary: Get goal by ID
      tags:
        - Modules / Goals
  /api/risk-assessments:
    get:
      description: >

        <p>Retrieves risk assessments with safety evaluations, hazard
        identification, risk scores, and mitigation strategies.</p>

        <p><strong>Filters:</strong></p>

        <ul>
          <li><code>homeId</code> - Filter by specific care home</li>
          <li><code>residentId</code> - Filter by specific resident</li>
          <li><code>startDate</code>, <code>endDate</code> - Date range filtering</li>
          <li><code>page</code>, <code>limit</code> - Pagination controls</li>
        </ul>
      operationId: getRiskAssessments
      parameters:
        - name: startDate
          required: false
          in: query
          description: Start date for filtering (inclusive)
          schema:
            format: date
            example: '2026-01-01'
            type: string
        - name: endDate
          required: false
          in: query
          description: End date for filtering (inclusive)
          schema:
            format: date
            example: '2026-12-31'
            type: string
        - name: page
          required: false
          in: query
          description: Page number (1-based)
          schema:
            minimum: 1
            default: 1
            example: 1
            type: number
        - name: limit
          required: false
          in: query
          description: Number of records per page
          schema:
            minimum: 1
            maximum: 100
            default: 10
            example: 10
            type: number
        - name: homeId
          required: false
          in: query
          description: Filter by home ID
          schema:
            example: home-123-abc
            type: string
        - name: residentId
          required: false
          in: query
          description: Filter by resident ID
          schema:
            example: resident-456-def
            type: string
        - name: dateField
          required: false
          in: query
          description: Date field to filter on
          schema:
            default: created_on
            example: created_on
            type: string
            enum:
              - created_on
              - reviewed_on
              - ingested_on
      responses:
        '200':
          description: Successfully retrieved records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiskAssessmentResponseDto'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: Invalid query parameters
                  details:
                    field: startDate
                    provided: invalid-date
                    expected: ISO 8601 format (YYYY-MM-DD)
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12345
        '401':
          description: Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: AUTHENTICATION_REQUIRED
                  message: Invalid or expired JWT token
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12346
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: FORBIDDEN
                  message: Insufficient permissions to access this resource
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12349
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12347
      security:
        - bearer: []
      summary: Get risk assessments
      tags:
        - Modules / Risk Assessments
  /api/risk-assessments/{id}:
    get:
      description: >

        <p>Retrieves complete risk assessment details including form data, risk
        scores, review history, and assessor information.</p>
      operationId: getRiskAssessmentById
      parameters:
        - name: id
          required: true
          in: path
          description: Unique identifier of the risk assessment
          schema:
            example: 64f8a1b23d4e5f6a7b8c9d0e
            type: string
      responses:
        '200':
          description: Successfully retrieved risk assessment
          content:
            application/json:
              schema:
                example:
                  id: 696f910b62d69cb14944bd29
                  form:
                    id: 6960cb5add702a0011af4ce2
                    name: ''
                    formFields: []
                  home:
                    id: home-123-abc
                    name: Sunrise Care Home
                  resident:
                    id: resident_id_123
                    name:
                      first: John
                      last: Doe
                      full: John Doe
                    preferredName: Johnny
                  createdBy:
                    id: user_id_789
                    name:
                      first: Sarah
                      last: Manager
                      full: Sarah Manager
                  seenBy: []
                  archived: false
                  createdOn: '2026-01-20T14:28:27.400Z'
                  riskLevel: high
                  riskScore: 12
                  incomplete: false
                  reviewedOn: '2026-01-20T14:28:27.401Z'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: Invalid query parameters
                  details:
                    field: startDate
                    provided: invalid-date
                    expected: ISO 8601 format (YYYY-MM-DD)
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12345
        '401':
          description: Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: AUTHENTICATION_REQUIRED
                  message: Invalid or expired JWT token
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12346
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: FORBIDDEN
                  message: Insufficient permissions to access this resource
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12349
        '404':
          description: Risk Assessment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: NOT_FOUND
                  message: Risk Assessment with ID '64f8a1b23d4e5f6a7b8c9d0e' not found
                  details:
                    field: id
                    provided: 64f8a1b23d4e5f6a7b8c9d0e
                    expected: Valid risk assessment ID
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12348
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12347
      security:
        - bearer: []
      summary: Get risk assessment by ID
      tags:
        - Modules / Risk Assessments
  /api/logs:
    get:
      description: >

        <p>Retrieves logs (daily care notes) logged by staff members about
        residents' care, activities, and observations.</p>

        <p><strong>Filters:</strong></p>

        <ul>
          <li><code>homeId</code> - Filter by specific care home</li>
          <li><code>residentId</code> - Filter by specific resident</li>
          <li><code>categoryId</code> - Filter by log category (e.g., Meals & Nutrition)</li>
          <li><code>itemId</code> - Filter by log category item (e.g., Breakfast)</li>
          <li><code>loggedById</code> - Filter by user who logged the entry</li>
          <li><code>startDate</code>, <code>endDate</code> - Date range filtering</li>
          <li><code>dateField</code> - Date field to filter on (default: timeLogged)</li>
          <li><code>page</code>, <code>limit</code> - Pagination controls (default: page=1, limit=10, max=100)</li>
        </ul>

        <p><strong>Note:</strong> Deleted logs are automatically excluded from
        results.</p>
      operationId: getLogs
      parameters:
        - name: startDate
          required: false
          in: query
          description: Start date for filtering (inclusive)
          schema:
            format: date
            example: '2026-01-01'
            type: string
        - name: endDate
          required: false
          in: query
          description: End date for filtering (inclusive)
          schema:
            format: date
            example: '2026-12-31'
            type: string
        - name: page
          required: false
          in: query
          description: Page number (1-based)
          schema:
            minimum: 1
            default: 1
            example: 1
            type: number
        - name: limit
          required: false
          in: query
          description: Number of records per page
          schema:
            minimum: 1
            maximum: 100
            default: 10
            example: 10
            type: number
        - name: homeId
          required: false
          in: query
          description: Filter by home ID
          schema:
            example: home-123-abc
            type: string
        - name: residentId
          required: false
          in: query
          description: Filter by resident ID
          schema:
            example: 63299b624e4c26570fe21e75
            type: string
        - name: categoryId
          required: false
          in: query
          description: Filter by log category ID
          schema:
            example: 5f155c4ac49007031a671d4f
            type: string
        - name: itemId
          required: false
          in: query
          description: Filter by log category item ID
          schema:
            example: 5f155c4ac49007031a671d50
            type: string
        - name: loggedById
          required: false
          in: query
          description: Filter by user who logged (loggedBy)
          schema:
            example: 68ef4775c1e051de495b175a
            type: string
        - name: dateField
          required: false
          in: query
          description: Date field to filter on (only timeLogged supported)
          schema:
            default: timeLogged
            example: timeLogged
            type: string
            enum:
              - timeLogged
      responses:
        '200':
          description: Successfully retrieved records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogResponseDto'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: Invalid query parameters
                  details:
                    field: startDate
                    provided: invalid-date
                    expected: ISO 8601 format (YYYY-MM-DD)
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12345
        '401':
          description: Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: AUTHENTICATION_REQUIRED
                  message: Invalid or expired JWT token
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12346
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: FORBIDDEN
                  message: Insufficient permissions to access this resource
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12349
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12347
      security:
        - bearer: []
      summary: Get logs (daily care notes)
      tags:
        - Modules / Logs
  /api/logs/{id}:
    get:
      description: >

        <p>Retrieves complete log information including populated references for
        home, resident, loggedBy, editedBy, category, and item.</p>

        <p>Logs represent daily care notes and observations logged by staff
        members.</p>
      operationId: getLogById
      parameters:
        - name: id
          required: true
          in: path
          description: Unique identifier of the log
          schema:
            example: 64f8a1b23d4e5f6a7b8c9d0e
            type: string
      responses:
        '200':
          description: Successfully retrieved log
          content:
            application/json:
              schema:
                example:
                  id: 6980bf40b0d86defd672b8a1
                  title: Resident had a good breakfast
                  type: log
                  timeLogged: '2026-02-02T15:14:02.272Z'
                  originalTimeLog: '2026-02-02T15:14:08.625Z'
                  description: >-
                    Ate all food, engaged in conversation with other residents.
                    No assistance required.
                  location: Dining Room
                  deleted: false
                  home:
                    id: 66e2aeef14dce156439010d5
                    name: Sunrise Care Home
                  resident:
                    id: 69613fc010eecc5386f987ae
                    name:
                      first: Margaret
                      last: Thompson
                      full: Margaret Thompson
                  loggedBy:
                    id: 68406c31e55ca6b6d2262f56
                    name:
                      first: Jane
                      last: Smith
                      full: Jane Smith
                  editedBy:
                    id: 68ef4775c1e051de495b175a
                    name:
                      first: Sarah
                      last: Manager
                      full: Sarah Manager
                  category:
                    id: 5e867702b349f776c8d48c34
                    name: Food & Drink
                  item:
                    id: 68cae49a5df0b900121771f2
                    name: Breakfast
                  editedAt: '2026-02-02T15:20:00.000Z'
                  revisions: 0
                  picture1: >-
                    https://lmc-care-uploads.s3.eu-west-2.amazonaws.com/photos/home/logs/example-home-id/photo1.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=EXAMPLE%2F20260202%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20260202T151402Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=examplesignature
                  picture2: null
                  picture3: null
                  videoFile: null
                  videoThumbnail: null
                  hidden: false
                  isNextHandover: false
                  revoked: false
                  revokedAt: null
                  nonEditable: false
                  amount1: 250
                  amount2: 0
                  amountType: ml
                  stockQuantityType: volume
                  latitude: 51.5
                  longitude: -1.5
                  accuracy: 10
                  itemSublevel: Lunch
                  doneBySu: false
                  response:
                    questions:
                      - key: mood
                        label: Mood
                        value: Happy
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: Invalid query parameters
                  details:
                    field: startDate
                    provided: invalid-date
                    expected: ISO 8601 format (YYYY-MM-DD)
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12345
        '401':
          description: Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: AUTHENTICATION_REQUIRED
                  message: Invalid or expired JWT token
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12346
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: FORBIDDEN
                  message: Insufficient permissions to access this resource
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12349
        '404':
          description: Log not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: NOT_FOUND
                  message: Log with ID '64f8a1b23d4e5f6a7b8c9d0e' not found
                  details:
                    field: id
                    provided: 64f8a1b23d4e5f6a7b8c9d0e
                    expected: Valid log ID
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12348
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12347
      security:
        - bearer: []
      summary: Get log by ID
      tags:
        - Modules / Logs
  /api/logcategories:
    get:
      description: >

        <p>Retrieves log categories used to classify daily care notes and
        observations.</p>

        <p><strong>Examples:</strong> Meals & Nutrition, Personal Care,
        Activities, Health & Wellbeing, Medication</p>

        <p><strong>Filters:</strong></p>

        <ul>
          <li><code>page</code>, <code>limit</code> - Pagination controls (default: page=1, limit=10, max=100)</li>
        </ul>

        <p><strong>Note:</strong> This endpoint does not require authentication.
        Log categories are public reference data.</p>
      operationId: getLogCategories
      parameters:
        - name: page
          required: false
          in: query
          description: Page number (1-based)
          schema:
            minimum: 1
            default: 1
            example: 1
            type: number
        - name: limit
          required: false
          in: query
          description: Number of records per page
          schema:
            minimum: 1
            maximum: 100
            default: 10
            example: 10
            type: number
      responses:
        '200':
          description: List of log categories
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogCategoryResponseDto'
      summary: Get log categories
      tags:
        - Modules / Log Categories
  /api/logcategories/{id}:
    get:
      description: >

        <p>Retrieves a log category with its id, name, and color.</p>

        <p>Log categories are used to organize and classify daily care logs.</p>

        <p><strong>Note:</strong> This endpoint does not require
        authentication.</p>
      operationId: getLogCategoryById
      parameters:
        - name: id
          required: true
          in: path
          description: Unique identifier of the logcategory
          schema:
            example: 64f8a1b23d4e5f6a7b8c9d0e
            type: string
      responses:
        '200':
          description: Log category details
          content:
            application/json:
              schema:
                example:
                  id: 5f213e77cdd809d04ba664be
                  name: Body Maps
                  color: '#9966FB'
      summary: Get log category by ID
      tags:
        - Modules / Log Categories
  /api/logcategoryitems:
    get:
      description: >

        <p>Retrieves log category items representing specific activities or
        observations within a log category.</p>

        <p><strong>Examples:</strong> Breakfast (under Meals & Nutrition),
        Shower (under Personal Care), Walk in Garden (under Activities)</p>

        <p><strong>Filters:</strong></p>

        <ul>
          <li><code>page</code>, <code>limit</code> - Pagination controls (default: page=1, limit=10, max=100)</li>
        </ul>

        <p><strong>Note:</strong> This endpoint does not require authentication.
        Items are sorted by <code>order</code> for proper UI display.</p>
      operationId: getLogCategoryItems
      parameters:
        - name: page
          required: false
          in: query
          description: Page number (1-based)
          schema:
            minimum: 1
            default: 1
            example: 1
            type: number
        - name: limit
          required: false
          in: query
          description: Number of records per page
          schema:
            minimum: 1
            maximum: 100
            default: 10
            example: 10
            type: number
      responses:
        '200':
          description: List of log category items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogCategoryItemResponseDto'
      summary: Get log category items
      tags:
        - Modules / Log Category Items
  /api/logcategoryitems/{id}:
    get:
      description: >

        <p>Retrieves a log category item with its id, name, and parent category
        id.</p>

        <p>Log category items represent specific activities or observations that
        can be logged by staff members.</p>

        <p><strong>Note:</strong> This endpoint does not require
        authentication.</p>
      operationId: getLogCategoryItemById
      parameters:
        - name: id
          required: true
          in: path
          description: Unique identifier of the logcategoryitem
          schema:
            example: 64f8a1b23d4e5f6a7b8c9d0e
            type: string
      responses:
        '200':
          description: Log category item details
          content:
            application/json:
              schema:
                example:
                  id: 5e81db67b1b4e673bc2bb8cc
                  name: Catheter
                  category: 5e867702b349f776c8d48c2f
      summary: Get log category item by ID
      tags:
        - Modules / Log Category Items
  /api/documents:
    get:
      description: >

        <p>Retrieves resident-specific documents including medical records,
        assessments, care plans, and other resident documentation.</p>

        <p><strong>Filters:</strong></p>

        <ul>
          <li><code>homeId</code> - Filter by specific care home</li>
          <li><code>residentId</code> - Filter by specific resident</li>
          <li><code>categoryId</code> - Filter by document category</li>
          <li><code>startDate</code>, <code>endDate</code> - Date range filtering</li>
          <li><code>dateField</code> - Date field to filter on (default: createdAt)</li>
          <li><code>page</code>, <code>limit</code> - Pagination controls (default: page=1, limit=10, max=100)</li>
        </ul>
      operationId: getDocuments
      parameters:
        - name: startDate
          required: false
          in: query
          description: Start date for filtering (inclusive)
          schema:
            format: date
            example: '2026-01-01'
            type: string
        - name: endDate
          required: false
          in: query
          description: End date for filtering (inclusive)
          schema:
            format: date
            example: '2026-12-31'
            type: string
        - name: page
          required: false
          in: query
          description: Page number (1-based)
          schema:
            minimum: 1
            default: 1
            example: 1
            type: number
        - name: limit
          required: false
          in: query
          description: Number of records per page
          schema:
            minimum: 1
            maximum: 100
            default: 10
            example: 10
            type: number
        - name: homeId
          required: false
          in: query
          description: Filter by home ID
          schema:
            example: home-123-abc
            type: string
        - name: residentId
          required: false
          in: query
          description: Filter by resident ID
          schema:
            example: 63299b624e4c26570fe21e75
            type: string
        - name: categoryId
          required: false
          in: query
          description: Filter by document category ID
          schema:
            example: 5f155c4ac49007031a671d4f
            type: string
        - name: dateField
          required: false
          in: query
          description: Date field to filter on (only createdAt supported)
          schema:
            default: createdAt
            example: createdAt
            type: string
            enum:
              - createdAt
      responses:
        '200':
          description: Successfully retrieved records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentResponseDto'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: Invalid query parameters
                  details:
                    field: startDate
                    provided: invalid-date
                    expected: ISO 8601 format (YYYY-MM-DD)
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12345
        '401':
          description: Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: AUTHENTICATION_REQUIRED
                  message: Invalid or expired JWT token
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12346
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: FORBIDDEN
                  message: Insufficient permissions to access this resource
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12349
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12347
      security:
        - bearer: []
      summary: Get documents (resident documents)
      tags:
        - Modules / Documents
  /api/documents/{id}:
    get:
      description: >

        <p>Retrieves complete document information including file details,
        category, resident, and home references.</p>

        <p>Documents represent files uploaded for specific residents, including
        PDFs and other file types.</p>
      operationId: getDocumentById
      parameters:
        - name: id
          required: true
          in: path
          description: Unique identifier of the document
          schema:
            example: 64f8a1b23d4e5f6a7b8c9d0e
            type: string
      responses:
        '200':
          description: Successfully retrieved document
          content:
            application/json:
              schema:
                example:
                  id: 6977686fc18f55207654e609
                  name: Medical Assessment - January 2026
                  createdAt: '2026-01-26T13:13:19.529Z'
                  home:
                    id: 66e2aeef14dce156439010d5
                    name: Sunrise Care Home
                  resident:
                    id: 69613fc010eecc5386f987ae
                    name:
                      first: Margaret
                      last: Thompson
                      full: Margaret Thompson
                  category:
                    id: 5f155c4ac49007031a671d4f
                    name: Care Plans
                  pdf: >-
                    https://lmc-care-uploads.s3.eu-west-2.amazonaws.com/docs/home/documents/example-home-id/document-file.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=EXAMPLE%2F20260126%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20260126T131319Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=examplesignature
                  originalFile: Medical_Assessment_Jan2026.pdf
                  attachedToCarePlan: true
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: Invalid query parameters
                  details:
                    field: startDate
                    provided: invalid-date
                    expected: ISO 8601 format (YYYY-MM-DD)
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12345
        '401':
          description: Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: AUTHENTICATION_REQUIRED
                  message: Invalid or expired JWT token
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12346
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: FORBIDDEN
                  message: Insufficient permissions to access this resource
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12349
        '404':
          description: Document not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: NOT_FOUND
                  message: Document with ID '64f8a1b23d4e5f6a7b8c9d0e' not found
                  details:
                    field: id
                    provided: 64f8a1b23d4e5f6a7b8c9d0e
                    expected: Valid document ID
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12348
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12347
      security:
        - bearer: []
      summary: Get document by ID
      tags:
        - Modules / Documents
  /api/home-documents:
    get:
      description: >

        <p>Retrieves home-scoped documents including policies, procedures,
        licenses, training materials, and other home-level documentation.</p>

        <p><strong>Filters:</strong></p>

        <ul>
          <li><code>homeId</code> - Filter by specific care home</li>
          <li><code>categoryId</code> - Filter by home document category</li>
          <li><code>startDate</code>, <code>endDate</code> - Date range filtering</li>
          <li><code>dateField</code> - Date field to filter on (default: createdAt)</li>
          <li><code>page</code>, <code>limit</code> - Pagination controls (default: page=1, limit=10, max=100)</li>
        </ul>
      operationId: getHomeDocuments
      parameters:
        - name: startDate
          required: false
          in: query
          description: Start date for filtering (inclusive)
          schema:
            format: date
            example: '2026-01-01'
            type: string
        - name: endDate
          required: false
          in: query
          description: End date for filtering (inclusive)
          schema:
            format: date
            example: '2026-12-31'
            type: string
        - name: page
          required: false
          in: query
          description: Page number (1-based)
          schema:
            minimum: 1
            default: 1
            example: 1
            type: number
        - name: limit
          required: false
          in: query
          description: Number of records per page
          schema:
            minimum: 1
            maximum: 100
            default: 10
            example: 10
            type: number
        - name: homeId
          required: false
          in: query
          description: Filter by home ID
          schema:
            example: home-123-abc
            type: string
        - name: residentId
          required: false
          in: query
          description: Filter by resident ID
          schema:
            example: resident-456-def
            type: string
        - name: categoryId
          required: false
          in: query
          description: Filter by home document category ID
          schema:
            example: 5f155c4ac49007031a671d4f
            type: string
        - name: dateField
          required: false
          in: query
          description: Date field to filter on (only createdAt supported)
          schema:
            default: createdAt
            example: createdAt
            type: string
            enum:
              - createdAt
      responses:
        '200':
          description: Successfully retrieved records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HomeDocumentResponseDto'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: Invalid query parameters
                  details:
                    field: startDate
                    provided: invalid-date
                    expected: ISO 8601 format (YYYY-MM-DD)
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12345
        '401':
          description: Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: AUTHENTICATION_REQUIRED
                  message: Invalid or expired JWT token
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12346
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: FORBIDDEN
                  message: Insufficient permissions to access this resource
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12349
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12347
      security:
        - bearer: []
      summary: Get home documents (home-scoped documents)
      tags:
        - Modules / Home Documents
  /api/home-documents/{id}:
    get:
      description: >

        <p>Retrieves complete home document information including file details,
        category, and home references.</p>

        <p>Home documents are scoped to care homes rather than individual
        residents, including policies, procedures, and licenses.</p>
      operationId: getHomeDocumentById
      parameters:
        - name: id
          required: true
          in: path
          description: Unique identifier of the home document
          schema:
            example: 64f8a1b23d4e5f6a7b8c9d0e
            type: string
      responses:
        '200':
          description: Successfully retrieved homedocument
          content:
            application/json:
              schema:
                example:
                  id: 6915ffc2e924f18fb5af8879
                  name: Fire Safety Policy - 2026
                  createdAt: '2026-11-13T15:56:50.600Z'
                  home:
                    id: 66e2aeef14dce156439010d5
                    name: Sunrise Care Home
                  category:
                    id: 5f155c4ac49007031a671d4f
                    name: General
                  pdf: >-
                    https://lmc-care-uploads.s3.eu-west-2.amazonaws.com/docs/home/homeDocuments/example-home-id/document-file.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=EXAMPLE%2F20260113%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20260113T155650Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=examplesignature
                  originalFile: Fire_Safety_Policy_2026.pdf
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: Invalid query parameters
                  details:
                    field: startDate
                    provided: invalid-date
                    expected: ISO 8601 format (YYYY-MM-DD)
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12345
        '401':
          description: Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: AUTHENTICATION_REQUIRED
                  message: Invalid or expired JWT token
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12346
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: FORBIDDEN
                  message: Insufficient permissions to access this resource
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12349
        '404':
          description: HomeDocument not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: NOT_FOUND
                  message: HomeDocument with ID '64f8a1b23d4e5f6a7b8c9d0e' not found
                  details:
                    field: id
                    provided: 64f8a1b23d4e5f6a7b8c9d0e
                    expected: Valid homedocument ID
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12348
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12347
      security:
        - bearer: []
      summary: Get home document by ID
      tags:
        - Modules / Home Documents
  /api/devices:
    get:
      description: >

        <p>Retrieves devices (tablets, phones, laptops) registered to care homes
        for logging activities.</p>

        <p>All ObjectId reference fields are populated one level deep with
        <code>{ id, name }</code>.</p>

        <p>The <code>homes</code> array in the response is filtered to only
        include entries for homes the API key has access to.</p>

        <p><strong>Filters:</strong></p>

        <ul>
          <li><code>type</code> - Filter by device type (tablet, phone, laptop)</li>
          <li><code>deviceStatus</code> - Filter by home assignment status (pending, approved, blocked)</li>
          <li><code>startDate</code>, <code>endDate</code> - Date range filtering on createdOn</li>
          <li><code>page</code>, <code>limit</code> - Pagination controls (default: page=1, limit=10, max=100)</li>
        </ul>
      operationId: getDevices
      parameters:
        - name: startDate
          required: false
          in: query
          description: Start date for filtering (inclusive)
          schema:
            format: date
            example: '2026-01-01'
            type: string
        - name: endDate
          required: false
          in: query
          description: End date for filtering (inclusive)
          schema:
            format: date
            example: '2026-12-31'
            type: string
        - name: page
          required: false
          in: query
          description: Page number (1-based)
          schema:
            minimum: 1
            default: 1
            example: 1
            type: number
        - name: limit
          required: false
          in: query
          description: Number of records per page
          schema:
            minimum: 1
            maximum: 100
            default: 10
            example: 10
            type: number
        - name: type
          required: false
          in: query
          description: Filter by device type
          schema:
            example: tablet
            type: string
            enum:
              - tablet
              - phone
              - laptop
        - name: deviceStatus
          required: false
          in: query
          description: >-
            Filter by device home assignment status. If not provided, returns
            devices with any status.
          schema:
            example: approved
            type: string
            enum:
              - pending
              - approved
              - blocked
      responses:
        '200':
          description: Successfully retrieved records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceResponseDto'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: Invalid query parameters
                  details:
                    field: startDate
                    provided: invalid-date
                    expected: ISO 8601 format (YYYY-MM-DD)
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12345
        '401':
          description: Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: AUTHENTICATION_REQUIRED
                  message: Invalid or expired JWT token
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12346
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: FORBIDDEN
                  message: Insufficient permissions to access this resource
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12349
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12347
      security:
        - bearer: []
      summary: Get devices
      tags:
        - Modules / Devices
  /api/devices/{id}:
    get:
      description: >

        <p>Retrieves complete device information including populated user
        references, home assignments with status, and audit fields.</p>

        <p>The <code>homes</code> array is filtered to only include entries for
        homes the API key has access to. FCM (push notification) fields are
        excluded from the response.</p>
      operationId: getDeviceById
      parameters:
        - name: id
          required: true
          in: path
          description: Unique identifier of the device
          schema:
            example: 64f8a1b23d4e5f6a7b8c9d0e
            type: string
      responses:
        '200':
          description: Successfully retrieved device
          content:
            application/json:
              schema:
                example:
                  id: 64f8a1b23d4e5f6a7b8c9d0e
                  name: Reception Tablet
                  uuid: 550e8400-e29b-41d4-a716-446655440000
                  version: 4.2.1
                  model: iPad Pro 12.9
                  type: tablet
                  users:
                    - id: 64f8a1b23d4e5f6a7b8c9d01
                      name:
                        first: Jane
                        last: Smith
                        full: Jane Smith
                  homes:
                    - home:
                        id: 64f8a1b23d4e5f6a7b8c9d02
                        name: Sunrise Care Home
                      status: approved
                  lastUsedBy:
                    id: 64f8a1b23d4e5f6a7b8c9d01
                    name:
                      first: Jane
                      last: Smith
                      full: Jane Smith
                  lastUsedOn: '2026-03-07T14:30:00.000Z'
                  createdBy:
                    id: 64f8a1b23d4e5f6a7b8c9d03
                    name:
                      first: Admin
                      last: User
                      full: Admin User
                  createdOn: '2026-01-15T10:00:00.000Z'
                  editedBy:
                    id: 64f8a1b23d4e5f6a7b8c9d01
                    name:
                      first: Jane
                      last: Smith
                      full: Jane Smith
                  editedOn: '2026-03-07T14:30:00.000Z'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: Invalid query parameters
                  details:
                    field: startDate
                    provided: invalid-date
                    expected: ISO 8601 format (YYYY-MM-DD)
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12345
        '401':
          description: Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: AUTHENTICATION_REQUIRED
                  message: Invalid or expired JWT token
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12346
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: FORBIDDEN
                  message: Insufficient permissions to access this resource
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12349
        '404':
          description: Device not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: NOT_FOUND
                  message: Device with ID '64f8a1b23d4e5f6a7b8c9d0e' not found
                  details:
                    field: id
                    provided: 64f8a1b23d4e5f6a7b8c9d0e
                    expected: Valid device ID
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12348
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
              example:
                error:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred
                  timestamp: '2026-12-11T10:30:00Z'
                  correlationId: req_12347
      security:
        - bearer: []
      summary: Get device by ID
      tags:
        - Modules / Devices
info:
  title: Log my Care Open API
  description: >-
    API for accessing Log my Care data. Most endpoints are read-only
    (<code>GET</code>); the Residents endpoint additionally supports creating
    and updating records (<code>POST</code>/<code>PUT</code>). Authenticate by
    exchanging your API key for a JWT token via <code>POST
    /openapi/auth/token/exchange</code>, then include the token in the
    <code>Authorization: Bearer</code> header.


    <h2>Authentication</h2>


    <p><strong>Token Exchange (Required)</strong>: Exchange the API key for a
    short-lived JWT token (15 minutes) using <code>POST
    /openapi/auth/token/exchange</code>. This provides enhanced security by
    minimizing API key exposure.</p>


    <p>All authenticated endpoints require a valid JWT token in the
    <code>Authorization: Bearer</code> header.</p>


    <h2>Available Endpoints</h2>


    <h3>Health & Status</h3>

    <ul>
      <li><code>GET /health</code> - System health check (no authentication required)</li>
      <li><code>GET /openapi/health</code> - Alternative health check path (legacy compatibility)</li>
    </ul>


    <h3>Residents</h3>

    <ul>
      <li><code>GET /openapi/api/residents</code> - List all residents with filtering and pagination</li>
      <li><code>GET /openapi/api/residents/:id</code> - Get specific resident by ID</li>
      <li><code>POST /openapi/api/residents</code> - Create a resident</li>
      <li><code>PUT /openapi/api/residents/:id</code> - Update a resident</li>
      <li>Filters: <code>homeId</code>, <code>residentId</code>, <code>startDate</code>, <code>endDate</code>, <code>dateField</code>, <code>page</code>, <code>limit</code></li>
    </ul>


    <h3>Care Plans</h3>

    <ul>
      <li><code>GET /openapi/api/careplans</code> - List all care plans with filtering</li>
      <li><code>GET /openapi/api/careplans/:id</code> - Get specific care plan by ID</li>
      <li>Filters: <code>homeId</code>, <code>residentId</code>, <code>carePlanId</code>, <code>startDate</code>, <code>endDate</code>, <code>dateField</code>, <code>page</code>, <code>limit</code></li>
    </ul>


    <h3>Goals</h3>

    <ul>
      <li><code>GET /openapi/api/goals</code> - List all goals with filtering</li>
      <li><code>GET /openapi/api/goals/:id</code> - Get specific goal by ID</li>
      <li>Filters: <code>homeId</code>, <code>residentId</code>, <code>startDate</code>, <code>endDate</code>, <code>dateField</code>, <code>page</code>, <code>limit</code></li>
    </ul>


    <h3>Incident Reports</h3>

    <ul>
      <li><code>GET /openapi/api/incident-reports</code> - List all incident reports</li>
      <li><code>GET /openapi/api/incident-reports/:id</code> - Get specific incident report by ID</li>
      <li>Filters: <code>homeId</code>, <code>residentId</code>, <code>severity</code>, <code>startDate</code>, <code>endDate</code>, <code>dateField</code>, <code>page</code>, <code>limit</code></li>
    </ul>


    <h3>Risk Assessments</h3>

    <ul>
      <li><code>GET /openapi/api/risk-assessments</code> - List all risk assessments</li>
      <li><code>GET /openapi/api/risk-assessments/:id</code> - Get specific risk assessment by ID</li>
      <li>Filters: <code>homeId</code>, <code>residentId</code>, <code>startDate</code>, <code>endDate</code>, <code>dateField</code>, <code>page</code>, <code>limit</code></li>
    </ul>


    <h3>Homes</h3>

    <ul>
      <li><code>GET /openapi/api/homes</code> - List all care homes</li>
      <li><code>GET /openapi/api/homes/:id</code> - Get specific home by ID</li>
      <li>Filters: <code>page</code>, <code>limit</code></li>
    </ul>


    <h3>Users</h3>

    <ul>
      <li><code>GET /openapi/api/users</code> - List all users</li>
      <li><code>GET /openapi/api/users/:id</code> - Get specific user by ID</li>
      <li>Filters: <code>startDate</code>, <code>endDate</code>, <code>dateField</code>, <code>page</code>, <code>limit</code></li>
    </ul>


    <h3>Logs</h3>

    <ul>
      <li><code>GET /openapi/api/logs</code> - List all daily care logs</li>
      <li><code>GET /openapi/api/logs/:id</code> - Get specific log by ID</li>
      <li>Filters: <code>homeId</code>, <code>residentId</code>, <code>categoryId</code>, <code>itemId</code>, <code>loggedById</code>, <code>startDate</code>, <code>endDate</code>, <code>dateField</code>, <code>page</code>, <code>limit</code></li>
    </ul>


    <h3>Log Categories</h3>

    <ul>
      <li><code>GET /openapi/api/logcategories</code> - List all log categories (no authentication required)</li>
      <li><code>GET /openapi/api/logcategories/:id</code> - Get specific log category by ID (no authentication required)</li>
      <li>Filters: <code>page</code>, <code>limit</code></li>
    </ul>


    <h3>Log Category Items</h3>

    <ul>
      <li><code>GET /openapi/api/logcategoryitems</code> - List all log category items (no authentication required)</li>
      <li><code>GET /openapi/api/logcategoryitems/:id</code> - Get specific log category item by ID (no authentication required)</li>
      <li>Filters: <code>page</code>, <code>limit</code></li>
    </ul>


    <h3>Documents</h3>

    <ul>
      <li><code>GET /openapi/api/documents</code> - List all resident documents</li>
      <li><code>GET /openapi/api/documents/:id</code> - Get specific document by ID</li>
      <li>Filters: <code>homeId</code>, <code>residentId</code>, <code>categoryId</code>, <code>startDate</code>, <code>endDate</code>, <code>dateField</code>, <code>page</code>, <code>limit</code></li>
    </ul>


    <h3>Home Documents</h3>

    <ul>
      <li><code>GET /openapi/api/home-documents</code> - List all home-scoped documents</li>
      <li><code>GET /openapi/api/home-documents/:id</code> - Get specific home document by ID</li>
      <li>Filters: <code>homeId</code>, <code>categoryId</code>, <code>startDate</code>, <code>endDate</code>, <code>dateField</code>, <code>page</code>, <code>limit</code></li>
    </ul>


    <h3>Devices</h3>

    <ul>
      <li><code>GET /openapi/api/devices</code> - List all devices (tablets, phones, laptops)</li>
      <li><code>GET /openapi/api/devices/:id</code> - Get specific device by ID</li>
      <li>Filters: <code>type</code>, <code>deviceStatus</code>, <code>startDate</code>, <code>endDate</code>, <code>page</code>, <code>limit</code></li>
    </ul>


    <h2>Common Features</h2>


    <p><strong>Pagination</strong>: All list endpoints support <code>page</code>
    (default: 1) and <code>limit</code> (default: 10, max: 100) parameters.</p>


    <p><strong>Date Filtering</strong>: Many endpoints support
    <code>startDate</code>, <code>endDate</code>, and <code>dateField</code>
    parameters for filtering by date ranges.</p>


    <p><strong>Rate limits</strong>: 100 requests/minute per IP
    (unauthenticated), 1,000 requests/minute with JWT token authentication.</p>


    <p><strong>Security</strong>: All requests logged, input validated,
    parameterised queries, rate limiting enforced.</p>
  version: 1.108.0
  contact:
    name: API Support
    email: support@logmycare.co.uk
tags:
  - name: health
    description: Health check and system status
  - name: token-exchange
    description: API key authentication
  - name: Modules / Residents
    description: Resident records
  - name: Modules / Users
    description: User records
  - name: Modules / Care Plans
    description: Care plan records
  - name: Modules / Homes
    description: Care home records
  - name: Modules / Incident Reports
    description: Incident report records
  - name: Modules / Goals
    description: Goal records
  - name: Modules / Risk Assessments
    description: Risk assessment records
  - name: Modules / Logs
    description: Daily care log records
  - name: Modules / Log Categories
    description: Log category records
  - name: Modules / Log Category Items
    description: Log category item records
  - name: Modules / Documents
    description: Resident document records
  - name: Modules / Home Documents
    description: Home-scoped document records
  - name: Modules / Devices
    description: Device records
servers:
  - url: https://data.logmycare.co.uk/openapi
    description: API Server
components:
  securitySchemes:
    Bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: JWT token obtained from token exchange endpoint
  schemas:
    TokenExchangeRequestDto:
      type: object
      properties:
        grant_type:
          type: string
          description: Grant type for token exchange
          enum:
            - api_key_exchange
          example: api_key_exchange
        api_key:
          type: string
          description: >-
            API key to exchange for access token. The API key in MongoDB defines
            all permissions, scopes, and home access.
          example: sk_live_abcd1234...
          minLength: 8
      required:
        - grant_type
        - api_key
    TokenExchangeResponseDto:
      type: object
      properties:
        access_token:
          type: string
          description: Short-lived JWT access token
          example: eyJhbGciOiJIUzI1NiI...
        token_type:
          type: string
          description: Token type
          enum:
            - Bearer
          example: Bearer
        expires_in:
          type: number
          description: Token expiration time in seconds
          example: 900
        scope:
          description: Granted permissions/scope
          example:
            - residents:read
            - careplans:read
          type: array
          items:
            type: string
        issued_token_type:
          type: string
          description: Type of issued token
          example: urn:ietf:params:oauth:token-type:jwt
      required:
        - access_token
        - token_type
        - expires_in
        - scope
        - issued_token_type
    TokenExchangeErrorDto:
      type: object
      properties:
        error:
          type: string
          description: Error code
          example: invalid_request
        error_description:
          type: string
          description: Human-readable error description
          example: Invalid API key
        error_details:
          type: object
          description: Additional error details
          example:
            field: api_key
            code: invalid
      required:
        - error
        - error_description
    PaginationMetaDto:
      type: object
      properties:
        page:
          type: number
          description: Current page number
          example: 1
        limit:
          type: number
          description: Number of records per page
          example: 10
        total:
          description: >-
            Total number of records. Shows '10000+' when count exceeds 10,000
            for performance optimization.
          oneOf:
            - type: number
            - type: string
          example: 150
        totalPages:
          type: number
          description: Total number of pages
          example: 15
        hasNext:
          type: boolean
          description: Whether there is a next page
          example: true
        hasPrev:
          type: boolean
          description: Whether there is a previous page
          example: false
      required:
        - page
        - limit
        - total
        - totalPages
        - hasNext
        - hasPrev
    ResidentResponseDto:
      type: object
      properties:
        data:
          description: Array of residents
          example:
            - id: 69613fc010eecc5386f987ae
              name:
                first: Margaret
                last: Thompson
              email: margaret.thompson@example.com
              gender: female
              dateOfBirth: '1945-06-15T00:00:00.000Z'
              createdOn: '2026-01-15T09:30:00.000Z'
              admissionDate: '2026-01-10T00:00:00.000Z'
              preferredName: Maggie
              status: active
              statusChangedOn: '2026-01-20T10:00:00.000Z'
              isInactive: false
              home:
                id: 66e2aeef14dce156439010d5
                name: Sunrise Care Home
              location:
                roomName: Room 12
                unit: Oak Wing
                floor: '1'
              nhsNumber: 999 000 0001
              bloodType: O+
              allergies: Penicillin
              hasAllergies: true
              noKnownAllergies: false
              residentAllergies:
                - Penicillin
                - Latex
              medicalHistory: Hypertension, Type 2 diabetes
              height: 165cm
              gpCode: G1234567
              gpName: Dr. Sarah Williams
              gpEmail: sarah.williams@nhs.example.com
              gpTelephone: +44 1632 960123
              gpAddress:
                street1: 1 Example Lane
                suburb: Exampletown
                postcode: EX1 1CD
                country: United Kingdom
              gpSurgeryName: Example Medical Practice
              phones:
                - number: +44 7700 900123
                  type: mobile
              addresses:
                - street1: 45 Example Avenue
                  suburb: Exampletown
                  postcode: EX1 1EF
                  country: United Kingdom
                  isCurrent: true
                  isPrevious: false
              importantContacts:
                - name:
                    first: Robert
                    last: Thompson
                  relationship: Son
                  nextOfKin: true
                  lpa: true
                  phone: +44 7700 900456
                  email: robert.thompson@example.com
                  addresses:
                    - street1: 1 Example Street
                      suburb: Leeds
                      postcode: EX1 1EX
                      country: United Kingdom
              preferredContactMethod: noPreference
              religion: Christian
              ethnicity: White British
              nationality: British
              nationalities:
                - British
              languagesSpoken:
                - English
              maritalStatus: widowed
              birthplace: York
              sexualPreference: heterosexual
              carePackage:
                fundingSource: localAuthority
                fundingSourceNotes: Funded by York City Council
                fundingSourceOther: ''
              fundingSource: localAuthority
              fundingSourceNotes: Funded by York City Council
              fundingSourceOther: ''
              keyworkers:
                - 68406c31e55ca6b6d2262f56
              carerPreferences:
                gender: female
                language: English
              preferredDrink: Tea with milk
              preferredAdminRoute: oral
              dols:
                status: authorised
                startDate: '2026-02-01T00:00:00.000Z'
                endDate: '2026-08-01T00:00:00.000Z'
                reviewDate: '2026-05-01T00:00:00.000Z'
                applicationDate: '2026-01-15T00:00:00.000Z'
              dolsStartDate: '2026-02-01T00:00:00.000Z'
              dolsEndDate: '2026-08-01T00:00:00.000Z'
              dolsReviewDate: '2026-05-01T00:00:00.000Z'
              dolsApplicationDate: '2026-01-15T00:00:00.000Z'
              dnacpr:
                hasDnacpr: true
                details: DNACPR in place, reviewed by GP
                reviewDate: '2026-06-01T00:00:00.000Z'
                formPhysicalLocation: Front of care file
              dnacprDetails: DNACPR in place, reviewed by GP
              dnacprReviewDate: '2026-06-01T00:00:00.000Z'
              dnacprFormPhysicalLocation: Front of care file
              recentMustScore: '1'
              recentWaterlowScore: '12'
              recentDrinkConsumption: 1500ml
              hasChokingRisk: false
              prnMedsNote: Paracetamol PRN for pain
              nationalInsurance: QQ123456C
              summary: >-
                Margaret is a friendly resident who enjoys gardening and
                reading.
              otherIdentifiers:
                - type: localAuthorityRef
                  value: LA-2026-0042
              customId: example-resident-id-123
              ageYears: 80
          type: array
          items:
            type: object
        pagination:
          description: Pagination metadata
          allOf:
            - $ref: '#/components/schemas/PaginationMetaDto'
      required:
        - data
        - pagination
    ErrorDetailDto:
      type: object
      properties:
        field:
          type: string
          description: Field that caused the error
          example: startDate
        provided:
          type: string
          description: Value that was provided
          example: invalid-date
        expected:
          type: string
          description: Expected format or value
          example: ISO 8601 format (YYYY-MM-DD)
      required:
        - field
        - provided
        - expected
    ErrorDto:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: VALIDATION_ERROR
          enum:
            - AUTHENTICATION_REQUIRED
            - RATE_LIMIT_EXCEEDED
            - VALIDATION_ERROR
            - NOT_FOUND
            - DATABASE_ERROR
            - INTERNAL_ERROR
            - METHOD_NOT_ALLOWED
        message:
          type: string
          description: Error message
          example: Invalid date format
        details:
          description: Additional error details
          allOf:
            - $ref: '#/components/schemas/ErrorDetailDto'
        timestamp:
          type: string
          description: ISO 8601 timestamp of when the error occurred
          example: '2025-09-10T10:30:00Z'
        correlationId:
          type: string
          description: Correlation ID for tracking
          example: req_12345
      required:
        - code
        - message
        - timestamp
        - correlationId
    ErrorResponseDto:
      type: object
      properties:
        error:
          description: Error information
          allOf:
            - $ref: '#/components/schemas/ErrorDto'
      required:
        - error
    ResidentNameDto:
      type: object
      properties:
        first:
          type: string
          example: Jane
        last:
          type: string
          example: Smith
        full:
          type: string
          example: Jane Smith
      required:
        - first
        - last
    ExternalSourceDto:
      type: object
      properties:
        sourceName:
          type: string
          example: my-integration
          description: Name of the external system
        sourceId:
          type: string
          example: ext-12345
          description: Unique identifier in the external system
        sourceType:
          type: string
          example: api
          description: Type of the record in the external system
          enum:
            - api
            - import
            - integration
        externalCreatedAt:
          type: string
          example: '2024-01-15T09:30:00.000Z'
          description: When the record was created in the external system (ISO 8601)
        sourceRecordUrl:
          type: string
          example: https://app.example.com/residents/ext-12345
          description: URL to the record in the external system
        metadata:
          type: object
          example:
            region: north
            ward: A
          description: Additional metadata from the external system
      required:
        - sourceName
        - sourceId
        - sourceType
    CreateResidentDto:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/ResidentNameDto'
        home:
          type: string
          example: 507f1f77bcf86cd799439011
          description: Home ID
        dateOfBirth:
          type: string
          example: '1945-06-15'
          description: ISO 8601 date
        gender:
          type: string
          enum:
            - male
            - female
            - any
            - unknown
            - unspecified
            - other
        status:
          type: string
          enum:
            - active
            - inactive
            - hospitalised
            - deceased
            - discharged
            - pre-assessment
            - dummy
        externalSource:
          $ref: '#/components/schemas/ExternalSourceDto'
      required:
        - name
        - home
        - dateOfBirth
    UpdateResidentDto:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/ResidentNameDto'
        dateOfBirth:
          type: string
          example: '1945-06-15'
          description: ISO 8601 date
        gender:
          type: string
          enum:
            - male
            - female
            - any
            - unknown
            - unspecified
            - other
        status:
          type: string
          enum:
            - active
            - inactive
            - hospitalised
            - deceased
            - discharged
            - pre-assessment
            - dummy
        preferredName:
          type: string
          example: Jen
        externalSource:
          $ref: '#/components/schemas/ExternalSourceDto'
    UserResponseDto:
      type: object
      properties:
        data:
          description: Array of users
          example:
            - id: 68406c31e55ca6b6d2262f56
              name:
                first: Jane
                last: Smith
                full: Jane Smith
              email: jane.smith@example.co.uk
              role: carehome-admin
              cernerRole: standard
              active: true
              deleted: false
              dateOfBirth: '1985-03-22T00:00:00.000Z'
              startDate: '2026-01-02T00:00:00.000Z'
              endDate: null
              createdOn: '2026-01-15T09:00:00.000Z'
              lastSeen: '2026-02-10T16:45:00.000Z'
              firstLogin: '2026-01-15T09:18:06.809Z'
              phoneNumber: +44 7700 900789
              address:
                name: ''
                number: '10'
                street1: Example Road
                street2: ''
                suburb: York
                state: ''
                postcode: EX1 1AB
              allergies: None
              hasAllergies: 'no'
              home: 5a1174a35dcb0e004030a28d
              homes:
                - 5a1174a35dcb0e004030a28d
              permissions:
                - residents:read
                - logs:read
              permissionsTemplate: care-home-admin
              medicationPermission: true
              gpConnectPermission: false
              zones:
                - Oak Wing
              allZones: false
              workProfile:
                contractType: fullTime
                contractedHoursPerWeek: 37.5
                contractNotes: ''
                rotaPreferenceNotes: Prefers day shifts
                canDoOvertime: true
                availableTransportation:
                  - car
                availability: {}
              hasRequestedDemo: false
              picture: >-
                https://lmc-care-uploads.s3.eu-west-2.amazonaws.com/photos/users/example-user-id/avatar.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=EXAMPLE%2F20260115%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20260115T090000Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=examplesignature
              summary: Experienced care home administrator.
              customId: example-admin-id-123
              resident: null
              emergencyContactName:
                first: John
                last: Smith
              emergencyContactRelation: Spouse
              emergencyContactNumber: +44 7700 900999
          type: array
          items:
            type: object
        pagination:
          description: Pagination metadata
          allOf:
            - $ref: '#/components/schemas/PaginationMetaDto'
      required:
        - data
        - pagination
    UserNameDto:
      type: object
      properties:
        first:
          type: string
          example: Jane
        last:
          type: string
          example: Smith
      required:
        - first
        - last
    CreateUserDto:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/UserNameDto'
        email:
          type: string
          example: jane.smith@sunrisecare.co.uk
        role:
          type: string
          enum:
            - carer
            - senior-carer
            - carehome-admin
            - management
        home:
          type: string
          example: 507f1f77bcf86cd799439011
          description: Primary home ID
        homes:
          example: []
          type: array
          items:
            type: string
        externalSource:
          $ref: '#/components/schemas/ExternalSourceDto'
      required:
        - name
        - email
        - role
        - home
    UpdateUserDto:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/UserNameDto'
        email:
          type: string
          example: jane.smith@sunrisecare.co.uk
        role:
          type: string
          enum:
            - carer
            - senior-carer
            - carehome-admin
            - management
        active:
          type: boolean
          example: true
        externalSource:
          $ref: '#/components/schemas/ExternalSourceDto'
    CarePlanDateField:
      type: string
      enum:
        - created_on
        - edited_on
        - next_review_date
        - ingested_on
    CarePlanResponseDto:
      type: object
      properties:
        data:
          description: Array of care plans with comprehensive care information
          example:
            - id: 697b6a5b943a178423a9264b
              name: Enhanced Mobility Care Plan
              home:
                id: 66e2aeef14dce156439010d5
                name: Sunrise Care Home
              resident:
                id: 69613fc010eecc5386f987ae
                name:
                  first: Margaret
                  last: Thompson
                  full: Margaret Thompson
                preferredName: Maggie
              editedBy:
                id: 68406c31e55ca6b6d2262f56
                name:
                  first: Sarah
                  last: Manager
                  full: Sarah Manager
              goals:
                - 6968bf21c441cf6fb4ac9a3e
              needs: Requires support with mobility and transfers.
              strengths: >-
                Motivated to remain independent; engages well with
                physiotherapy.
              reviewComment: Progressing well, continue current plan.
              nextReviewDate: '2026-04-29T00:00:00.000Z'
              editedOn: '2026-02-01T11:00:00.000Z'
              createdOn: '2026-01-29T14:10:35.209Z'
              isCustom: true
              outcomes: Maintain independent mobility within the home.
              sections:
                - title: Mobility
                  needs: >-
                    Requires assistance with transfers and walking longer
                    distances.
                  strengths: Able to walk short distances with a frame.
                  outcomes: Walk to the dining room with minimal assistance.
              documents:
                - 6977686fc18f55207654e609
              revisions: 1
              carePlanId: 5f213e77cdd809d04ba664be
              isRevision: false
              skillNeeds:
                - 68cae49a5df0b900121771f2
              subActivity: Transfers
              fluidTracking:
                enabled: true
                intakeTarget: 1500
              riskAssessments:
                - 696f910b62d69cb14944bd29
              noIdentifiedNeed: false
              noFurtherSupportRequired: false
          type: array
          items:
            type: object
        pagination:
          description: >-
            Pagination metadata including total count, current page, and page
            size
          example:
            page: 1
            limit: 10
            total: 150
            totalPages: 15
            hasNext: true
            hasPrevious: false
          allOf:
            - $ref: '#/components/schemas/PaginationMetaDto'
      required:
        - data
        - pagination
    HomeResponseDto:
      type: object
      properties:
        data:
          description: Array of homes
          example:
            - id: 66e2aeef14dce156439010d5
              name: Sunrise Care Home
              active: true
              address:
                postcode: EX1 1AB
                state: null
                street1: 123 Example Street
                suburb: Exampletown
                isPrevious: false
                isCurrent: true
                country: United Kingdom
              odsCode: EX001
              incidentSeverity:
                '1': Minor
                '2': Moderate
                '3': Significant
                '4': Serious
                '5': Major
              telephone: +44 1632 960456
              bedCapacity: 45
              countryCode: ENG
              preferredPeopleNominative: Residents
              preferredCarePlansNominative: Care Plans
              customId: example-home-id-123
              homeGroup:
                id: 5f155c4ac49007031a671d4e
                name: Sunrise Care Group
              logCategoryItems:
                - id: 5e81db67b1b4e673bc2bb8cc
                  name: Catheter
              familyLogCategoryItems:
                - id: 68cae49a5df0b900121771f2
                  name: Activities
              picture: >-
                https://lmc-care-uploads.s3.eu-west-2.amazonaws.com/photos/home/example-home-id/home.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=EXAMPLE%2F20260720%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20260720T085642Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=examplesignature
              showAllResidentsButton: true
              visitBasedAccessControl: false
              startAccessTimeValue: 1
              startAccessTimeUnit: hours
              endAccessTimeValue: 1
              endAccessTimeUnit: hours
              sortByRoomNumber: true
              familyCarePlans: true
              familyDocuments: true
              familyShowNames: true
              familyShowDates: true
              locations:
                - Oak Wing
                - Maple Wing
              tier: premium
              careSetting: residential
              serviceUserType: olderPeople
              secondaryCareSetting: nursing
              secondaryServiceUserType: dementia
              rotaSettings:
                flexiVisits: false
                fundingTypesCount: 3
                contractTypesCount: 2
                absenceTypesCount: 4
                shiftTypesCount: 5
                visitTypesCount: 0
              privacyOfficers:
                - id: 507f1f77bcf86cd799439022
                  name: Jane Smith
                  email: jane.smith@example.com
                  startDate: '2026-01-15T00:00:00.000Z'
              features:
                deviceAccessControl:
                  granted: true
                  enabled: true
                eMAR:
                  granted: true
                  enabled: false
                family:
                  granted: true
                  enabled: true
                geoLocation:
                  granted: false
                  enabled: false
                rota:
                  granted: true
                  enabled: true
                noticeBoard:
                  granted: true
                  enabled: true
                positiveBehaviour:
                  granted: false
                  enabled: false
              createdOn: '2026-07-20T08:56:42.725Z'
          type: array
          items:
            type: object
        pagination:
          description: Pagination metadata
          allOf:
            - $ref: '#/components/schemas/PaginationMetaDto'
      required:
        - data
        - pagination
    IncidentReportResponseDto:
      type: object
      properties:
        data:
          description: Array of incident reports with enriched data from open_api schema
          example:
            - id: 6980aa75a5429846498a40da
              createdOn: '2026-04-09T18:48:00.000Z'
              log:
                title: Safeguarding
                description: >-
                  Resident reported feeling unsafe in the garden area. Staff
                  responded immediately and documented the incident.
                timeLogged: '2026-04-09T18:48:00.000Z'
                location: Garden
              case: null
              home:
                id: 66e2aeef14dce156439010d5
                name: Sunrise Care Home
              resident:
                id: 69613fc010eecc5386f987b2
                name:
                  first: David
                  last: Williams
                  full: David Williams
              status: needsReview
              closedBy: null
              closedOn: null
              severity: 2
              isDeleted: false
              reviewedOn: null
              closeComment: null
              category:
                id: 5e867702b349f776c8d48c34
                name: Incident
                icon: >-
                  https://lmc-data-production.s3.eu-west-2.amazonaws.com/icons/qXxuGVYsSRgAcXoZ.png
                color: '#FF3366'
              item:
                id: 68cae49a5df0b900121771f2
                name: Safeguarding
                icon: >-
                  https://lmc-data-production.s3.eu-west-2.amazonaws.com/icons/DrpQZb2rGf1HHvuI.png
          type: array
          items:
            type: object
        pagination:
          description: Pagination metadata
          allOf:
            - $ref: '#/components/schemas/PaginationMetaDto'
      required:
        - data
        - pagination
    GoalResponseDto:
      type: object
      properties:
        data:
          description: Array of goals
          example:
            - id: 6968bf21c441cf6fb4ac9a3e
              home:
                id: home-123-abc
                name: Sunrise Care Home
              resident:
                id: resident_id_123
                name:
                  first: John
                  last: Doe
                  full: John Doe
              createdBy:
                id: user_id_789
                name:
                  first: Sarah
                  last: Manager
                  full: Sarah Manager
              editedBy:
                id: user_id_790
                name:
                  first: Jane
                  last: Smith
                  full: Jane Smith
              logs:
                - 6968bf21c441cf6fb4ac9a3f
                - 696f874462d69cb149439f25
              title: Improve Mobility
              seenBy: []
              status: notStarted
              actions: []
              endDate: '2026-06-30T00:00:00.000Z'
              editedOn: '2026-01-23T14:18:42.514Z'
              createdOn: '2026-01-15T10:30:00.000Z'
              startDate: '2026-01-15T00:00:00.000Z'
              importance: 8
              description: Increase independent walking distance to 50 meters
              nextReviewDate: '2026-03-30T00:00:00.000Z'
              progressHistory:
                - date: '2026-01-15T10:19:13.900Z'
                  progress: 0
              successMeasurement: Able to walk 50 meters independently
          type: array
          items:
            type: object
        pagination:
          description: Pagination metadata
          allOf:
            - $ref: '#/components/schemas/PaginationMetaDto'
      required:
        - data
        - pagination
    RiskAssessmentResponseDto:
      type: object
      properties:
        data:
          description: Array of risk assessments
          example:
            - id: 696f910b62d69cb14944bd29
              form:
                id: 6960cb5add702a0011af4ce2
                name: ''
                formFields: []
              home:
                id: home-123-abc
                name: Sunrise Care Home
              resident:
                id: resident_id_123
                name:
                  first: John
                  last: Doe
                  full: John Doe
                preferredName: Johnny
              createdBy:
                id: user_id_789
                name:
                  first: Sarah
                  last: Manager
                  full: Sarah Manager
              seenBy: []
              archived: false
              createdOn: '2026-01-20T14:28:27.400Z'
              riskLevel: high
              riskScore: 12
              incomplete: false
              reviewedOn: '2026-01-20T14:28:27.401Z'
          type: array
          items:
            type: object
        pagination:
          description: Pagination metadata
          allOf:
            - $ref: '#/components/schemas/PaginationMetaDto'
      required:
        - data
        - pagination
    LogResponseDto:
      type: object
      properties:
        data:
          description: Array of logs (daily care notes) with enriched data
          example:
            - id: 6980bf40b0d86defd672b8a1
              title: Resident had a good breakfast
              type: log
              timeLogged: '2026-02-02T15:14:02.272Z'
              originalTimeLog: '2026-02-02T15:14:08.625Z'
              description: >-
                Ate all food, engaged in conversation with other residents. No
                assistance required.
              location: Dining Room
              deleted: false
              home:
                id: 66e2aeef14dce156439010d5
                name: Sunrise Care Home
              resident:
                id: 69613fc010eecc5386f987ae
                name:
                  first: Margaret
                  last: Thompson
                  full: Margaret Thompson
              loggedBy:
                id: 68406c31e55ca6b6d2262f56
                name:
                  first: Jane
                  last: Smith
                  full: Jane Smith
              editedBy:
                id: 68ef4775c1e051de495b175a
                name:
                  first: Sarah
                  last: Manager
                  full: Sarah Manager
              category:
                id: 5e867702b349f776c8d48c34
                name: Food & Drink
              item:
                id: 68cae49a5df0b900121771f2
                name: Breakfast
              editedAt: '2026-02-02T15:20:00.000Z'
              revisions: 0
              picture1: >-
                https://lmc-care-uploads.s3.eu-west-2.amazonaws.com/photos/home/logs/example-home-id/photo1.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=EXAMPLE%2F20260202%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20260202T151402Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=examplesignature
              picture2: null
              picture3: null
              videoFile: null
              videoThumbnail: null
              hidden: false
              isNextHandover: false
              revoked: false
              revokedAt: null
              nonEditable: false
              amount1: 250
              amount2: 0
              amountType: ml
              stockQuantityType: volume
              latitude: 51.5
              longitude: -1.5
              accuracy: 10
              itemSublevel: Lunch
              doneBySu: false
              response:
                questions:
                  - key: mood
                    label: Mood
                    value: Happy
          type: array
          items:
            type: object
        pagination:
          description: Pagination metadata
          allOf:
            - $ref: '#/components/schemas/PaginationMetaDto'
      required:
        - data
        - pagination
    LogCategoryResponseDto:
      type: object
      properties:
        data:
          description: Array of log categories
          example:
            - id: 5f213e77cdd809d04ba664be
              name: Body Maps
              color: '#9966FB'
          type: array
          items:
            type: object
        pagination:
          description: Pagination metadata
          allOf:
            - $ref: '#/components/schemas/PaginationMetaDto'
      required:
        - data
        - pagination
    LogCategoryItemResponseDto:
      type: object
      properties:
        data:
          description: Array of log category items
          example:
            - id: 5e81db67b1b4e673bc2bb8cc
              name: Catheter
              category: 5e867702b349f776c8d48c2f
          type: array
          items:
            type: object
        pagination:
          description: Pagination metadata
          allOf:
            - $ref: '#/components/schemas/PaginationMetaDto'
      required:
        - data
        - pagination
    DocumentResponseDto:
      type: object
      properties:
        data:
          description: Array of documents with enriched data
          example:
            - id: 6977686fc18f55207654e609
              name: Medical Assessment - January 2026
              createdAt: '2026-01-26T13:13:19.529Z'
              home:
                id: 66e2aeef14dce156439010d5
                name: Sunrise Care Home
              resident:
                id: 69613fc010eecc5386f987ae
                name:
                  first: Margaret
                  last: Thompson
                  full: Margaret Thompson
              category:
                id: 5f155c4ac49007031a671d4f
                name: Care Plans
              pdf: >-
                https://lmc-care-uploads.s3.eu-west-2.amazonaws.com/docs/home/documents/example-home-id/document-file.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=EXAMPLE%2F20260126%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20260126T131319Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=examplesignature
              originalFile: Medical_Assessment_Jan2026.pdf
              attachedToCarePlan: true
          type: array
          items:
            type: object
        pagination:
          description: Pagination metadata
          allOf:
            - $ref: '#/components/schemas/PaginationMetaDto'
      required:
        - data
        - pagination
    HomeDocumentResponseDto:
      type: object
      properties:
        data:
          description: Array of home documents with enriched data
          example:
            - id: 6915ffc2e924f18fb5af8879
              name: Fire Safety Policy - 2026
              createdAt: '2026-11-13T15:56:50.600Z'
              home:
                id: 66e2aeef14dce156439010d5
                name: Sunrise Care Home
              category:
                id: 5f155c4ac49007031a671d4f
                name: General
              pdf: >-
                https://lmc-care-uploads.s3.eu-west-2.amazonaws.com/docs/home/homeDocuments/example-home-id/document-file.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=EXAMPLE%2F20260113%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20260113T155650Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=examplesignature
              originalFile: Fire_Safety_Policy_2026.pdf
          type: array
          items:
            type: object
        pagination:
          description: Pagination metadata
          allOf:
            - $ref: '#/components/schemas/PaginationMetaDto'
      required:
        - data
        - pagination
    DeviceResponseDto:
      type: object
      properties:
        data:
          description: Array of devices
          example:
            - id: 64f8a1b23d4e5f6a7b8c9d0e
              name: Reception Tablet
              uuid: 550e8400-e29b-41d4-a716-446655440000
              version: 4.2.1
              model: iPad Pro 12.9
              type: tablet
              users:
                - id: 64f8a1b23d4e5f6a7b8c9d01
                  name:
                    first: Jane
                    last: Smith
                    full: Jane Smith
              homes:
                - home:
                    id: 64f8a1b23d4e5f6a7b8c9d02
                    name: Sunrise Care Home
                  status: approved
              lastUsedBy:
                id: 64f8a1b23d4e5f6a7b8c9d01
                name:
                  first: Jane
                  last: Smith
                  full: Jane Smith
              lastUsedOn: '2026-03-07T14:30:00.000Z'
              createdBy:
                id: 64f8a1b23d4e5f6a7b8c9d03
                name:
                  first: Admin
                  last: User
                  full: Admin User
              createdOn: '2026-01-15T10:00:00.000Z'
              editedBy:
                id: 64f8a1b23d4e5f6a7b8c9d01
                name:
                  first: Jane
                  last: Smith
                  full: Jane Smith
              editedOn: '2026-03-07T14:30:00.000Z'
          type: array
          items:
            type: object
        pagination:
          description: Pagination metadata
          allOf:
            - $ref: '#/components/schemas/PaginationMetaDto'
      required:
        - data
        - pagination
security:
  - Bearer: []
