openapi: 3.0.3
info:
  title: VivaLNK Biometrics Data Platform API (Modeled)
  description: >-
    A modeled OpenAPI description of the VivaLNK (Vivalink) Biometrics Data
    Platform cloud API for remote patient monitoring. VivaLNK provides
    medical-grade wearable biosensors (Multi-Vital ECG patch, temperature
    patch, SpO2 sensor, BP cuff) and a cloud platform that ingests their data
    over RESTful HTTPS services (Amazon API Gateway plus Amazon Kinesis for
    near-real-time ingestion) and makes it available for machine-to-machine
    (M2M) integration, webhook push, FHIR interoperability, and bulk file
    export.

    IMPORTANT: VivaLNK's developer surface is delivered through its SDK and
    Developer Program and is partner-gated - the full API reference is provided
    under license rather than published openly. The paths, base URL, request
    parameters, and schemas below are MODELED from VivaLNK's documented
    platform capabilities (M2M cloud web services, webhook support, FHIR
    support, data-file downloads) and are NOT copied from a public reference.
    Field names, the exact base URL, and authentication scheme must be
    confirmed against VivaLNK's licensed documentation before use.
  version: '1.0-modeled'
  contact:
    name: VivaLNK (Vivalink)
    url: https://www.vivalink.com
  x-status: modeled
  x-endpoints-confirmed: false
  x-source-notes: >-
    Confirmed via VivaLNK marketing/technical pages and the AWS Partner Network
    blog: REST over HTTPS, Amazon API Gateway, Amazon Kinesis Data Streams for
    near-real-time access, M2M cloud APIs, webhook support, FHIR support, and
    bulk data-file downloads. No public WebSocket API is documented.
servers:
  - url: https://api.vivalink.com
    description: Modeled base URL (partner-gated; actual host provided under the Developer Program)
security:
  - bearerAuth: []
tags:
  - name: Subjects
    description: Subjects (patients / study participants) enrolled for monitoring.
  - name: Devices
    description: VivaLNK wearable biosensors and their assignment to subjects.
  - name: Vital Signs
    description: Biometric measurements captured from wearables.
  - name: Webhooks
    description: Subscriptions for pushed biometric data and alert events.
  - name: FHIR
    description: HL7 FHIR R4 resources for EHR/CTMS interoperability.
