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