REST API

All discovery and health endpoints are public — no API key required. For a human-readable catalog of voices, languages, and models, see Voices, Languages & Models. The base URL is derived from your WebSocket endpoint by replacing wss:// with https://:

Environment	WebSocket	REST Base
Production	`wss://api.lokutor.com/ws/agent`	`https://api.lokutor.com`
Local	`ws://localhost:8080/ws/agent`	`http://localhost:8080`

The JavaScript SDK converts this automatically via VoiceAgentClient.fetchVoices() and siblings.

`GET /health` — Admin Dashboard Health

This is the admin dashboard’s health/status page, not a lightweight liveness probe — for automated health checks, use /ready below instead, which is what’s actually unauthenticated and probe-friendly. Returns the dashboard’s HTML status page by default. Pass Accept: application/json or ?format=json to get JSON instead:

{
  "status": "healthy",
  "version": "1.0.0",
  "usage": { },
  "events": { },
  "companies": [ ],
  "db_companies": 0,
  "db_api_keys": 0,
  "config": { "elastic_pool": 0, "desired_headroom": 0, "max_replicas": 0 }
}

If DASHBOARD_PASSWORD is set on the server, this endpoint requires HTTP Basic Auth (admin / the configured password) for all callers except Kubernetes probes (matched by a kube-probe User-Agent).

cURL

curl -s -H "Accept: application/json" https://api.lokutor.com/health | jq .

`GET /ready` — Readiness Probe

Returns 200 when the TTS engine is warmed up and ready to accept synthesis requests. Returns 503 during startup.

Response (200)

{
  "ready": true,
  "status": "ready"
}

Response (503)

{
  "ready": false,
  "status": "not_ready"
}

`GET /voices` — List Voice Styles

Returns all available voice styles with a display name, inferred gender, and the full list of supported languages (currently identical across all voices — every voice supports every language below).

Response

{
  "voices": [
    {
      "id": "F1",
      "name": "Claire",
      "gender": "female",
      "languages": ["en", "es", "ca", "gl", "eu", "pt", "fr", "it", "de"]
    },
    {
      "id": "M1",
      "name": "James",
      "gender": "male",
      "languages": ["en", "es", "ca", "gl", "eu", "pt", "fr", "it", "de"]
    }
  ]
}

Field	Type	Description
`id`	`string`	Voice identifier, e.g. `F1`, `M3`. Call `GET /voices` for the current list rather than hard-coding one.
`name`	`string`	Display name, e.g. “Claire”. Any voice can speak any supported language.
`gender`	`string`	`"female"`, `"male"`, or omitted if unknown
`languages`	`string[]`	ISO codes this voice can speak — all nine supported languages, since the model is zero-shot and a voice is a timbre rather than a language.

GET /voices lists the built-in voices only. Your cloned voices are yours alone: they are listed in the dashboard under Voices, each with its clone_… id, and any endpoint that takes a voice accepts one of them only from an API key on the account that created it. From any other account a clone_… id is answered as an unrecognised voice (validation.invalid_voice).

`GET /languages` — List Supported Languages

Returns every language code and display name that text-to-speech can speak. Nine languages are supported today. Speech recognition, which voice agents and the speech-to-text API use to understand a caller, covers six of them: English, Spanish, Portuguese, French, Italian and German. Catalan, Galician and Basque are speak-only for now.

Response

{
  "languages": [
    { "code": "en", "name": "English" },
    { "code": "es", "name": "Spanish" },
    { "code": "ca", "name": "Catalan" },
    { "code": "gl", "name": "Galician" },
    { "code": "eu", "name": "Basque" },
    { "code": "pt", "name": "Portuguese" },
    { "code": "fr", "name": "French" },
    { "code": "it", "name": "Italian" },
    { "code": "de", "name": "German" }
  ]
}

That is the complete list.

`GET /models` — List TTS Models

Returns all loaded TTS model versions, including the default model.

Response

{
  "models": [
    {
      "name": "versa-2.0",
      "description": "Primary production model",
      "default": true
    }
  ]
}

versa-1.0 has been retired and is no longer served — versa-2.0 is the only model this endpoint returns.

Field	Type	Description
`name`	`string`	Model version identifier
`description`	`string`	Human-readable description
`default`	`boolean`	`true` for the primary production model

`GET /config` — Server Configuration

Returns runtime limits such as max text length, speed range, steps range, and audio format.

Response

{
  "max_text_length": 5000,
  "min_speed": 0.5,
  "max_speed": 2.0,
  "min_steps": 1,
  "max_steps": 128,
  "sample_rate": 44100,
  "channels": 1
}

Field	Type	Description
`max_text_length`	`integer`	Maximum input text length (characters)
`min_speed`	`number`	Minimum speech speed multiplier
`max_speed`	`number`	Maximum speech speed multiplier
`min_steps`	`integer`	Minimum diffusion steps
`max_steps`	`integer`	Maximum value this endpoint accepts without a `400` — not the range that has any effect. On `POST /tts/synthesize` a value above `8` is treated as `8` (see Steps / quality).
`sample_rate`	`integer`	Output audio sample rate (Hz)
`channels`	`integer`	Output audio channels (`1` = mono)

Use these values to validate synthesis requests client-side before sending them over the WebSocket.

`GET /status` — Runtime Status

Returns detailed runtime information including memory usage, active connections, uptime, and readiness state.

Response

{
  "status": "ok",
  "timestamp": "2026-04-29T16:31:23.955Z",
  "version": "1.1.0",
  "runtime": "go1.24.10",
  "inference": "cpu",
  "uptime_seconds": 17,
  "goroutines": 61,
  "mem_alloc_bytes": 73432552,
  "active_connections": 0,
  "failed_requests": 0,
  "ready": true
}

Field	Type	Description
`status`	`string`	`"ok"` or `"warming_up"`
`timestamp`	`string`	ISO 8601 timestamp
`version`	`string`	Server version from `VERSION` env var
`runtime`	`string`	Go runtime version
`inference`	`string`	`"cpu"` or `"gpu"`
`uptime_seconds`	`integer`	Seconds since server start
`goroutines`	`integer`	Current Go routine count
`mem_alloc_bytes`	`integer`	Allocated heap memory
`active_connections`	`integer`	Active WebSocket connections
`failed_requests`	`integer`	Total failed requests since start
`ready`	`boolean`	Whether the engine is warmed up

`GET /v1/pricing` — Rate Card

Every price Lokutor charges, as JSON, public and without a key. Fields and an example are on the Rate Card page; how the prices apply is in Pricing and billing.

JavaScript SDK

The SDK provides static methods on VoiceAgentClient for all discovery endpoints. They automatically convert wss:// to https:// and handle JSON parsing and errors.

import { VoiceAgentClient } from '@lokutor/sdk';

// All methods are static, no instance required
const voices = await VoiceAgentClient.fetchVoices();
const languages = await VoiceAgentClient.fetchLanguages();
const models = await VoiceAgentClient.fetchModels();
const config = await VoiceAgentClient.fetchConfig();
const status = await VoiceAgentClient.fetchStatus();
const health = await VoiceAgentClient.fetchHealth();

// Custom base URL (auto-converts wss->https)
const localVoices = await VoiceAgentClient.fetchVoices('ws://localhost:8080/ws/agent');

Each method returns a typed Promise and throws LokutorError on failure:

import { isRetryable } from '@lokutor/sdk';

try {
  const cfg = await VoiceAgentClient.fetchConfig();
  console.log('Max text length:', cfg.max_text_length);
} catch (err) {
  if (isRetryable(err)) {
    console.warn('Server warming up, retrying...');
  } else {
    console.error('Fatal:', err.message);
  }
}

TypeScript Types

import type {
  VoiceInfo,
  LanguageInfo,
  ModelInfo,
  ServerConfig,
  ServerStatus,
  HealthStatus,
} from '@lokutor/sdk';

cURL Examples

# Liveness/readiness (unauthenticated, probe-friendly)
curl -s https://api.lokutor.com/ready | jq .

# Voices
curl -s https://api.lokutor.com/voices | jq .

# Config (use for client-side validation)
curl -s https://api.lokutor.com/config | jq .

# Status
curl -s https://api.lokutor.com/status | jq .

# Rate card (prices, public)
curl -s https://api.lokutor.com/v1/pricing | jq .

`POST /tts/synthesize` — TTS Synthesis

Synthesize speech from text. Returns a WAV audio file.

Request

Requires authentication via Authorization: Bearer or X-API-Key header.

{
  "text": "Hello, world!",
  "voice": "F1",
  "speed": 1.0,
  "language": "en",
  "steps": 4
}

Parameter	Type	Required	Default	Description
`text`	`string`	Yes	—	Text to synthesize. `400` if empty.
`voice`	`string`	Yes	—	Voice ID (e.g. `F1`, `M2`). `400` if empty — unlike the WebSocket endpoints, this one won’t silently fall back to an unstyled voice.
`speed`	`float`	No	`1.0`	Speed multiplier. Out-of-range values (outside 0.5–2.0) are silently reset to `1.0` rather than rejected — this endpoint does not return `validation.speed_out_of_range` the way the WebSocket endpoints do.
`language`	`string`	No	none (language-agnostic)	ISO language code. If omitted, synthesis proceeds language-agnostic rather than defaulting to English — pass it explicitly for predictable results.
`steps`	`int`	No	`4` (fixed)	Denoising steps. Accepted (`1`–`8`; a higher value is treated as `8`) but has no effect: the current voice model runs a fixed `4`. See Steps / quality.
`segments`	`array`	No	—	Multi-speaker segments (see below)

Multi-speaker segments — each segment has its own voice, text, speed, language, and optional pause_ms.

Same vocabulary as the SDK and WebSocket API. voice, language, speed, and steps are identical across REST, WebSocket, and both SDKs. The older voice_id, lang, and quality names are still accepted as deprecated aliases (quality maps to steps: ultra_fast=8, fast=16, medium=32, high=64), so existing integrations keep working — but new code should use the canonical names above.

Response

Content-Type: audio/wav — PCM16, 44.1 kHz, mono.

cURL

curl -X POST https://api.lokutor.com/tts/synthesize \
  -H "Authorization: Bearer sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world", "voice": "F1"}'

`POST /stt/transcribe` — Speech-to-Text

One-shot transcription of a complete audio clip. For continuous/live transcription with automatic utterance detection, use WS /ws/stt instead — see the SDK’s Speech-to-Text guide.

Request

Requires authentication via Authorization: Bearer or X-API-Key header. Accepts either multipart/form-data (an audio file field) or JSON with base64-encoded audio.

{
  "audio": "<base64-encoded PCM16 or WAV>",
  "format": "wav",
  "sample_rate": 16000,
  "language": "en"
}

Parameter	Type	Default	Description
`audio`	`string`	—	Base64-encoded audio (JSON mode only — use the `audio` form field for multipart)
`format`	`string`	`"wav"`	`"wav"` or `"pcm16"`
`sample_rate`	`int`	`16000`	Required for `"pcm16"`; ignored for WAV (read from the file header)
`language`	`string`	`"en"`	ISO language code. The older `lang` name is still accepted as a deprecated alias.

Response

{
  "text": "Hello, this is a test.",
  "latency_ms": 240,
  "engine": "parakeet",
  "sample_rate": 16000,
  "language": "en",
  "duration_seconds": 2.1,
  "segments": [
    { "text": "Hello, this is a test.", "start": 0.0, "end": 2.1, "duration": 2.1 }
  ]
}

engine is "parakeet" on the normal path, or "whisper" if this deployment is falling back to the local Whisper model. Audio at any sample rate is resampled correctly — 44.1kHz (this API’s own TTS output) works the same as 16kHz.

cURL

curl -X POST https://api.lokutor.com/stt/transcribe \
  -H "Authorization: Bearer sk_your_key_here" \
  -F "[email protected]" \
  -F "language=en"

`POST /denoise` — Audio Denoising

Removes background noise from a WAV audio file.

Request

Requires authentication via Authorization: Bearer or X-API-Key header (an API key or a Supabase session token both work). Send as multipart/form-data with the WAV file in a field named audio. 16-bit PCM WAV only.

curl -X POST https://api.lokutor.com/denoise \
  -H "Authorization: Bearer sk_your_key_here" \
  -F "[email protected]"

Response

Content-Type: audio/wav — denoised audio, 16-bit PCM.

Observability Endpoints

Method	Path	Auth	Description
`GET`	`/metrics`	No	Prometheus metrics exposure
`GET`	`/docs/`	No	Swagger UI (dev only)
`GET`	`/debug/info`	No	Runtime debug info
`GET`	`/debug/logs`	No	Recent log tail
`GET`	`/debug/stream`	No	Streaming debug output

Note: /docs/ is intended for development environments only. Do not expose it through production ingress.

WebSocket Protocol — Real-time streaming API
Streaming API — TTS synthesis endpoint
Voice Chat — Conversational agent endpoint
JavaScript SDK Reference — SDK methods and types

Get Started

SDK

API Reference

Resources

`GET /health` — Admin Dashboard Health

cURL

`GET /ready` — Readiness Probe

Response (200)

Response (503)

`GET /voices` — List Voice Styles

Response

`GET /languages` — List Supported Languages

Response

`GET /models` — List TTS Models

Response

`GET /config` — Server Configuration

Response

`GET /status` — Runtime Status

Response

`GET /v1/pricing` — Rate Card

JavaScript SDK

TypeScript Types

cURL Examples

`POST /tts/synthesize` — TTS Synthesis

Request

Response

cURL

`POST /stt/transcribe` — Speech-to-Text

Request

Response

cURL

`POST /denoise` — Audio Denoising

Request

Response

Observability Endpoints

​GET /health — Admin Dashboard Health

​cURL

​GET /ready — Readiness Probe

​Response (200)

​Response (503)

​GET /voices — List Voice Styles

​Response

​GET /languages — List Supported Languages

​Response

​GET /models — List TTS Models

​Response

​GET /config — Server Configuration

​Response

​GET /status — Runtime Status

​Response

​GET /v1/pricing — Rate Card

​JavaScript SDK

​TypeScript Types

​cURL Examples

​POST /tts/synthesize — TTS Synthesis

​Request

​Response

​cURL

​POST /stt/transcribe — Speech-to-Text

​Request

​Response

​cURL

​POST /denoise — Audio Denoising

​Request

​Response

​Observability Endpoints

​Related Pages

`GET /health` — Admin Dashboard Health

cURL

`GET /ready` — Readiness Probe

Response (200)

Response (503)

`GET /voices` — List Voice Styles

Response

`GET /languages` — List Supported Languages

Response

`GET /models` — List TTS Models

Response

`GET /config` — Server Configuration

Response

`GET /status` — Runtime Status

Response

`GET /v1/pricing` — Rate Card

JavaScript SDK

TypeScript Types

cURL Examples

`POST /tts/synthesize` — TTS Synthesis

Request

Response

cURL

`POST /stt/transcribe` — Speech-to-Text

Request

Response

cURL

`POST /denoise` — Audio Denoising

Request

Response

Observability Endpoints

Related Pages