Okareo Voice API

openapi: 3.2.0
info:
  title: Okareo Voice API
  version: 0.1.0
  description: Voice calls, streaming, and observers.
servers:
- url: https://api.okareo.com
tags:
- name: Voice
  description: Voice calls, streaming, and observers.
paths:
  /v0/voice/upload:
    post:
      tags:
      - Voice
      summary: Upload Voice File
      description: 'Upload a base64-encoded audio file (WAV or MP3).


        Files are stored in their original format. Duration is extracted

        from audio headers.'
      operationId: upload_voice_file_v0_voice_upload_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/VoiceUploadRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceUploadResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v0/voice/phone_target_capabilities:
    get:
      tags:
      - Voice
      summary: Phone Target Capabilities
      description: 'What a Phone target may be configured to do, for THIS caller''s org.


        Two different facts, and the form needs both:


        ``rfc2833_dtmf`` -- may this org choose out-of-band DTMF at all. True for

        everyone now; only the master kill switch takes it away.


        ``default_dtmf_mechanism`` -- what a target that states no preference

        actually does. Telnyx/``rfc2833`` for most organizations, ``inband`` for

        those kept on Twilio by ``TWILIO_DEFAULT_ORG_IDS``. The form must render

        this as its default rather than assuming in-band, or it will show "In-band"

        for a target that in fact dials out-of-band.


        Keep this route even if the switches are eventually retired. The app gates

        the control on ``rfc2833_dtmf === true`` and fails closed, so a 404 here

        hides the control from everybody -- the opposite of enabling it.


        Advisory only. The server validates the opt-in again at run submit

        (``validate_dtmf_mechanism``); hiding a control is not enforcement.'
      operationId: phone_target_capabilities_v0_voice_phone_target_capabilities_get
      parameters:
      - name: api-key
        in: header
        required: true
        schema:
          type: string
          title: Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Phone Target Capabilities V0 Voice Phone Target Capabilities Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v0/voice/active_calls:
    get:
      tags:
      - Voice
      summary: List Active Calls
      description: Return live Twilio + Vonage calls visible to the caller's org.
      operationId: list_active_calls_v0_voice_active_calls_get
      parameters:
      - name: api-key
        in: header
        required: true
        schema:
          type: string
          title: Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ActiveCallItem'
                title: Response List Active Calls V0 Voice Active Calls Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v0/voice/active_calls/{call_sid}:
    get:
      tags:
      - Voice
      summary: Get Active Call
      description: 'Lookup a single live call by CallSid.


        TODO: Vonage entries are keyed in Redis by correlation id (`vonage_edge:{corr}`),

        not by call UUID, so there''s no direct `vonage_edge:{call_sid}` key to fetch the

        way there is for Twilio. A Vonage call_id -> corr reverse index (or a full

        `vonage_edge:*` scan + filter) would be needed to support this lookup for Vonage;

        out of scope for this pass -- Twilio-keyed lookups are unaffected.'
      operationId: get_active_call_v0_voice_active_calls__call_sid__get
      parameters:
      - name: call_sid
        in: path
        required: true
        schema:
          type: string
          title: Call Sid
      - name: api-key
        in: header
        required: true
        schema:
          type: string
          title: Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActiveCallItem'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v0/voice/file/{project_id}/{file_id}:
    get:
      tags:
      - Voice
      summary: Download File
      operationId: download_file_v0_voice_file__project_id___file_id__get
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Project Id
      - name: file_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: File Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v0/voice/call_sid/{call_sid}:
    get:
      tags:
      - Voice
      summary: Download File By Call Sid
      description: 'Download a voice recording by call_sid.


        This endpoint allows the UI to fetch recordings using just the call_sid

        from the datapoint metadata, without needing to know the file_id.


        Args:

        call_sid: Twilio CallSid (e.g., "CA1234567890abcdef")


        Returns:

        StreamingResponse with the audio file (WAV format)


        Raises:

        HTTPException 404: If no recording found for the call_sid'
      operationId: download_file_by_call_sid_v0_voice_call_sid__call_sid__get
      parameters:
      - name: call_sid
        in: path
        required: true
        schema:
          type: string
          title: Call Sid
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v0/voice/twilio/testtarget:
    post:
      tags:
      - Voice
      summary: Twilio Inbound Webhook
      operationId: twilio_inbound_webhook_v0_voice_twilio_testtarget_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v0/voice/twilio/testtarget/ivr:
    post:
      tags:
      - Voice
      summary: Twilio Inbound Webhook Ivr
      operationId: twilio_inbound_webhook_ivr_v0_voice_twilio_testtarget_ivr_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v0/voice/twilio/testtarget/ivr/dtmf/{call_sid}:
    get:
      tags:
      - Voice
      summary: Testtarget Ivr Dtmf
      description: 'Read back the DTMF an IVR-route call decoded (the test asserts on this).


        Requires an Okareo api-key: unlike the sibling webhook/ws routes (which

        Twilio must reach keyless), this read-back is excluded from the testtarget

        middleware bypass so the captured digits -- and the global ``latest`` pointer

        below -- are not world-readable (SRV-5).'
      operationId: testtarget_ivr_dtmf_v0_voice_twilio_testtarget_ivr_dtmf__call_sid__get
      parameters:
      - name: call_sid
        in: path
        required: true
        schema:
          type: string
          title: Call Sid
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v0/voice/observer/register:
    post:
      tags:
      - Voice
      summary: Observer Register
      description: 'Attach a Twilio Stream subresource to a live call.


        Pre-registers the observer in the in-memory registry so the WS handler

        can recognize the inbound `start` frame, then calls Twilio''s Streams

        REST API to create the subresource. On Twilio failure the registration

        is rolled back so a retry can re-attempt cleanly.


        The caller''s org is verified against the call''s org (from the

        ``twilio_edge:{call_sid}`` Redis key) so clients can only observe

        calls belonging to their own account.'
      operationId: observer_register_v0_voice_observer_register_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/ObserverRegisterRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObserverRegisterResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v0/voice/observer/unregister/{call_sid}:
    post:
      tags:
      - Voice
      summary: Observer Unregister
      description: Stop the Twilio Stream subresource and drop local state.
      operationId: observer_unregister_v0_voice_observer_unregister__call_sid__post
      parameters:
      - name: call_sid
        in: path
        required: true
        schema:
          type: string
          title: Call Sid
      - name: api-key
        in: header
        required: true
        schema:
          type: string
          title: Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
                title: Response Observer Unregister V0 Voice Observer Unregister  Call Sid  Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v0/voice/observer/status:
    get:
      tags:
      - Voice
      summary: Observer Status
      description: Observer-specific state. Process liveness is covered by Okareo health.
      operationId: observer_status_v0_voice_observer_status_get
      parameters:
      - name: api-key
        in: header
        required: true
        schema:
          type: string
          title: Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObserverStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v0/voice/observer/twilio/stream_status:
    post:
      tags:
      - Voice
      summary: Observer Twilio Stream Status
      description: 'Twilio Stream subresource statusCallback receiver.


        Twilio POSTs `stream-started`, `stream-stopped`, `stream-error` here.

        On `stream-stopped`/`stream-error` we mark the registration as

        not-streaming but do NOT delete it -- the Redis TTL handles expiry,

        and keeping the registration alive allows Twilio reconnects (Cloud Run

        60-min WS timeout) to find it on any node.'
      operationId: observer_twilio_stream_status_v0_voice_observer_twilio_stream_status_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
                title: Response Observer Twilio Stream Status V0 Voice Observer Twilio Stream Status Post
