asyncapi: 3.0.0
info:
  title: SLNG Gateway API - Sarvam AI STT
  version: 0.1.0
  description: SLNG Gateway API
  contact:
    name: SLNG Support
    url: https://slng.ai
    email: support@slng.ai
  license:
    name: Proprietary
  tags:
    - name: STT
      description: Speech-to-Text services
servers:
  production:
    host: api.slng.ai
    protocol: wss
    description: Production
    security:
      - $ref: "#/components/securitySchemes/bearer"
  staging:
    host: stageapi.slng.ai
    protocol: wss
    description: Staging
    security:
      - $ref: "#/components/securitySchemes/bearer"
channels:
  /v1/stt/sarvam/saaras:v3:
    address: /v1/stt/sarvam/saaras:v3
    title: Saaras v3
    summary: Saaras v3
    description: "Stream real-time speech-to-text transcripts from Sarvam AI Saaras v3 over WebSocket with voice activity detection across 23 Indian languages. Session configuration is provided via query parameters on the WebSocket upgrade URL: `language-code`, `mode`, `sample_rate`, `input_audio_codec`, `high_vad_sensitivity`, `vad_signals`."
    tags:
      - name: Sarvam AI Saaras
    servers:
      - $ref: "#/servers/production"
      - $ref: "#/servers/staging"
    messages:
      SarvamSaarasV3AudioFrame:
        $ref: "#/components/messages/SarvamSaarasV3AudioFrame"
      SarvamSaarasV3FlushSignal:
        $ref: "#/components/messages/SarvamSaarasV3FlushSignal"
      SarvamSaarasV3TranscriptMessage:
        $ref: "#/components/messages/SarvamSaarasV3TranscriptMessage"
      SarvamSaarasV3EventsMessage:
        $ref: "#/components/messages/SarvamSaarasV3EventsMessage"
      SarvamSaarasV3ErrorMessage:
        $ref: "#/components/messages/SarvamSaarasV3ErrorMessage"
    bindings:
      ws:
        method: GET
        headers:
          $ref: "#/components/schemas/WebsocketHeadersSarvamSaarasV3"
operations:
  sttSarvamSaarasV3ReceiveAudio:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1stt~1sarvam~1saaras:v3"
    summary: Send audio frame to Saaras v3
    messages:
      - $ref: "#/channels/~1v1~1stt~1sarvam~1saaras:v3/messages/SarvamSaarasV3AudioFrame"
    description: Send an audio frame to Saaras v3 as a JSON message with base64-encoded PCM/WAV data.
    tags: []
  sttSarvamSaarasV3ReceiveFlush:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1stt~1sarvam~1saaras:v3"
    summary: Force-finalize buffered audio on Saaras v3
    messages:
      - $ref: "#/channels/~1v1~1stt~1sarvam~1saaras:v3/messages/SarvamSaarasV3FlushSignal"
    description: Force the server to finalize buffered audio and emit a final transcript. The connection stays open for further audio.
    tags: []
  sttSarvamSaarasV3SendData:
    action: send
    channel:
      $ref: "#/channels/~1v1~1stt~1sarvam~1saaras:v3"
    summary: Receive transcript from Saaras v3
    messages:
      - $ref: "#/channels/~1v1~1stt~1sarvam~1saaras:v3/messages/SarvamSaarasV3TranscriptMessage"
    description: Receive a final transcript chunk from Saaras v3 after voice activity detection identifies an utterance boundary or after a flush signal.
    tags: []
  sttSarvamSaarasV3SendEvents:
    action: send
    channel:
      $ref: "#/channels/~1v1~1stt~1sarvam~1saaras:v3"
    summary: Receive VAD events from Saaras v3
    messages:
      - $ref: "#/channels/~1v1~1stt~1sarvam~1saaras:v3/messages/SarvamSaarasV3EventsMessage"
    description: Receive voice activity detection events (START_SPEECH or END_SPEECH) emitted by Saaras v3 when `vad_signals` is enabled on the upgrade query string.
    tags: []
  sttSarvamSaarasV3SendError:
    action: send
    channel:
      $ref: "#/channels/~1v1~1stt~1sarvam~1saaras:v3"
    summary: Receive error from Saaras v3
    messages:
      - $ref: "#/channels/~1v1~1stt~1sarvam~1saaras:v3/messages/SarvamSaarasV3ErrorMessage"
    description: Receive an error from Saaras v3 or the gateway when the request is malformed or the upstream session fails.
    tags: []
