Skip to content

API Endpoints

Schakel exposes a minimal API: one HTTP endpoint for health checks and one WebSocket endpoint for the voice pipeline.

Health Check

GET /

Returns the service status.

Response (200 OK):

{
  "status": "online",
  "service": "Schakel Voice"
}

Audio WebSocket

WS /ws/audio

Real-time voice pipeline. This is the primary interface for voice satellites.

Protocol

The WebSocket exchanges raw binary frames -- no JSON wrapping, no headers, just PCM bytes.

Audio format: 16-bit PCM, 16 kHz, mono (little-endian).

Client sends: Raw audio chunks from the microphone. The chunk size is flexible -- the server buffers internally.

Server sends: Raw audio bytes (TTS response) after the full pipeline completes. The client should play these bytes directly through the speaker.

Pipeline Behavior

  1. The server enters LISTENING state on connection.
  2. Audio chunks are fed to the wake word detector. All audio is discarded until the wake word triggers.
  3. On wake word detection, the server enters RECORDING state.
  4. Audio is buffered for 3 seconds (96,000 bytes at 16 kHz, 16-bit mono).
  5. The buffered audio runs through the full pipeline: STT -> intent classification -> agent dispatch -> TTS.
  6. The synthesized audio response is sent back as a binary WebSocket frame.
  7. The server resets to LISTENING state.

Connection Example

import asyncio
import websockets

async def stream_audio():
    async with websockets.connect("ws://localhost:8000/ws/audio") as ws:
        # Send audio chunks (e.g., from a microphone)
        while True:
            chunk = read_from_microphone()  # 16-bit PCM, 16 kHz, mono
            await ws.send(chunk)

            # Check for response audio
            try:
                response = await asyncio.wait_for(ws.recv(), timeout=0.1)
                play_audio(response)  # Play through speaker
            except asyncio.TimeoutError:
                pass

Interactive Docs

When the server is running, FastAPI auto-generates interactive API documentation:

  • Swagger UI: http://localhost:8000/docs
  • ReDoc: http://localhost:8000/redoc
  • OpenAPI JSON: http://localhost:8000/openapi.json

Note

The WebSocket endpoint is not shown in the OpenAPI docs due to OpenAPI specification limitations. The HTTP health check endpoint is fully documented there.