API Docs — KA Voicemail API

Overview

The KA Voicemail API detects voicemail greetings in real-time audio using Whisper.cpp transcription and phrase matching. Submit audio chunks during a live call — get back a detection decision in under 2 seconds.

Base URL

https://ss.karims.dev

Authentication

All endpoints require authentication via one of the following methods.

key API Key

Send as a header or Bearer token:

X-API-Key: YOUR_API_KEY
— or —
Authorization: Bearer YOUR_API_KEY

lock Basic Auth

Standard HTTP Basic Authentication:

Authorization: Basic base64(username:password)

POST /voicemail

Upload an audio file. Returns real-time voicemail detection result with matched phrases and dead air tracking.

Parameter	Type	Required	Description
audio	file	yes	WAV audio file to analyze
language	string	no	Language code (default: `en`)
decision_window_ms	int	no	Audio duration to analyze in ms (default: `2000`)
session_id	string	no	Unique call identifier for dead air tracking
dead_air_threshold	int	no	Consecutive blank chunks before dead_air=true (default: `3`)

Request

curl -s -X POST https://ss.karims.dev/voicemail \
  -H "X-API-Key: YOUR_KEY" \
  -F "audio=@call.wav" \
  -F "session_id=call-123" \
  -F "decision_window_ms=2000"

Response

{
  "text": "please leave a message",
  "voicemail": true,
  "matched_phrases": ["leave a message"],
  "dead_air": false,
  "session_id": "call-123",
  "language": "en",
  "decision_window_ms": 2000
}

POST /voicemail-json

Send audio as a base64-encoded string in a JSON body. Also supports passing pre-transcribed text directly. Includes DNC (Do Not Call) phrase detection.

Request Body

{
  "audio_base64": "UklGRi...",
  "language": "en",
  "decision_window_ms": 2000,
  "session_id": "call-123",
  "dead_air_threshold": 3,
  "chunk_index": 0
}

Response

{
  "text": "please leave a message",
  "voicemail": true,
  "matched_phrases": ["leave a message"],
  "dnc": false,
  "dnc_phrases": [],
  "dead_air": false,
  "chunk_index": 0
}

POST /transcribe

Transcribe audio to text without voicemail detection. Returns full transcript and segment-level detail.

Request

curl -s -X POST https://ss.karims.dev/transcribe \
  -H "X-API-Key: YOUR_KEY" \
  -F "audio=@audio.wav" \
  -F "language=en"

Response

{
  "text": "Hi, you've reached John...",
  "language": "en",
  "segments": [
    { "text": "Hi, you've reached John." }
  ]
}

GET /health

Returns the API health status. Use this to verify the service is running.

Request

curl https://ss.karims.dev/health

Response

{ "status": "ok" }

monitor_heart View live health dashboard →

Error Codes

Code	Meaning	Description
401	Unauthorized	Missing or invalid API key / Basic Auth credentials.
400	Bad Request	Missing required fields (e.g. no audio file or audio_base64).
500	Internal Server Error	Transcription failed or whisper.cpp encountered an error.