Okareo Monitoring API

openapi: 3.2.0
info:
  title: Okareo Monitoring API
  version: 0.1.0
  description: Ingest live conversations and receive provider monitoring webhooks.
servers:
- url: https://api.okareo.com
tags:
- name: Monitoring
  description: Ingest live conversations and receive provider monitoring webhooks.
paths:
  /v0/conversations/ingest:
    post:
      tags:
      - Monitoring
      summary: Ingest Conversations
      description: 'Ingest voice conversations for monitoring.


        Accepts one or more custom conversations and enqueues them for async

        processing. Each conversation''s turns will become Datapoint rows, and

        configured monitors will automatically match and run checks.


        This is the monitoring path, not the simulation path. No ScenarioSets are created.

        The mut_id is optional - when omitted, datapoints are created without MUT association

        and rely entirely on monitor/filter group matching.


        Args:

        payload: Conversation data including project_id and conversation list

        request: FastAPI request object for tenant context


        Returns:

        ConversationIngestResponse with status and conversation identifiers'
      operationId: ingest_conversations_v0_conversations_ingest_post
      parameters:
      - name: api-key
        in: header
        required: true
        schema:
          type: string
          title: Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngestPayload'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationIngestResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v0/voice/retell/monitor/{public_id}:
    post:
      tags:
      - Monitoring
      summary: Retell Webhook
      description: Webhook receiver for Retell AI call events.
      operationId: retell_webhook_v0_voice_retell_monitor__public_id__post
      parameters:
      - name: public_id
        in: path
        required: true
        schema:
          type: string
          title: Public Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v0/voice/livekit/monitor/{public_id}:
    post:
      tags:
      - Monitoring
      summary: Livekit Webhook
      description: Webhook receiver for LiveKit egress events.
      operationId: livekit_webhook_v0_voice_livekit_monitor__public_id__post
      parameters:
      - name: public_id
        in: path
        required: true
        schema:
          type: string
          title: Public Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v0/voice/twilio/monitor/{public_id}:
    post:
      tags:
      - Monitoring
      summary: Twilio Monitor Webhook
      description: Webhook receiver for Twilio recording callbacks (monitoring path).
      operationId: twilio_monitor_webhook_v0_voice_twilio_monitor__public_id__post
      parameters:
      - name: public_id
        in: path
        required: true
        schema:
          type: string
          title: Public Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v0/voice/vapi/monitor:
    post:
      tags:
      - Monitoring
      summary: Vapi Webhook
      description: Webhook receiver for VAPI end-of-call-report events.
      operationId: vapi_webhook_v0_voice_vapi_monitor_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v0/voice/elevenlabs/webhook:
    post:
      tags:
      - Monitoring
      summary: Elevenlabs Webhook
      description: Webhook receiver for ElevenLabs post-call events (prio 2).
      operationId: elevenlabs_webhook_v0_voice_elevenlabs_webhook_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
components:
  schemas:
    IngestPayload:
      properties:
        project_id:
          type: string
          format: uuid
          title: Project Id
          description: Okareo project ID
        mut_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Mut Id
          description: Optional model under test ID. If not provided, datapoints are created without a MUT association (monitoring path).
        conversations:
          items:
            $ref: '#/components/schemas/ConversationIngestRequest'
          type: array
          title: Conversations
          description: List of conversations to ingest (1+)
      type: object
      required:
      - project_id
      - conversations
      title: IngestPayload
      description: 'Top-level ingest request with project context.


        This is the monitoring path - conversations are ingested and monitored

        based on filter groups, not associated with a specific MUT like test runs.'
    ConversationIngestRequest:
      properties:
        call_id:
          type: string
          title: Call Id
          description: Platform-specific call identifier
        context_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Context Token
          description: Optional context token for correlation. Defaults to call_id if not provided.
        conversation_start_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Conversation Start At
          description: Absolute conversation start timestamp in UTC. Use this with per-turn timestamp_ms values to derive wall-clock message times.
        audio:
          anyOf:
          - $ref: '#/components/schemas/ConversationAudio'
          - type: 'null'
          description: Audio reference for the conversation. Prefer URL or voice_file_id over inline base64.
        recording_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Recording Url
          description: 'Legacy compatibility field. Prefer audio={type:''url'', url: ...}.'
        recording_bytes_b64:
          anyOf:
          - type: string
          - type: 'null'
          title: Recording Bytes B64
          description: 'Legacy compatibility field. Prefer audio={type:''inline_b64'', inline_b64: ...}.'
        transcript:
          anyOf:
          - items:
              $ref: '#/components/schemas/ConversationTurn'
            type: array
          - type: 'null'
          title: Transcript
          description: Pre-parsed transcript as a list of turns. Optional for audio-only sources.
        diarization:
          type: boolean
          title: Diarization
          description: When transcript is absent, run diarization + ASR on the audio before creating the datapoint.
          default: true
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
          description: Platform-specific metadata
        tags:
          items:
            type: string
          type: array
          title: Tags
          description: Tags for monitor matching
        first_turn:
          type: string
          title: First Turn
          description: 'For audio-only diarization: ''user'' or ''assistant'' spoke first'
          default: assistant
      type: object
      required:
      - call_id
      title: ConversationIngestRequest
      description: Request payload for ingesting voice conversations.
    ConversationTurn:
      properties:
        role:
          type: string
          title: Role
          description: 'Speaker role: ''user'' or ''assistant'''
        content:
          type: string
          title: Content
          description: Text content of the utterance
        timestamp_ms:
          type: integer
          title: Timestamp Ms
          description: Timestamp in milliseconds from conversation start
          default: 0
      type: object
      required:
      - role
      - content
      title: ConversationTurn
      description: A single turn in a conversation (user or assistant utterance).
    ConversationAudio:
      properties:
        type:
          type: string
          enum:
          - url
          - voice_file_id
          - inline_b64
          title: Type
          description: Audio reference type
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
          description: Externally hosted audio URL when type='url'
        voice_file_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Voice File Id
          description: Existing Okareo voice file identifier when type='voice_file_id'
        inline_b64:
          anyOf:
          - type: string
          - type: 'null'
          title: Inline B64
          description: Base64-encoded audio bytes when type='inline_b64'
      type: object
      required:
      - type
      title: ConversationAudio
      description: Audio attachment for a conversation ingest request.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    ConversationIngestResponse:
      properties:
        status:
          type: string
          title: Status
          description: Processing status
          default: accepted
        conversations:
          items:
            additionalProperties:
              type: string
            type: object
          type: array
          title: Conversations
          description: List of call_id and context_token pairs
      type: object
      required:
      - conversations
      title: ConversationIngestResponse
      description: Response after enqueuing conversations for processing.