API Overview

This page distills the key concepts behind the Truebar pipeline API: which environment variables to set, how to authorise requests, the roles your service user needs, and how to discover & compose pipeline stages. For full end‑to‑end code, jump to the quickstarts and streaming guides in the links below.

Environment setup

Export the standard variables once (production hostnames shown). Replace the host prefix (for example with playground-) when targeting a non-production cluster.

export TRUEBAR_USERNAME="alice@example.com"export TRUEBAR_PASSWORD="super-secret-passphrase"export TRUEBAR_CLIENT_ID="truebar-client"export TRUEBAR_AUTH_URL="https://auth.true-bar.si/realms/truebar/protocol/openid-connect/token"export TRUEBAR_API_BASE_URL="https://api.true-bar.si"export TRUEBAR_STT_WS_URL="wss://api.true-bar.si/api/pipelines/stream"export TRUEBAR_TTS_WS_URL="wss://api.true-bar.si/api/pipelines/stream"

Additional variables (such as TRUEBAR_ASR_TAG, TRUEBAR_TTS_TAG, or the TRUEBAR_TTS_NLP_* tags for Riva pipelines) can be layered on per project.

Quick navigation

• Getting started: Environment & auth walkthrough
• Tutorials: Streaming STT quickstart, Streaming TTS quickstart
• API guides: Streaming STT guide, Streaming TTS guide, Offline pipeline API, History API
• Migration: Moving from 2.x to 3.x
• Client libraries: Java / JS SDKs

Authentication in brief

Truebar issues OAuth2 access tokens. The canonical curl examples (password grant and refresh grant) live in the Getting Started guide. Most teams wrap those flows in a small helper (see the Node.js/Python token managers in the tutorials) and reuse the bearer token via the Authorization: Bearer header for both REST and WebSocket calls. Only fall back to ?access_token= when headers are impossible (for example some embedded clients).

Discover stages

Every stage advertises the tags, feature flags, and parameters it supports. Call the discovery endpoint with your bearer token:

cURL

curl "$TRUEBAR_API_BASE_URL/api/pipelines/stages" \  --header "Authorization: Bearer $TRUEBAR_ACCESS_TOKEN" \  | jq '.[] | {task, configOptions: .configOptions // .config, features}'

Python

import jsonimport os
import requests

response = requests.get(    f"{os.environ['TRUEBAR_API_BASE_URL']}/api/pipelines/stages",    headers={"Authorization": f"Bearer {os.environ['TRUEBAR_ACCESS_TOKEN']}"},    timeout=10,)response.raise_for_status()summary = [    {        "task": stage["task"],        "features": stage.get("features"),        "configOptions": stage.get("configOptions") or stage.get("config"),    }    for stage in response.json()]print(json.dumps(summary, indent=2))

Node.js

stages.mjs

import axios from "axios";
const { data } = await axios.get(  `${process.env.TRUEBAR_API_BASE_URL}/api/pipelines/stages`,  {    headers: { Authorization: `Bearer ${process.env.TRUEBAR_ACCESS_TOKEN}` },    timeout: 10_000,  },);
const summary = data.map((stage) => ({  task: stage.task,  features: stage.features,  configOptions: stage.configOptions ?? stage.config,}));
console.log(JSON.stringify(summary, null, 2));

Java

import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;
public class StageDiscovery {  public static void main(String[] args) throws Exception {    HttpRequest request = HttpRequest.newBuilder()        .uri(URI.create(System.getenv("TRUEBAR_API_BASE_URL") + "/api/pipelines/stages"))        .header("Authorization", "Bearer " + System.getenv("TRUEBAR_ACCESS_TOKEN"))        .build();
    HttpClient client = HttpClient.newHttpClient();    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());    if (response.statusCode() >= 400) {      throw new IllegalStateException("Discovery failed: " + response.statusCode() + " - " + response.body());    }    System.out.println(response.body());  }}

Example (annotated):

{  "task": "TTS",  "features": ["streamingTts", "multiVoice"],  "configOptions": [    {      "tag": "RIVA:sl-SI:ZIGA:20250408-2103",      "parameters": {      }    }  ]}

If the TTS tag belongs to the Riva family (RIVA:*, RIVA-STREAM:*, or VIT:*) you should also look for the corresponding NLP stages (NLP_st, NLP_tn, NLP_g2a) so the pipeline mirrors the production flow. Non-Riva voices usually expose a single TTS stage with optional prosody parameters.

Compose pipelines

• STT: Start with an ASR stage, add punctuation/normalisation stages if desired, and keep exceptionHandlingPolicy at THROW unless you intentionally want to continue on failure. Streaming pipelines expect mono, 16 kHz PCM chunks; resample or convert ahead of time.
• TTS: Choose either a single-stage voice or assemble the Riva chain (semantic tagging → text normalisation → grapheme-to-accentuation → TTS). Set TRUEBAR_TTS_ENABLE_SSML=true (and optionally TRUEBAR_TTS_SSML_RATE) when you need SSML control.

You can reuse the helpers from the quickstarts (buildPipeline/build_tts_pipeline) to keep the logic in one place.

Streaming message flow

1. Connect to wss://…/api/pipelines/stream.
2. Wait for STATUS: INITIALIZED, then send your CONFIG payload.
3. When you receive STATUS: CONFIGURED, start streaming PCM audio (STT) or TEXT_SEGMENT payloads (TTS).
4. Send {"type":"EOS","lockSession":false} when finished so the service can finish the session.
5. Watch for STATUS: FINISHED before closing the socket.
6. Handle ERROR messages by logging details and retrying with exponential backoff if the failure is transient (e.g. network interruptions).

The streaming guides contain complete Node.js/Python loops that implement retries and clean shutdowns.

Stage & parameter reference

Use this cheat sheet alongside the discovery endpoint. Parameter names match the identifiers returned by /api/pipelines/stages.

Speech-to-Text (ASR)

• Features: onlineAsr, dictatedCommands, dictatedPunctuations, speakerDiarization.
• Common parameters: enableInterims, enableSd, sdMinSpeakers, sdMaxSpeakers, enableUnks.

Text-to-Text (NLP)

Stage	Purpose	Notable parameters
NLP_pc	Add punctuation	enableSplitToSentences
NLP_tn	Text normalisation	customConfig
NLP_itn	Inverse normalisation	—
NLP_g2a	Grapheme-to-accentuation	fastEnabled, customTransformations
NLP_st	Sentence tokenization	processSsml
NLP_ts	Summarisation	summaryType, keywordsEnabled, keypointsEnabled

Text-to-Speech (TTS)

• Features: ssmlA, ssmlB, ssmlB.

Discover more

• STT token formatting & spacing rules
• TTS multi-stage design & SSML tips
• Client libraries for Java and JavaScript implementations of the same patterns.