History API

Every offline job or streaming session lands in the History API. Use it to build dashboards, download transcripts, or share recordings with collaborators.

Permissions#

API
PIPELINE_OFFLINE_API or PIPELINE_ONLINE_API (depending on the session type)
Stage-specific roles (STAGE_ASR, STAGE_TTS, etc.) if you plan to resume sessions with the same user.

Endpoints at a glance#

Purpose	Method & path
List sessions	`GET /api/client/sessions`
Fetch a session	`GET /api/client/sessions/{sessionId}`
Download audio	`GET /api/client/sessions/{sessionId}/audio.wav`
Fetch transcripts	`GET /api/client/sessions/{sessionId}/transcripts`
List recordings	`GET /api/client/sessions/{sessionId}/recordings`
List shares	`GET /api/client/sessions/{sessionId}/shares`
Create share	`POST /api/client/sessions/{sessionId}/shares`
Delete share	`DELETE /api/client/sessions/shares/{shareId}`
Discover shareable users	`GET /api/client/users`

All requests require an access token supplied via the Authorization: Bearer header (or ?access_token= query parameter when headers are not available).

List sessions#

cURL
Python
JavaScript (Node.js)
Java

curl --fail --location \n  --request GET "$TRUEBAR_API_BASE_URL/api/client/sessions" \n  --header "Authorization: Bearer $TRUEBAR_ACCESS_TOKEN"

list_sessions.py

import os
import requests

response = requests.get(    f"{os.environ['TRUEBAR_API_BASE_URL']}/api/client/sessions",    headers={"Authorization": f"Bearer {os.environ['TRUEBAR_ACCESS_TOKEN']}"},    timeout=10,)response.raise_for_status()data = response.json()print(f"Fetched {len(data.get('content', []))} sessions")

list-sessions.mjs

import axios from 'axios';
const response = await axios.get(  `${process.env.TRUEBAR_API_BASE_URL}/api/client/sessions`,  { headers: { Authorization: `Bearer ${process.env.TRUEBAR_ACCESS_TOKEN}` } },);console.log(`Fetched ${response.data.content?.length ?? 0} sessions`);

ListSessions.java

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

The response uses cursor-based slicing; each item includes a cursor token you can pass back in subsequent calls.

{  "cursor": "MjAyNC0wNC0yMlQwODoxNTowMC4wMDBaOjEyMzQ1",  "content": [    {      "id": 4812,      "name": "Call centre demo",      "status": "FINISHED",      "numRecordings": 2,      "recordedMs": 586000,      "processedMs": 586000,      "createdAt": "2024-04-22T08:15:30.123Z",      "updatedAt": "2024-04-22T08:27:18.044Z",      "createdByUser": "alice@example.com",      "createdByGroup": "support",      "isLocked": false,      "isDiscarded": false,      "labels": [],      "notes": null    }  ]}

Paging with cursors#

slice-cursor: resume from the cursor of the last session in the previous response.
slice-length: positive to fetch forward, negative to fetch backwards. Defaults to 20 sessions forward.

Example: fetch the next 10 sessions after the supplied cursor.

curl --request GET \  "$TRUEBAR_API_BASE_URL/api/client/sessions?slice-cursor=$CURSOR&slice-length=10" \  --header "Authorization: Bearer $TRUEBAR_ACCESS_TOKEN"

Sorting & filtering#

Query parameters:

sort=createdAt,desc (supported fields: id, name, createdAt, updatedAt, numRecordings, recordedSeconds)
name=demo – substring match on the session name.
label=customer-a – sessions tagged with the given label.
created-after=2024-01-01T00:00:00Z
created-before=2024-03-31T23:59:59Z

curl --request GET \  "$TRUEBAR_API_BASE_URL/api/client/sessions?name=Test&sort=createdAt,asc&slice-length=30" \  --header "Authorization: Bearer $TRUEBAR_ACCESS_TOKEN"

Session details#

cURL
Python
JavaScript (Node.js)
Java

curl --fail --location \n  --request GET "$TRUEBAR_API_BASE_URL/api/client/sessions/$SESSION_ID" \n  --header "Authorization: Bearer $TRUEBAR_ACCESS_TOKEN"