components:
  schemas:
    WebsocketHeadersSarvamSaarasV3:
      type: object
      properties:
        X-World-Part-Override:
          type: string
          description: "Target world part override. Auto-selected if not provided. Available world parts: `ap`."
          enum:
            - ap
  messages:
    SarvamSaarasV3AudioFrame:
      name: SarvamSaarasV3AudioFrame
      title: Audio Frame
      summary: Stream a base64-encoded audio chunk to Saaras v3 as a JSON message.
      contentType: application/json
      payload:
        type: object
        description: Audio frame envelope expected by Saaras v3. Send a JSON message whose `audio.data` is a base64-encoded PCM/WAV chunk together with the sample rate and encoding. The gateway forwards the frame to Sarvam after normalizing `encoding` values to `audio/wav` when the source is raw PCM.
        required:
          - audio
        properties:
          audio:
            type: object
            required:
              - data
              - sample_rate
              - encoding
            properties:
              data:
                type: string
                format: byte
                description: Base64-encoded audio bytes for this chunk. At 16 kHz linear16, a ~256 ms chunk is roughly 8192 bytes before base64.
              sample_rate:
                type: integer
                description: Sample rate of the audio in Hz.
                default: 16000
              encoding:
                type: string
                description: Encoding of the audio bytes. Raw PCM variants are normalized to `audio/wav` before being forwarded to Sarvam.
                default: wav
                enum:
                  - wav
                  - linear16
                  - LINEAR16
                  - pcm_s16le
                  - pcm_l16
                  - pcm_raw
                  - audio/wav
      examples:
        - name: sarvamSaarasV3AudioHi
          summary: Stream a Hindi audio chunk
          payload:
            audio:
              data: UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAEAfAAABAAgAZGF0YQAAAAA=
              sample_rate: 16000
              encoding: wav
    SarvamSaarasV3FlushSignal:
      name: SarvamSaarasV3FlushSignal
      title: Flush Signal
      summary: Force-finalize buffered audio without closing the connection.
      contentType: application/json
      payload:
        type: object
        description: Mid-stream flush. The gateway translates this to Saaras's `finalize` control message so the server emits a final transcript for the audio buffered so far. The WebSocket stays open for further audio.
        required:
          - type
        properties:
          type:
            type: string
            const: flush
      examples:
        - name: sarvamSaarasV3Flush
          summary: Force-finalize the current utterance
          payload:
            type: flush
    SarvamSaarasV3TranscriptMessage:
      name: SarvamSaarasV3TranscriptMessage
      title: Transcript
      summary: Saaras v3 final transcript chunk for the most recent utterance.
      contentType: application/json
      payload:
        type: object
        description: Final transcript event emitted by Saaras v3 after an utterance ends or after a flush. Saaras v3 emits final transcripts only — there are no partial/interim results on this channel.
        required:
          - type
          - data
        properties:
          type:
            type: string
            const: data
          data:
            type: object
            required:
              - transcript
            properties:
              transcript:
                type: string
                description: Transcribed text for the utterance, in the language determined by the `language-code` query parameter.
      examples:
        - name: sarvamSaarasV3TranscriptTe
          summary: Final Telugu transcript
          payload:
            type: data
            data:
              transcript: నమస్తే ఇది తెలుగు పరీక్ష
        - name: sarvamSaarasV3TranscriptHi
          summary: Final Hindi transcript
          payload:
            type: data
            data:
              transcript: नमस्ते, आज आप कैसे हैं?
    SarvamSaarasV3EventsMessage:
      name: SarvamSaarasV3EventsMessage
      title: VAD Event
      summary: Voice activity detection signal from Saaras v3.
      contentType: application/json
      payload:
        type: object
        description: Voice activity event emitted when `vad_signals=true` is set on the upgrade query string. `START_SPEECH` marks the start of an utterance and `END_SPEECH` marks the end.
        required:
          - type
          - data
        properties:
          type:
            type: string
            const: events
          data:
            type: object
            required:
              - signal_type
            properties:
              signal_type:
                type: string
                description: Which VAD boundary this event marks.
                enum:
                  - START_SPEECH
                  - END_SPEECH
              occured_at:
                type: string
                format: date-time
                description: ISO-8601 timestamp at which Saaras observed the boundary.
      examples:
        - name: sarvamSaarasV3EventEndSpeech
          summary: End-of-utterance marker
          payload:
            type: events
            data:
              signal_type: END_SPEECH
              occured_at: 2026-05-18T12:50:56.000Z
        - name: sarvamSaarasV3EventStartSpeech
          summary: Start-of-utterance marker
          payload:
            type: events
            data:
              signal_type: START_SPEECH
              occured_at: 2026-05-18T12:50:54.000Z
    SarvamSaarasV3ErrorMessage:
      name: SarvamSaarasV3ErrorMessage
      title: Error
      summary: Error from Saaras v3 or the SLNG gateway.
      contentType: application/json
      payload:
        type: object
        description: Error message from the upstream Sarvam session or from the SLNG gateway when a request is malformed, an authentication or quota check fails, or the upstream socket disconnects unexpectedly.
        required:
          - type
          - data
        properties:
          type:
            type: string
            const: error
          data:
            type: object
            required:
              - message
            properties:
              message:
                type: string
                description: Human-readable error description.
              code:
                type: string
                description: Optional machine-readable error code when the failure originates from the gateway.
      examples:
        - name: sarvamSaarasV3ErrorInvalidPayload
          summary: Upstream rejected the audio payload
          payload:
            type: error
            data:
              message: Invalid audio payload
        - name: sarvamSaarasV3ErrorBackendConnection
          summary: Gateway could not reach Sarvam
          payload:
            type: error
            data:
              message: "Failed to connect to backend: 502 Bad Gateway"
              code: backend_connection_failed
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: |
        API key issued by SLNG. Pass as `Authorization: Bearer <token>` in the WebSocket upgrade request headers.