Audio and email

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.

Field	Required	Notes
`file`	Yes	Audio file from a browser upload or local file
`model`	No	Defaults 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

Field	Type	Required	Notes
`model`	string	No	Defaults to `basics-stt`
`audio`	string	Yes	Base64-encoded audio
`mime_type`	string	No	Defaults 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

Field	Type	Required	Notes
`to`	email string	Yes	Recipient address
`subject`	string	Yes	Tenant company may be appended
`content`	string	Yes	Plain 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

Overview

Public API

WebSocket `/v1/listen`

POST `/v1/audio/transcriptions`

Multipart form-data

JSON with base64 audio

JSON fields

Response

POST `/v1/audio/speech`

Request body

Response

POST `/v1/email/send`

Request body

Request fields

Success response

Common errors

​WebSocket /v1/listen

​POST /v1/audio/transcriptions

​Multipart form-data

​JSON with base64 audio

​JSON fields

​Response

​POST /v1/audio/speech

​Request body

​Response

​POST /v1/email/send

​Request body

​Request fields

​Success response

​Common errors

WebSocket `/v1/listen`

POST `/v1/audio/transcriptions`

Multipart form-data

JSON with base64 audio

JSON fields

Response

POST `/v1/audio/speech`

Request body

Response

POST `/v1/email/send`

Request body

Request fields

Success response

Common errors