components:
  schemas:
    VoiceUploadResponse:
      properties:
        file_id:
          type: string
          format: uuid
          title: File Id
          description: Unique identifier for the uploaded audio.
        file_url:
          type: string
          title: File Url
          description: Link to access the uploaded audio file.
        file_duration:
          type: number
          title: File Duration
          description: Duration of the audio file in milliseconds.
        time_created:
          type: string
          format: date-time
          title: Time Created
          description: Timestamp indicating when audio file was created.
      type: object
      required:
      - file_id
      - file_url
      - file_duration
      - time_created
      title: VoiceUploadResponse
    VoiceUploadRequest:
      properties:
        project_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Project Id
          description: ID of the project to associate the audio file with.
        audio:
          type: string
          title: Audio
          description: Audio file (.wav) in base64-encoded bytes.
      type: object
      required:
      - audio
      title: VoiceUploadRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ObserverStatusResponse:
      properties:
        registered_observers:
          type: integer
          title: Registered Observers
        actively_streaming:
          type: integer
          title: Actively Streaming
      type: object
      required:
      - registered_observers
      - actively_streaming
      title: ObserverStatusResponse
    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
    ObserverRegisterRequest:
      properties:
        call_sid:
          type: string
          title: Call Sid
          description: Twilio CallSid for the live call
        twilio_account_sid:
          anyOf:
          - type: string
          - type: 'null'
          title: Twilio Account Sid
          description: Twilio AccountSid (falls back to TWILIO_ACCOUNT_SID env var)
        twilio_auth_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Twilio Auth Token
          description: Twilio Auth Token (falls back to TWILIO_AUTH_TOKEN env var)
        keyword_patterns:
          items:
            type: string
          type: array
          title: Keyword Patterns
          description: Regex patterns to match against transcript.final text
        entity_types:
          items:
            type: string
          type: array
          title: Entity Types
          description: spaCy NER labels to surface as entity.detected events (e.g. ORG, PERSON, PRODUCT, MONEY)
        enable_svd:
          type: boolean
          title: Enable Svd
          description: Enable Modulate synthetic voice detection (requires MODULATE_API_KEY on server)
          default: false
      type: object
      required:
      - call_sid
      title: ObserverRegisterRequest
    ObserverRegisterResponse:
      properties:
        call_sid:
          type: string
          title: Call Sid
        twilio_stream_subresource_sid:
          type: string
          title: Twilio Stream Subresource Sid
        status:
          type: string
          title: Status
          default: registered
      type: object
      required:
      - call_sid
      - twilio_stream_subresource_sid
      title: ObserverRegisterResponse
    ActiveCallItem:
      properties:
        call_sid:
          type: string
          title: Call Sid
        stream_sid:
          anyOf:
          - type: string
          - type: 'null'
          title: Stream Sid
        task_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Task Id
        job_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Job Id
        org_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Org Id
        project_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Project Id
        registered_at:
          type: number
          title: Registered At
          default: 0.0
      type: object
      required:
      - call_sid
      title: ActiveCallItem