paths:
  /v1/subjects:
    get:
      operationId: listSubjects
      tags: [Subjects]
      summary: List subjects
      description: Lists subjects enrolled in your account, project, or study (modeled).
      parameters:
        - name: projectId
          in: query
          schema: { type: string }
          description: Filter subjects by project or study.
        - name: limit
          in: query
          schema: { type: integer, default: 50 }
        - name: cursor
          in: query
          schema: { type: string }
      responses:
        '200':
          description: A page of subjects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/Subject' }
                  cursor: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
    post:
      operationId: createSubject
      tags: [Subjects]
      summary: Create a subject
      description: Enrolls a new subject for monitoring (modeled).
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SubjectInput' }
      responses:
        '201':
          description: The created subject.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Subject' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /v1/subjects/{subjectId}:
    parameters:
      - name: subjectId
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: getSubject
      tags: [Subjects]
      summary: Retrieve a subject
      responses:
        '200':
          description: The subject.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Subject' }
        '404': { $ref: '#/components/responses/NotFound' }
    patch:
      operationId: updateSubject
      tags: [Subjects]
      summary: Update a subject
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SubjectInput' }
      responses:
        '200':
          description: The updated subject.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Subject' }
    delete:
      operationId: deactivateSubject
      tags: [Subjects]
      summary: Deactivate a subject
      responses:
        '204': { description: Subject deactivated. }
  /v1/devices:
    get:
      operationId: listDevices
      tags: [Devices]
      summary: List devices
      description: Lists VivaLNK wearable biosensors registered to your account (modeled).
      parameters:
        - name: type
          in: query
          schema:
            type: string
            enum: [ecg, temperature, spo2, bp_cuff]
        - name: assigned
          in: query
          schema: { type: boolean }
      responses:
        '200':
          description: A list of devices.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/Device' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /v1/devices/{deviceId}:
    parameters:
      - name: deviceId
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: getDevice
      tags: [Devices]
      summary: Retrieve a device
      responses:
        '200':
          description: The device.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Device' }
        '404': { $ref: '#/components/responses/NotFound' }
  /v1/devices/{deviceId}/assignment:
    parameters:
      - name: deviceId
        in: path
        required: true
        schema: { type: string }
    put:
      operationId: assignDevice
      tags: [Devices]
      summary: Assign a device to a subject
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                subjectId: { type: string }
              required: [subjectId]
      responses:
        '200':
          description: The updated device assignment.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Device' }
    delete:
      operationId: unassignDevice
      tags: [Devices]
      summary: Unassign a device
      responses:
        '204': { description: Device unassigned. }
  /v1/subjects/{subjectId}/measurements:
    parameters:
      - name: subjectId
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: listMeasurements
      tags: [Vital Signs]
      summary: Retrieve subject measurements
      description: >-
        Returns time-ranged biometric measurements for a subject - ECG-derived
        heart rate, HRV, RR interval, respiratory rate, temperature, SpO2,
        blood pressure, and accelerometer/activity data (modeled). Near-real-time
        results are served over REST (backed by Amazon Kinesis), not a public
        streaming socket.
      parameters:
        - name: metric
          in: query
          schema:
            type: string
            enum: [heart_rate, hrv, rr_interval, respiratory_rate, temperature, spo2, blood_pressure, activity, ecg_waveform]
        - name: start
          in: query
          schema: { type: string, format: date-time }
        - name: end
          in: query
          schema: { type: string, format: date-time }
        - name: interval
          in: query
          description: Aggregation interval (raw, 1m, 5m, 1h). Omit for raw samples.
          schema: { type: string }
      responses:
        '200':
          description: A time series of measurements.
          content:
            application/json:
              schema:
                type: object
                properties:
                  subjectId: { type: string }
                  metric: { type: string }
                  unit: { type: string }
                  samples:
                    type: array
                    items: { $ref: '#/components/schemas/Measurement' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /v1/subjects/{subjectId}/exports:
    parameters:
      - name: subjectId
        in: path
        required: true
        schema: { type: string }
    post:
      operationId: createExport
      tags: [Vital Signs]
      summary: Request a bulk data-file export
      description: >-
        Requests a bulk export (for example CSV/EDF) of a subject's raw
        biometric data over a time range for retrospective analysis (modeled).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                start: { type: string, format: date-time }
                end: { type: string, format: date-time }
                format: { type: string, enum: [csv, edf, json] }
      responses:
        '202':
          description: Export accepted; poll or await a webhook for completion.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Export' }
  /v1/webhooks:
    get:
      operationId: listWebhooks
      tags: [Webhooks]
      summary: List webhook subscriptions
      responses:
        '200':
          description: A list of webhook subscriptions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/Webhook' }
    post:
      operationId: createWebhook
      tags: [Webhooks]
      summary: Create a webhook subscription
      description: >-
        Registers an HTTPS endpoint to receive pushed biometric data and alert
        events (for example threshold or arrhythmia notifications). Webhook
        push is a documented VivaLNK platform capability (modeled shape).
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/WebhookInput' }
      responses:
        '201':
          description: The created subscription.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Webhook' }
  /v1/webhooks/{webhookId}:
    parameters:
      - name: webhookId
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: getWebhook
      tags: [Webhooks]
      summary: Retrieve a webhook subscription
      responses:
        '200':
          description: The subscription.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Webhook' }
    delete:
      operationId: deleteWebhook
      tags: [Webhooks]
      summary: Delete a webhook subscription
      responses:
        '204': { description: Subscription deleted. }
  /fhir/Observation:
    get:
      operationId: searchFhirObservations
      tags: [FHIR]
      summary: Search FHIR Observations
      description: >-
        Returns biometric measurements as HL7 FHIR R4 Observation resources for
        EHR/CTMS interoperability (modeled). FHIR support is a documented
        VivaLNK Biometrics Data Platform capability.
      parameters:
        - name: patient
          in: query
          schema: { type: string }
          description: FHIR Patient reference or subject identifier.
        - name: code
          in: query
          schema: { type: string }
          description: LOINC code for the vital sign.
        - name: date
          in: query
          schema: { type: string }
      responses:
        '200':
          description: A FHIR Bundle of Observation resources.
          content:
            application/fhir+json:
              schema: { type: object }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Modeled as an OAuth2/bearer access token issued to Developer Program
        partners for machine-to-machine access. Confirm the exact scheme
        (API key vs. OAuth2 client credentials) against VivaLNK's licensed docs.
  responses:
    Unauthorized:
      description: Missing or invalid credentials.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
  schemas:
    Subject:
      type: object
      properties:
        id: { type: string }
        externalId: { type: string }
        projectId: { type: string }
        status: { type: string, enum: [active, inactive] }
        createdAt: { type: string, format: date-time }
    SubjectInput:
      type: object
      properties:
        externalId: { type: string }
        projectId: { type: string }
        metadata: { type: object, additionalProperties: true }
    Device:
      type: object
      properties:
        id: { type: string }
        serialNumber: { type: string }
        type: { type: string, enum: [ecg, temperature, spo2, bp_cuff] }
        model: { type: string }
        firmwareVersion: { type: string }
        assignedSubjectId: { type: string, nullable: true }
        status: { type: string }
    Measurement:
      type: object
      properties:
        timestamp: { type: string, format: date-time }
        value: { type: number }
        deviceId: { type: string }
    Export:
      type: object
      properties:
        id: { type: string }
        status: { type: string, enum: [pending, processing, complete, failed] }
        downloadUrl: { type: string, nullable: true }
    Webhook:
      type: object
      properties:
        id: { type: string }
        url: { type: string, format: uri }
        events:
          type: array
          items: { type: string }
        active: { type: boolean }
    WebhookInput:
      type: object
      required: [url, events]
      properties:
        url: { type: string, format: uri }
        events:
          type: array
          items:
            type: string
            enum: [measurement.created, alert.threshold, alert.arrhythmia, export.complete]
        secret: { type: string }
    Error:
      type: object
      properties:
        code: { type: string }
        message: { type: string }