import osimport requests

session_id = "12345"response = requests.get(    f"{os.environ['TRUEBAR_API_BASE_URL']}/api/client/sessions/{session_id}",    headers={"Authorization": f"Bearer {os.environ['TRUEBAR_ACCESS_TOKEN']}"},    timeout=10,)response.raise_for_status()print(response.json())

import axios from 'axios';
const sessionId = '12345';const { data } = await axios.get(  `${process.env.TRUEBAR_API_BASE_URL}/api/client/sessions/${sessionId}`,  { headers: { Authorization: `Bearer ${process.env.TRUEBAR_ACCESS_TOKEN}` } },);console.log(data);

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

Returns the same fields as the list view, plus pipeline metadata and recording summaries.

Download audio#

cURL
Python
JavaScript (Node.js)
Java

curl --fail --location \n  --request GET "$TRUEBAR_API_BASE_URL/api/client/sessions/$SESSION_ID/audio.wav" \n  --header "Authorization: Bearer $TRUEBAR_ACCESS_TOKEN" \n  --output session.wav

import osimport requests

session_id = "12345"response = requests.get(    f"{os.environ['TRUEBAR_API_BASE_URL']}/api/client/sessions/{session_id}/audio.wav",    headers={"Authorization": f"Bearer {os.environ['TRUEBAR_ACCESS_TOKEN']}"},    timeout=30,)response.raise_for_status()with open("session.wav", "wb") as handle:    handle.write(response.content)

import axios from 'axios';import { writeFileSync } from 'node:fs';
const sessionId = '12345';const response = await axios.get(  `${process.env.TRUEBAR_API_BASE_URL}/api/client/sessions/${sessionId}/audio.wav`,  {    headers: { Authorization: `Bearer ${process.env.TRUEBAR_ACCESS_TOKEN}` },    responseType: 'arraybuffer',  },);writeFileSync('session.wav', Buffer.from(response.data));

import java.io.FileOutputStream;import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;
public class DownloadSessionAudio {  public static void main(String[] args) throws Exception {    String sessionId = "12345";    HttpRequest request = HttpRequest.newBuilder()        .uri(URI.create(System.getenv("TRUEBAR_API_BASE_URL") + "/api/client/sessions/" + sessionId + "/audio.wav"))        .header("Authorization", "Bearer " + System.getenv("TRUEBAR_ACCESS_TOKEN"))        .GET()        .build();
    HttpClient client = HttpClient.newHttpClient();    HttpResponse<byte[]> response = client.send(request, HttpResponse.BodyHandlers.ofByteArray());    if (response.statusCode() >= 400) {      throw new IllegalStateException("Request failed: " + response.statusCode());    }    try (FileOutputStream out = new FileOutputStream("session.wav")) {      out.write(response.body());    }  }}

Tips:

Use the Range header (Range: bytes=0-1048575) to stream partial content.
When a client cannot set headers (e.g., a browser <audio> tag), append ?access_token=$TOKEN to the URL.

Fetch transcripts#

cURL
Python
JavaScript (Node.js)
Java

curl --fail --location \n  --request GET "$TRUEBAR_API_BASE_URL/api/client/sessions/$SESSION_ID/transcripts"   --header "Authorization: Bearer $TRUEBAR_ACCESS_TOKEN"

import osimport requests

session_id = "12345"response = requests.get(    f"{os.environ['TRUEBAR_API_BASE_URL']}/api/client/sessions/{session_id}/transcripts",    headers={"Authorization": f"Bearer {os.environ['TRUEBAR_ACCESS_TOKEN']}"},    timeout=10,)response.raise_for_status()for entry in response.json():    print(entry["id"], entry["content"])

import axios from 'axios';
const sessionId = '12345';const { data } = await axios.get(  `${process.env.TRUEBAR_API_BASE_URL}/api/client/sessions/${sessionId}/transcripts`,  { headers: { Authorization: `Bearer ${process.env.TRUEBAR_ACCESS_TOKEN}` } },);data.forEach((item) => {  console.log(item.id, JSON.parse(item.content));});

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

Response:

[  {    "id": 7319,    "content": "{\"tokens\":[{\"text\":\"Hello\"},{\"text\":\"world\"}]}"  }]

