Luma Health Engagements API

openapi: 3.2.0
info:
  version: 2.0.0
  title: Rest-Service Engagements API
  x-logo:
    url: https://lumahealth-assets.s3.us-west-2.amazonaws.com/new_luma_logo_black.png
    backgroundColor: '#FFFFFF'
    altText: Luma Health
  description: OpenAPI [Basic Structure](https://swagger.io/docs/specification/basic-structure/)
servers:
- url: https://api.lumahealth.io/api/v2
security:
- Bearer: []
tags:
- name: engagements
  description: Conversation sessions between the system and a recipient, driven by one or more AI agents
paths:
  /engagements:
    get:
      summary: List engagements
      operationId: engagementsList
      tags:
      - engagements
      parameters:
      - name: recipient
        in: query
        description: ID of the recipient user.
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      - name: recipientType
        in: query
        schema:
          type: string
          enum:
          - doctor
          - staff
          - patient
          - system
      - name: status
        in: query
        schema:
          type: string
          enum:
          - in-progress
          - failed
          - success
          - escalation_required
          - idle
      - $ref: '#/components/parameters/userParam'
      - $ref: '#/components/parameters/deletedParam'
      - $ref: '#/components/parameters/createdByParam'
      - $ref: '#/components/parameters/updatedByParam'
      - $ref: '#/components/parameters/createdAtParam'
      - $ref: '#/components/parameters/updatedAtParam'
      - $ref: '#/components/parameters/pageParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/populateParam'
      - $ref: '#/components/parameters/selectParam'
      responses:
        '200':
          description: List of engagements
          content:
            application/json:
              schema:
                type: object
                required:
                - response
                - page
                - size
                properties:
                  response:
                    type: array
                    minItems: 0
                    items:
                      $ref: '#/components/schemas/EngagementResponse'
                  page:
                    type: integer
                    format: int32
                    minimum: 1
                  size:
                    type: integer
                    format: int32
                    minimum: 0
                additionalProperties: false
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
    post:
      summary: Create an engagement
      operationId: engagementCreate
      tags:
      - engagements
      requestBody:
        description: Create an engagement
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EngagementRequestCreate'
      responses:
        '201':
          description: Successful creation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EngagementResponse'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
  /engagements/{engagementId}:
    get:
      summary: Get engagement by id
      operationId: engagementGet
      tags:
      - engagements
      parameters:
      - name: engagementId
        in: path
        required: true
        description: Engagement's unique identifier in Luma's database.
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      responses:
        '200':
          description: Engagement
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EngagementResponse'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
    put:
      summary: Update an engagement
      operationId: engagementUpdate
      tags:
      - engagements
      parameters:
      - name: engagementId
        in: path
        required: true
        description: Engagement's unique identifier in Luma's database.
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      requestBody:
        description: An engagement (full or partial) to be updated
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EngagementRequestUpdate'
      responses:
        '200':
          description: Engagement
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EngagementResponse'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
    delete:
      summary: Delete an engagement
      operationId: engagementDelete
      tags:
      - engagements
      parameters:
      - name: engagementId
        in: path
        required: true
        description: Engagement's unique identifier in Luma's database.
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      responses:
        '200':
          description: Deleted engagement
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EngagementResponse'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
  /engagements/findOrCreate:
    post:
      summary: Find or create an engagement
      description: Finds an existing engagement matching the given criteria, or creates a new one if none exists. If `patient` is set and `recipient` is not, `recipient` and `recipientType` are automatically derived from `patient`.
      operationId: engagementFindOrCreate
      tags:
      - engagements
      requestBody:
        description: The criteria to find or create an engagement with
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - patient
              - direction
              properties:
                patient:
                  type: string
                  pattern: '[0-9a-f]'
                  minLength: 24
                  maxLength: 24
                direction:
                  type: string
                  enum:
                  - inbound
                  - outbound
                agents:
                  type: array
                  items:
                    type: string
                    pattern: '[0-9a-f]'
                    minLength: 24
                    maxLength: 24
                goals:
                  type: array
                  items:
                    type: object
                    additionalProperties: false
                    required:
                    - type
                    properties:
                      type:
                        type: string
                channel:
                  type: string
                  enum:
                  - sms
                  - email
                  - voice
                  - chat
                  - whatsapp
                outboundNumber:
                  type: string
                  pattern: '[0-9a-f]'
                  minLength: 24
                  maxLength: 24
                expiresAt:
                  type: string
                  format: date-time
                context:
                  type: object
      responses:
        '200':
          description: The found or newly created engagement
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EngagementResponse'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
  /engagements/{engagement}/operations/{operation}:
    post:
      summary: Perform an operation on an engagement
      description: Generic operation dispatcher for an in-flight engagement, used to transfer or end a call, request a callback, send an SMS, hand off to the hub, transfer channels, or push a new EngagementEvent onto the engagement.
      operationId: engagementPerformOperation
      tags:
      - engagements
      parameters:
      - name: engagement
        in: path
        required: true
        description: Engagement's unique identifier in Luma's database.
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      - name: operation
        in: path
        required: true
        description: The operation to perform.
        schema:
          type: string
          enum:
          - transferCall
          - end
          - callMe
          - sendSms
          - sendToHub
          - transferChannel
          - pushEvent
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                operationData:
                  type: object
                  description: Data for the operation being performed. For `pushEvent`, this is the EngagementEvent payload to append.
      responses:
        '200':
          description: The updated engagement
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EngagementResponse'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
  /engagements/{engagementId}/findLatest/{eventName}:
    get:
      summary: Find the most recent engagement event by name
      description: Finds the most recent EngagementEvent for this engagement whose `payload.name` matches `eventName`.
      operationId: engagementFindLatestEvent
      tags:
      - engagements
      parameters:
      - name: engagementId
        in: path
        required: true
        description: Engagement's unique identifier in Luma's database.
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      - name: eventName
        in: path
        required: true
        description: The event name to search for, for example `VoiceCallEnded`.
        schema:
          type: string
      responses:
        '200':
          description: The most recent matching engagement event
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EngagementEventResponse'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
        '404':
          description: No matching event found
components:
  schemas:
    EngagementRequestUpdate:
      type: object
      properties:
        _id:
          $ref: '#/components/schemas/idParam'
        user:
          $ref: '#/components/schemas/userParam'
        deleted:
          $ref: '#/components/schemas/deletedParam'
        createdBy:
          $ref: '#/components/schemas/createdByParam'
        updatedBy:
          $ref: '#/components/schemas/updatedByParam'
        createdAt:
          $ref: '#/components/schemas/createdAtParam'
        updatedAt:
          $ref: '#/components/schemas/updatedAtParam'
        recipient:
          type: string
          description: ID of the user this engagement is directed at.
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        recipientType:
          type: string
          description: The kind of user `recipient` is.
          enum:
          - doctor
          - staff
          - patient
          - system
        patient:
          type: string
          description: DEPRECATED. Use `recipient` and `recipientType` instead.
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        expiresAt:
          type: string
          format: date-time
        topic:
          type: string
        agents:
          type: array
          description: IDs of the AI agents involved in this engagement.
          items:
            type: string
            pattern: '[0-9a-f]'
            minLength: 24
            maxLength: 24
        mainAgent:
          type: string
          description: ID of the primary AI agent driving this engagement.
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        engagementSetting:
          type: string
          description: ID of the EngagementSetting (voice/language preset) used for this engagement.
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        context:
          type: object
          description: Initial context provided to the engagement, used for outbound flows. Keys must correspond to AgentContextVariable names, and values must conform to that variable's schema.
        metadata:
          type: object
          description: Metadata about the engagement's inactivity tracking and routing decisions.
          properties:
            inactivityPolicy:
              type: object
              properties:
                anchor:
                  type: string
                inactiveAfterMs:
                  type: number
                closeAfterIdleMs:
                  type: number
                timeoutAt:
                  type: string
                  format: date-time
            inactivityState:
              type: object
              properties:
                lastRelevantActivityAt:
                  type: string
                  format: date-time
                firstBecameInactiveAt:
                  type: string
                  format: date-time
                lastInactiveEventAt:
                  type: string
                  format: date-time
            sourceService:
              type: string
            routingDecision:
              type: object
              properties:
                agentId:
                  type: string
        completedAt:
          type: string
          format: date-time
        type:
          type: string
          default: conversational
          enum:
          - conversational
          - other
        status:
          type: string
          description: Lifecycle status of the engagement. Transitions from `in-progress` to `success`, `failed`, or `escalation_required`.
          enum:
          - in-progress
          - failed
          - success
          - escalation_required
          - idle
        statusReason:
          type: string
          enum:
          - expired
          - systemic_failure
    userParam:
      in: query
      name: user
      required: false
      type: string
      pattern: '[0-9a-f]'
      minLength: 24
      maxLength: 24
      schema:
        type: string
        pattern: '[0-9a-f]'
        minLength: 24
        maxLength: 24
      description: The ID of the root account user.
    EngagementResponse:
      type: object
      description: An Engagement represents a single interaction or conversation session between the system and a recipient, such as a patient, staff member, doctor, or the system itself, for example an inbound or outbound call, SMS thread, chat, or email exchange, driven by one or more AI agents. It tracks lifecycle state as the conversation moves from in-progress to a terminal success, failure, or escalation-required status, the channel and context of the conversation, and optionally links to a reusable EngagementSetting that supplies voice and language presets. EngagementEvents reference an Engagement to form an event-sourcing style history of everything that happened during it.
      properties:
        _id:
          $ref: '#/components/schemas/idParam'
        user:
          $ref: '#/components/schemas/userParam'
        deleted:
          $ref: '#/components/schemas/deletedParam'
        createdBy:
          $ref: '#/components/schemas/createdByParam'
        updatedBy:
          $ref: '#/components/schemas/updatedByParam'
        createdAt:
          $ref: '#/components/schemas/createdAtParam'
        updatedAt:
          $ref: '#/components/schemas/updatedAtParam'
        recipient:
          type: string
          description: ID of the user this engagement is directed at.
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        recipientType:
          type: string
          description: The kind of user `recipient` is.
          enum:
          - doctor
          - staff
          - patient
          - system
        patient:
          type: string
          description: DEPRECATED. Use `recipient` and `recipientType` instead.
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        expiresAt:
          type: string
          format: date-time
        topic:
          type: string
        agents:
          type: array
          description: IDs of the AI agents involved in this engagement.
          items:
            type: string
            pattern: '[0-9a-f]'
            minLength: 24
            maxLength: 24
        mainAgent:
          type: string
          description: ID of the primary AI agent driving this engagement.
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        engagementSetting:
          type: string
          description: ID of the EngagementSetting (voice/language preset) used for this engagement.
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        context:
          type: object
          description: Initial context provided to the engagement, used for outbound flows. Keys must correspond to AgentContextVariable names, and values must conform to that variable's schema.
        metadata:
          type: object
          description: Metadata about the engagement's inactivity tracking and routing decisions.
          properties:
            inactivityPolicy:
              type: object
              properties:
                anchor:
                  type: string
                inactiveAfterMs:
                  type: number
                closeAfterIdleMs:
                  type: number
                timeoutAt:
                  type: string
                  format: date-time
            inactivityState:
              type: object
              properties:
                lastRelevantActivityAt:
                  type: string
                  format: date-time
                firstBecameInactiveAt:
                  type: string
                  format: date-time
                lastInactiveEventAt:
                  type: string
                  format: date-time
            sourceService:
              type: string
            routingDecision:
              type: object
              properties:
                agentId:
                  type: string
        completedAt:
          type: string
          format: date-time
        type:
          type: string
          default: conversational
          enum:
          - conversational
          - other
        status:
          type: string
          description: Lifecycle status of the engagement. Transitions from `in-progress` to `success`, `failed`, or `escalation_required`.
          enum:
          - in-progress
          - failed
          - success
          - escalation_required
          - idle
        statusReason:
          type: string
          enum:
          - expired
          - systemic_failure
    EngagementRequestCreate:
      type: object
      required:
      - recipient
      - recipientType
      properties:
        _id:
          $ref: '#/components/schemas/idParam'
        user:
          $ref: '#/components/schemas/userParam'
        deleted:
          $ref: '#/components/schemas/deletedParam'
        createdBy:
          $ref: '#/components/schemas/createdByParam'
        updatedBy:
          $ref: '#/components/schemas/updatedByParam'
        createdAt:
          $ref: '#/components/schemas/createdAtParam'
        updatedAt:
          $ref: '#/components/schemas/updatedAtParam'
        recipient:
          type: string
          description: ID of the user this engagement is directed at.
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        recipientType:
          type: string
          description: The kind of user `recipient` is.
          enum:
          - doctor
          - staff
          - patient
          - system
        patient:
          type: string
          description: DEPRECATED. Use `recipient` and `recipientType` instead.
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        expiresAt:
          type: string
          format: date-time
        topic:
          type: string
        agents:
          type: array
          description: IDs of the AI agents involved in this engagement.
          items:
            type: string
            pattern: '[0-9a-f]'
            minLength: 24
            maxLength: 24
        mainAgent:
          type: string
          description: ID of the primary AI agent driving this engagement.
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        engagementSetting:
          type: string
          description: ID of the EngagementSetting (voice/language preset) used for this engagement.
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        context:
          type: object
          description: Initial context provided to the engagement, used for outbound flows. Keys must correspond to AgentContextVariable names, and values must conform to that variable's schema.
        metadata:
          type: object
          description: Metadata about the engagement's inactivity tracking and routing decisions.
          properties:
            inactivityPolicy:
              type: object
              properties:
                anchor:
                  type: string
                inactiveAfterMs:
                  type: number
                closeAfterIdleMs:
                  type: number
                timeoutAt:
                  type: string
                  format: date-time
            inactivityState:
              type: object
              properties:
                lastRelevantActivityAt:
                  type: string
                  format: date-time
                firstBecameInactiveAt:
                  type: string
                  format: date-time
                lastInactiveEventAt:
                  type: string
                  format: date-time
            sourceService:
              type: string
            routingDecision:
              type: object
              properties:
                agentId:
                  type: string
        completedAt:
          type: string
          format: date-time
        type:
          type: string
          default: conversational
          enum:
          - conversational
          - other
        status:
          type: string
          description: Lifecycle status of the engagement. Transitions from `in-progress` to `success`, `failed`, or `escalation_required`.
          enum:
          - in-progress
          - failed
          - success
          - escalation_required
          - idle
        statusReason:
          type: string
          enum:
          - expired
          - systemic_failure
    idParam:
      in: query
      name: _id
      type: string
      pattern: '[0-9a-f]'
      minLength: 24
      maxLength: 24
      required: false
      schema:
        type: string
        pattern: '[0-9a-f]'
        minLength: 24
        maxLength: 24
      description: Luma's internal ID of an object.
    updatedAtParam:
      in: query
      name: updatedAt
      type: string
      format: date-time
      schema:
        type: string
        format: date-time
      required: false
      description: The date/time when this object was updated.
    createdAtParam:
      in: query
      name: createdAt
      type: string
      format: date-time
      schema:
        type: string
        format: date-time
      required: false
      description: The date/time when this object was created.
    updatedByParam:
      in: query
      name: updatedBy
      required: false
      type: string
      pattern: '[0-9a-f]'
      minLength: 24
      maxLength: 24
      schema:
        type: string
        pattern: '[0-9a-f]'
        minLength: 24
        maxLength: 24
      description: The ID of the user who updated this object.
    EngagementEventResponse:
      type: object
      description: An EngagementEvent is an immutable, append-only log record of something that happened during an Engagement, such as an agent being assigned, a message being sent or received, a voice call starting or ending, or a lifecycle transition. Each event belongs to exactly one Engagement, and the ordered set of events for an engagement forms its event-sourcing history.
      properties:
        _id:
          $ref: '#/components/schemas/idParam'
        user:
          $ref: '#/components/schemas/userParam'
        deleted:
          $ref: '#/components/schemas/deletedParam'
        createdBy:
          $ref: '#/components/schemas/createdByParam'
        updatedBy:
          $ref: '#/components/schemas/updatedByParam'
        createdAt:
          $ref: '#/components/schemas/createdAtParam'
        updatedAt:
          $ref: '#/components/schemas/updatedAtParam'
        engagement:
          type: string
          description: ID of the parent Engagement this event occurred during.
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        recipient:
          type: string
          description: ID of the user this event is about, if applicable.
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        payload:
          type: object
          description: The event's contents.
          properties:
            name:
              type: string
              description: The kind of event, for example `AgentAssigned`, `MessageSent`, `VoiceCallStarted`, `EngagementCompleted`.
            body:
              type: object
              description: Event-specific data, shape depends on `name`.
            metadata:
              type: object
              properties:
                source:
                  type: object
                  properties:
                    service:
                      type: string
                    agent:
                      type: string
                    operation:
                      type: string
                update:
                  type: array
                  items:
                    type: object
                    properties:
                      fromEvent:
                        type: string
                      toEngagement:
                        type: string
                      op:
                        type: string
                        default: $set
                        enum:
                        - $set
                        - $push
                        - $pull
                        - $addToSet
    deletedParam:
      in: query
      name: deleted
      required: false
      type: number
      enum:
      - 0
      - 1
      schema:
        type: number
        enum:
        - 0
        - 1
      description: Flag for logical deletion where 1 means deleted.
    createdByParam:
      in: query
      name: createdBy
      type: string
      pattern: '[0-9a-f]'
      minLength: 24
      maxLength: 24
      schema:
        type: string
        pattern: '[0-9a-f]'
        minLength: 24
        maxLength: 24
      required: false
      description: The ID of the user who created this object.
  parameters:
    pageParam:
      in: query
      name: page
      required: false
      type: integer
      format: int32
      default: 1
      minimum: 1
      schema:
        type: integer
        format: int32
        default: 1
        minimum: 1
    createdAtParam:
      in: query
      name: createdAt
      type: string
      format: date-time
      schema:
        type: string
        format: date-time
      required: false
      description: The date/time when this object was created.
    updatedAtParam:
      in: query
      name: updatedAt
      type: string
      format: date-time
      schema:
        type: string
        format: date-time
      required: false
      description: The date/time when this object was updated.
    updatedByParam:
      in: query
      name: updatedBy
      required: false
      type: string
      pattern: '[0-9a-f]'
      minLength: 24
      maxLength: 24
      schema:
        type: string
        pattern: '[0-9a-f]'
        minLength: 24
        maxLength: 24
      description: The ID of the user who updated this object.
    createdByParam:
      in: query
      name: createdBy
      type: string
      pattern: '[0-9a-f]'
      minLength: 24
      maxLength: 24
      schema:
        type: string
        pattern: '[0-9a-f]'
        minLength: 24
        maxLength: 24
      required: false
      description: The ID of the user who created this object.
    populateParam:
      name: _populate
      in: query
      description: Response properties which will be replaced by the referenced objects, separated by commas.
      required: false
      type: string
      schema:
        type: string
    selectParam:
      name: _select
      in: query
      description: Response properties that should be returned, separated by commas.
      required: false
      type: string
      schema:
        type: string
    deletedParam:
      in: query
      name: deleted
      required: false
      type: number
      enum:
      - 0
      - 1
      schema:
        type: number
        enum:
        - 0
        - 1
      description: Flag for logical deletion where 1 means deleted.
    limitParam:
      name: limit
      in: query
      description: How many items to fetch per page
      required: false
      type: integer
      format: int32
      default: 500
      minimum: 1
      maximum: 1000
      schema:
        type: integer
        format: int32
        default: 500
        minimum: 1
        maximum: 1000
    userParam:
      in: query
      name: user
      required: false
      type: string
      pattern: '[0-9a-f]'
      minLength: 24
      maxLength: 24
      schema:
        type: string
        pattern: '[0-9a-f]'
        minLength: 24
        maxLength: 24
      description: The ID of the root account user.
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT