Skip to main content
Use these endpoints when you need speech input, speech output, or transactional email from the gateway.

​
WebSocket /v1/listen

Use this endpoint for live streaming speech-to-text. Auth: required (Authorization: Bearer bos_live_sk_...) Proxy to Deepgram’s live streaming STT. Connect to the gateway with your Basics API key; the gateway handles the upstream connection and keeps provider credentials server-side. URL: wss://api.basicsos.com/v1/listen?model=nova-2&diarize=true&... Use the same query params as Deepgram’s Listen API.
  • Client → gateway: send binary audio frames
  • Gateway → client: receive Deepgram JSON transcript results
  • When either side closes the connection, the other is closed as well

​
POST /v1/audio/transcriptions

Convert speech to text. Auth: required This endpoint supports two input modes, so you can work with browser uploads or direct JSON payloads.

​
Multipart form-data

Recommended for browser uploads.
FieldRequiredNotes
fileYesAudio file from a browser upload or local file
modelNoDefaults to basics-stt
const form = new FormData();
form.append("file", file);
form.append("model", "basics-stt");

const res = await fetch(`${BASE_URL}/v1/audio/transcriptions`, {
  method: "POST",
  headers: { Authorization: `Bearer ${apiKey}` },
  body: form
});

​
JSON with base64 audio

{
  "model": "basics-stt",
  "audio": "<base64-audio>",
  "mime_type": "audio/wav"
}

​
JSON fields

FieldTypeRequiredNotes
modelstringNoDefaults to basics-stt
audiostringYesBase64-encoded audio
mime_typestringNoDefaults to audio/wav

​
Response

Returns provider-specific transcription JSON from Deepgram.

​
POST /v1/audio/speech

Convert text to speech. Auth: required

​
Request body

{
  "model": "basics-tts",
  "input": "Hello from Basics.",
  "voice": "default",
  "encoding": "mp3"
}

​
Response

Returns a binary audio body. Common response headers:
  • Content-Type: provider audio type such as audio/mpeg
  • x-request-id: internal request ID
const res = await fetch(`${BASE_URL}/v1/audio/speech`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "basics-tts",
    input: "Hello from Basics."
  })
});

const blob = await res.blob();
const url = URL.createObjectURL(blob);

​
POST /v1/email/send

Send a simple tenant-scoped text email through Basics. Auth: required. BYOK is not supported.

​
Request body

{
  "to": "user@example.com",
  "subject": "Welcome to Basics",
  "content": "Thanks for signing up!"
}

​
Request fields

FieldTypeRequiredNotes
toemail stringYesRecipient address
subjectstringYesTenant company may be appended
contentstringYesPlain text body

​
Success response

{
  "id": "email_123456",
  "ok": true
}

​
Common errors

  • 503 with code: "service_unavailable" when email is not configured
  • 422 with code: "invalid_payload" for validation errors
  • 4xx or 5xx with code: "email_send_failed" if the Resend call fails