content is a JSON string; parse it to recover the segment/token structure used across the documentation.

List recordings#

cURL
Python
JavaScript (Node.js)
Java

curl --fail --location \n  --request GET "$TRUEBAR_API_BASE_URL/api/client/sessions/$SESSION_ID/recordings?page=0&size=10"   --header "Authorization: Bearer $TRUEBAR_ACCESS_TOKEN"

import osimport requests

session_id = "12345"response = requests.get(    f"{os.environ['TRUEBAR_API_BASE_URL']}/api/client/sessions/{session_id}/recordings",    headers={"Authorization": f"Bearer {os.environ['TRUEBAR_ACCESS_TOKEN']}"},    params={"page": 0, "size": 10},    timeout=10,)response.raise_for_status()print(response.json()["content"])

import axios from 'axios';
const sessionId = '12345';const { data } = await axios.get(  `${process.env.TRUEBAR_API_BASE_URL}/api/client/sessions/${sessionId}/recordings`,  {    headers: { Authorization: `Bearer ${process.env.TRUEBAR_ACCESS_TOKEN}` },    params: { page: 0, size: 10 },  },);console.log(data.content);

import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;
public class ListRecordings {  public static void main(String[] args) throws Exception {    String sessionId = "12345";    HttpRequest request = HttpRequest.newBuilder()        .uri(URI.create(System.getenv("TRUEBAR_API_BASE_URL") + "/api/client/sessions/" + sessionId + "/recordings?page=0&size=10"))        .header("Authorization", "Bearer " + System.getenv("TRUEBAR_ACCESS_TOKEN"))        .GET()        .build();
    HttpClient client = HttpClient.newHttpClient();    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());    if (response.statusCode() >= 400) {      throw new IllegalStateException("Request failed: " + response.statusCode());    }    System.out.println(response.body());  }}

Example response (trimmed):

{  "totalPages": 1,  "totalElements": 2,  "content": [    {      "id": 10291,      "duration": 305.7,      "isDiscarded": false,      "pipeline": [        { "task": "ASR", "config": { "tag": "KALDI:sl-SI:COL:20221208-0800" } },        { "task": "NLP_pc", "config": { "tag": "NEMO_PUNCTUATOR:sl-SI:*:*" } }      ]    }  ]}

Use the pipeline snapshot to replay or diagnose historical jobs.

Session sharing#

Sessions are private by default; only the creator and group admins can view them. Use the sharing endpoints to delegate access.

Discover shareable users#

cURL
Python
JavaScript (Node.js)
Java

curl --fail --location \n  --request GET "$TRUEBAR_API_BASE_URL/api/client/users"   --header "Authorization: Bearer $TRUEBAR_ACCESS_TOKEN"

import osimport requests

response = requests.get(    f"{os.environ['TRUEBAR_API_BASE_URL']}/api/client/users",    headers={"Authorization": f"Bearer {os.environ['TRUEBAR_ACCESS_TOKEN']}"},    timeout=10,)response.raise_for_status()print(response.json())

import axios from 'axios';
const { data } = await axios.get(  `${process.env.TRUEBAR_API_BASE_URL}/api/client/users`,  { headers: { Authorization: `Bearer ${process.env.TRUEBAR_ACCESS_TOKEN}` } },);console.log(data);

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

List existing shares#

cURL
Python
JavaScript (Node.js)
Java

curl --fail --location \n  --request GET "$TRUEBAR_API_BASE_URL/api/client/sessions/$SESSION_ID/shares"   --header "Authorization: Bearer $TRUEBAR_ACCESS_TOKEN"

import osimport requests

session_id = "12345"response = requests.get(    f"{os.environ['TRUEBAR_API_BASE_URL']}/api/client/sessions/{session_id}/shares",    headers={"Authorization": f"Bearer {os.environ['TRUEBAR_ACCESS_TOKEN']}"},    timeout=10,)response.raise_for_status()print(response.json())

import axios from 'axios';
const sessionId = '12345';const { data } = await axios.get(  `${process.env.TRUEBAR_API_BASE_URL}/api/client/sessions/${sessionId}/shares`,  { headers: { Authorization: `Bearer ${process.env.TRUEBAR_ACCESS_TOKEN}` } },);console.log(data);

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

[  {    "id": 912,    "createdAt": "2024-04-22T08:31:11.000Z",    "sharedWith": { "id": 37, "username": "bob@example.com" }  }]

Add a share#

cURL
Python
JavaScript (Node.js)
Java

curl --fail --location \n  --request POST "$TRUEBAR_API_BASE_URL/api/client/sessions/$SESSION_ID/shares"   --header "Authorization: Bearer $TRUEBAR_ACCESS_TOKEN"   --header "Content-Type: application/json"   --data-raw '{ "userId": 37 }'

import osimport requests

session_id = "12345"payload = {"userId": 37}response = requests.post(    f"{os.environ['TRUEBAR_API_BASE_URL']}/api/client/sessions/{session_id}/shares",    headers={        "Authorization": f"Bearer {os.environ['TRUEBAR_ACCESS_TOKEN']}",        "Content-Type": "application/json",    },    json=payload,    timeout=10,)response.raise_for_status()print(response.json())

import axios from 'axios';
const sessionId = '12345';const payload = { userId: 37 };const { data } = await axios.post(  `${process.env.TRUEBAR_API_BASE_URL}/api/client/sessions/${sessionId}/shares`,  payload,  {    headers: {      Authorization: `Bearer ${process.env.TRUEBAR_ACCESS_TOKEN}` ,      'Content-Type': 'application/json',    },  },);console.log(data);

import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;
public class CreateShare {  public static void main(String[] args) throws Exception {    String sessionId = "12345";    String payload = "{\"userId\":37}";    HttpRequest request = HttpRequest.newBuilder()        .uri(URI.create(System.getenv("TRUEBAR_API_BASE_URL") + "/api/client/sessions/" + sessionId + "/shares"))        .header("Authorization", "Bearer " + System.getenv("TRUEBAR_ACCESS_TOKEN"))        .header("Content-Type", "application/json")        .POST(HttpRequest.BodyPublishers.ofString(payload))        .build();
    HttpClient client = HttpClient.newHttpClient();    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());    if (response.statusCode() >= 400) {      throw new IllegalStateException("Request failed: " + response.statusCode());    }    System.out.println(response.body());  }}

Remove a share#

cURL
Python
JavaScript (Node.js)
Java

curl --fail --location \n  --request DELETE "$TRUEBAR_API_BASE_URL/api/client/sessions/shares/$SHARE_ID"   --header "Authorization: Bearer $TRUEBAR_ACCESS_TOKEN"

import osimport requests

share_id = "678"response = requests.delete(    f"{os.environ['TRUEBAR_API_BASE_URL']}/api/client/sessions/shares/{share_id}",    headers={"Authorization": f"Bearer {os.environ['TRUEBAR_ACCESS_TOKEN']}"},    timeout=10,)response.raise_for_status()

import axios from 'axios';
const shareId = '678';await axios.delete(  `${process.env.TRUEBAR_API_BASE_URL}/api/client/sessions/shares/${shareId}`,  { headers: { Authorization: `Bearer ${process.env.TRUEBAR_ACCESS_TOKEN}` } },);console.log('Share removed');

import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;
public class DeleteShare {  public static void main(String[] args) throws Exception {    String shareId = "678";    HttpRequest request = HttpRequest.newBuilder()        .uri(URI.create(System.getenv("TRUEBAR_API_BASE_URL") + "/api/client/sessions/shares/" + shareId))        .header("Authorization", "Bearer " + System.getenv("TRUEBAR_ACCESS_TOKEN"))        .DELETE()        .build();
    HttpClient client = HttpClient.newHttpClient();    HttpResponse<Void> response = client.send(request, HttpResponse.BodyHandlers.discarding());    if (response.statusCode() >= 400) {      throw new IllegalStateException("Request failed: " + response.statusCode());    }  }}

Next steps#

Use the Offline Pipeline API to create jobs that appear in history.
Resume a streaming session with the sessionId returned by the WebSocket STATUS messages (see the Streaming STT guide).
Surface history data in your product by pairing these endpoints with custom metadata stored in your application.