SDK Functions

Use this page when you want to build with the SDK, not memorize every method name.

Start with the quick example, then copy the recipe closest to your task. Each recipe shows the same idea in Python, Node.js, Go, and Rust where the SDKs expose it. The Quick Start, Sign In, and Create A Client Identity recipes also show Kotlin, Swift, and C#; for the full surface of those SDKs, use the Kotlin, Swift, and .NET SDK pages.

Tip

The SDKs use https://api.thalovant.com by default. Keep client identities secret. They let a client connect to a hub.

Quick Start

This example signs in, creates a client identity for one hub, connects, sends one request, and prints the reply.

Python

from thalovant import ThalovantClient, ThalovantControlPlane

api = ThalovantControlPlane()
api.login("[email protected]", "password")

result = api.create_client_identity(
    "hub-id",
    name="python-demo-client",
    preferred_protocols=("wss", "https", "mqtt"),
)

with ThalovantClient(result.identity, protocol="wss") as client:
    reply = client.ask("Tell me a short clean joke.")
    print(reply.text)

Node.js

import { ThalovantClient, ThalovantControlPlane } from "@thalovant/sdk";

const api = new ThalovantControlPlane();
await api.login("[email protected]", "password");

const result = await api.createClientIdentity("hub-id", {
  name: "node-demo-client",
  preferredProtocols: ["wss", "https", "mqtt"],
});

const client = new ThalovantClient(result.identity, { protocol: "wss" });
try {
  const reply = await client.ask("Tell me a short clean joke.");
  console.log(reply.text);
} finally {
  await client.close();
}

Go

package main

import (
  "context"
  "fmt"
  "log"

  thalovant "github.com/thalovant/thalovant-go-sdk"
)

func main() {
  ctx := context.Background()
  api := thalovant.NewDefaultControlPlane("")

  if _, err := api.Login(ctx, "[email protected]", "password", ""); err != nil {
    log.Fatal(err)
  }

  result, err := api.CreateClientIdentityForHubID(ctx, "hub-id", thalovant.BootstrapIdentityOptions{
    Name:               "go-demo-client",
    PreferredProtocols: []thalovant.HubProtocol{thalovant.ProtocolWSS, thalovant.ProtocolHTTPS, thalovant.ProtocolMQTT},
  })
  if err != nil {
    log.Fatal(err)
  }

  client, err := thalovant.NewClientWithOptions(result.Identity, thalovant.ClientOptions{Protocol: thalovant.ProtocolWSS})
  if err != nil {
    log.Fatal(err)
  }
  defer client.Close(ctx)

  reply, err := client.Ask(ctx, "Tell me a short clean joke.", thalovant.RequestOptions{})
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(reply.Text)
}

Rust

use thalovant::{BootstrapIdentityOptions, Client, ControlPlane, HubProtocol, RequestOptions};

#[tokio::main]
async fn main() -> thalovant::Result<()> {
    let mut api = ControlPlane::default();
    api.login("[email protected]", "password", None).await?;

    let result = api
        .create_client_identity_for_hub_id(
            "hub-id",
            BootstrapIdentityOptions {
                name: "rust-demo-client".into(),
                preferred_protocols: vec![HubProtocol::Wss, HubProtocol::Https, HubProtocol::Mqtt],
                ..Default::default()
            },
        )
        .await?;

    let client = Client::with_protocol(result.identity.clone(), HubProtocol::Wss)?;
    let reply = client.ask("Tell me a short clean joke.", RequestOptions::default()).await?;
    println!("{}", reply.text);
    client.close().await?;

    Ok(())
}

Kotlin

import com.thalovant.sdk.CreateClientIdentityOptions
import com.thalovant.sdk.ThalovantClient
import com.thalovant.sdk.ThalovantControlPlane
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    val api = ThalovantControlPlane()
    api.login("[email protected]", "password")

    val result = api.createClientIdentity(
        "hub-id",
        CreateClientIdentityOptions(name = "kotlin-demo-client"),
    )

    val client = ThalovantClient(result.identity)
    try {
        val reply = client.ask("Tell me a short clean joke.")
        println(reply.text)
    } finally {
        client.close()
    }
}

Swift

import ThalovantSDK

let api = ThalovantControlPlane()
try await api.login(email: "[email protected]", password: "password")

let result = try await api.createClientIdentity(
    hubId: "hub-id",
    options: CreateClientIdentityOptions(name: "swift-demo-client")
)

let client = try ThalovantClient(identity: result.identity)
do {
    try await client.connect()
    let reply = try await client.ask("Tell me a short clean joke.")
    print(reply.text)
    await client.close()
} catch {
    await client.close()
    throw error
}

C#

using Thalovant;

var api = new ThalovantControlPlane();
await api.LoginAsync("[email protected]", "password");

var result = await api.CreateClientIdentityAsync(
    "hub-id",
    new CreateClientIdentityOptions("dotnet-demo-client"));

using var client = new ThalovantClient(result.Identity);
await client.ConnectAsync();
var reply = await client.AskAsync("Tell me a short clean joke.");
Console.WriteLine(reply.Text);
await client.CloseAsync();

The Kotlin, Swift, and C# clients connect over WSS only in their v0.1 releases, so they take no protocol argument here. See Capability Tiers.

Expected result:

Why did the hub keep good logs? It wanted every punchline to be traceable.

Choose The Right Recipe

Control plane

Discover hubs and create client identities.

Identity

Load saved credentials and choose a protocol.

Runtime client

Connect, ask, emit events, and send structured input.

Events and context

Listen for hub events and attach session metadata.

Create An API Client

Use this before hub discovery or identity provisioning.

Python

from thalovant import ThalovantControlPlane

api = ThalovantControlPlane()

Node.js

import { ThalovantControlPlane } from "@thalovant/sdk";

const api = new ThalovantControlPlane();

Go

import thalovant "github.com/thalovant/thalovant-go-sdk"

api := thalovant.NewDefaultControlPlane("")

Rust

use thalovant::ControlPlane;

let mut api = ControlPlane::default();

Sign In

Sign in before private control-plane actions such as creating a client identity.

Accounts with multi-factor authentication enabled must include a TOTP code or a one-time recovery code; without one, the API rejects the sign-in with HTTP 401 and code mfa_required. Every SDK sends the MFA fields only when they are set.

Python

api.login("[email protected]", "password")

# MFA-enabled accounts add a TOTP code or a one-time recovery code:
api.login("[email protected]", "password", otp_code="123456")
api.login("[email protected]", "password", recovery_code="abcd-efgh-ijkl")

Node.js

await api.login("[email protected]", "password");

// MFA-enabled accounts add a TOTP code or a one-time recovery code:
await api.login("[email protected]", "password", { otpCode: "123456" });
await api.login("[email protected]", "password", { recoveryCode: "abcd-efgh-ijkl" });

Go

_, err := api.Login(ctx, "[email protected]", "password", "")
if err != nil {
  log.Fatal(err)
}

// MFA-enabled accounts use LoginWithOptions with OTPCode or RecoveryCode:
_, err = api.LoginWithOptions(ctx, "[email protected]", "password", thalovant.LoginOptions{
  OTPCode: "123456",
})
if err != nil {
  log.Fatal(err)
}

Rust

api.login("[email protected]", "password", None).await?;

// MFA-enabled accounts use login_with_options with otp_code or recovery_code:
use thalovant::LoginOptions;

api.login_with_options(
    "[email protected]",
    "password",
    LoginOptions {
        otp_code: Some("123456".into()),
        ..Default::default()
    },
)
.await?;

Kotlin

api.login("[email protected]", "password")

// MFA-enabled accounts add a TOTP code or a one-time recovery code:
api.login("[email protected]", "password", otpCode = "123456")
api.login("[email protected]", "password", recoveryCode = "abcd-efgh-ijkl")

Swift

try await api.login(email: "[email protected]", password: "password")

// MFA-enabled accounts add a TOTP code or a one-time recovery code:
try await api.login(email: "[email protected]", password: "password", otpCode: "123456")
try await api.login(email: "[email protected]", password: "password", recoveryCode: "abcd-efgh-ijkl")

C#

await api.LoginAsync("[email protected]", "password");

// MFA-enabled accounts add a TOTP code or a one-time recovery code:
await api.LoginAsync("[email protected]", "password", otpCode: "123456");
await api.LoginAsync("[email protected]", "password", recoveryCode: "abcd-efgh-ijkl");

Common failure:

Missing Thalovant API access token

Fix it by signing in before the private call, or by passing an API token to the control-plane client. An HTTP 401 with code mfa_required means the account needs the TOTP or recovery code shown above.

Sign In Without A Password

Use device login when the code should never see your password: CLIs, agents, notebooks, and machines you do not fully trust with account credentials.

The SDK prints a line like To sign in, visit https://dash.thalovant.com/activate and enter the code XXXX-XXXX, opens that page in your browser when it can, and polls the API while you approve the sign-in with your normal browser session, including Google sign-in or MFA. On approval the SDK receives a scoped, revocable API token and stores it exactly like a password login.

Approving a device sign-in needs a paid workspace plan; on a free plan the approval is rejected with HTTP 402. Device login needs Python 0.4.22, Node.js 0.2.25, Go v0.3.3, Rust v0.2.20, or Kotlin, Swift, and .NET 0.1.1.

Python

api.login_with_browser()

# Optional: request narrower scopes and label the token in the dashboard.
api.login_with_browser(scopes=["hubs:read", "clients:write"], client_name="my-cli")

Node.js

// Prints: To sign in, visit https://dash.thalovant.com/activate and enter the code XXXX-XXXX
const token = await api.loginWithBrowser({ clientName: "my-laptop" });

// api.accessToken is now set, exactly like after api.login(...).

Go

token, err := api.LoginWithBrowser(ctx, thalovant.DeviceLoginOptions{
  Scopes:     []string{"hubs:read", "clients:write"}, // optional
  ClientName: "my-cli",                               // optional label in the dashboard
})
if err != nil {
  log.Fatal(err)
}
fmt.Println("signed in, token id:", token["token_id"])

Rust

use thalovant::DeviceLoginOptions;

let token = api
    .login_with_browser(DeviceLoginOptions {
        scopes: vec!["hubs:read".into(), "clients:write".into()],
        client_name: Some("my-tool".into()),
        ..Default::default()
    })
    .await?;
println!("signed in, token scopes: {}", token["scopes"]);

Kotlin

import com.thalovant.sdk.DeviceLoginOptions

api.loginWithBrowser(
    DeviceLoginOptions(scopes = listOf("hubs:read"), clientName = "kotlin-demo"),
)

Swift

let token = try await api.loginWithBrowser(options: DeviceLoginOptions(
    scopes: ["hubs:read", "clients:write"],
    clientName: "my-macbook"
))
print(token.tokenId ?? "", token.scopes)

C#

var result = await api.LoginWithBrowserAsync(new DeviceLoginOptions
{
    Scopes = new[] { "hubs:read", "clients:write" },
    ClientName = "my-tool",
});
Console.WriteLine($"{result.TokenId} expires {result.ExpiresAt}");

Every SDK honors the same options: scopes to narrow what the token can do, client_name (native casing) to label the token in the dashboard, open_browser to skip opening the page, prompt to replace the printed line, and a timeout that defaults to 15 minutes.

The approving user manages the resulting token on the dashboard’s API Tokens page: scopes, expiry, last use, and revocation.

Authenticate With An API Token

Use a stored API token when the process should start authenticated, such as CI jobs, servers, and AI agent configs.

Mint a token on the dashboard’s API Tokens page or through device login, then pass it to the control-plane constructor. Tokens are scoped, revocable, and show their last use on that page; creating one needs a paid workspace plan. The examples read the token from a THALOVANT_API_TOKEN environment variable, the same convention the MCP server uses.

Python

import os

from thalovant import ThalovantControlPlane

api = ThalovantControlPlane(access_token=os.environ["THALOVANT_API_TOKEN"])
# Ready immediately; no login call needed.

Node.js

const api = new ThalovantControlPlane("https://api.thalovant.com", {
  accessToken: process.env.THALOVANT_API_TOKEN,
});

// Ready immediately; no login call needed.

Go

api := thalovant.NewDefaultControlPlane(os.Getenv("THALOVANT_API_TOKEN"))

Rust

use thalovant::ControlPlane;

let token = std::env::var("THALOVANT_API_TOKEN").expect("THALOVANT_API_TOKEN is set");
let api = ControlPlane::with_access_token(token);

Kotlin

val api = ThalovantControlPlane(accessToken = System.getenv("THALOVANT_API_TOKEN"))

Swift

let api = ThalovantControlPlane(accessToken: ProcessInfo.processInfo.environment["THALOVANT_API_TOKEN"])

C#

var api = new ThalovantControlPlane(accessToken: Environment.GetEnvironmentVariable("THALOVANT_API_TOKEN"));

Tip

Keep tokens out of source code and logs. Store them in a secret manager or CI secret, and revoke a token on the API Tokens page the moment it might have leaked.

List Public Hubs

Use public hub discovery before you ask a user to choose a hub.

Python

page = api.list_public_hubs(limit=12)

for hub in page["data"]:
    print(hub["id"], hub["slug"], hub["title"])

Node.js

const page = await api.listPublicHubs({ limit: 12 });

for (const hub of page.data) {
  console.log(hub.id, hub.slug, hub.title);
}

Go

page, err := api.ListPublicHubs(ctx, 12, "")
if err != nil {
  log.Fatal(err)
}

for _, hub := range page.Data {
  fmt.Println(hub.ID, hub.Slug, hub.Title)
}

Rust

let page = api.list_public_hubs(Some(12), None).await?;

for hub in page.data {
    println!("{} {} {}", hub.id, hub.slug, hub.title);
}

Get One Public Hub

Use this when you have a hub reference from a URL, card, or saved choice.

Python

hub = api.get_public_hub("joke-garden")
print(hub["title"], hub["public_ref"])

Node.js

const hub = await api.getPublicHub("joke-garden");
console.log(hub.title, hub.publicRef);

Go

hub, err := api.GetPublicHub(ctx, "joke-garden")
if err != nil {
  log.Fatal(err)
}
fmt.Println(hub.Title, hub.PublicRef)

Rust

let hub = api.get_public_hub("joke-garden").await?;
println!("{} {}", hub.title, hub.public_ref);

List Visible Hubs

Use this for hubs the signed-in workspace can see.

Python

page = api.list_hubs(limit=25)

for hub in page["data"]:
    print(hub["id"], hub["title"])

Node.js

const page = await api.listHubs({ limit: 25 });

for (const hub of page.data) {
  console.log(hub.id, hub.title);
}

Go

page, err := api.ListHubs(ctx, 25, "", "")
if err != nil {
  log.Fatal(err)
}

for _, hub := range page.Data {
  fmt.Println(hub.ID, hub.Title)
}

Rust

let page = api.list_hubs(Some(25), None, None).await?;

for hub in page.data {
    println!("{} {}", hub.id, hub.title);
}

Get One Hub

Use this after you already know the hub ID.

Python

hub = api.get_hub("hub-id")
print(hub["title"])

Node.js

const hub = await api.getHub("hub-id");
console.log(hub.title);

Go

hub, err := api.GetHub(ctx, "hub-id")
if err != nil {
  log.Fatal(err)
}
fmt.Println(hub.Title)

Rust

let hub = api.get_hub("hub-id").await?;
println!("{}", hub.title);

Provision A Hub

Use this when your code should create the hub. Discovery needs hubs:read and works on any plan. The four writes need hubs:write and a paid plan. For the etag rule, the immutable fields, and the error table, see Provision Hubs.

Python

skills = api.list_marketplace_skills()["data"]

group = api.create_runtime_group({"name": "kiosks"})
hub = api.create_hub({
    "name": "joke-garden",
    "runtime_group_id": group["id"],
    "spec": {"protocols": {"wss": {"enabled": True}}},
})

api.install_runtime_group_skill(group["id"], "skill-weather")
api.release_runtime_group(group["id"], channel="stable")
api.release_hub(hub["id"], channel="stable")

Node.js

const catalog = await api.listMarketplaceSkills();

const group = await api.createRuntimeGroup({ name: "kiosks" });
const hub = await api.createHub({
  name: "joke-garden",
  runtimeGroupId: group.id as string,
  spec: { protocols: { wss: { enabled: true } } },
});

await api.installRuntimeGroupSkill(group.id as string, "skill-weather");
await api.releaseRuntimeGroup(group.id as string, { channel: "stable" });
await api.releaseHub(hub.id as string, { channel: "stable" });

Go

catalog, err := api.ListMarketplaceSkills(ctx, thalovant.MarketplaceSkillListOptions{})

group, err := api.CreateRuntimeGroup(ctx, map[string]any{"name": "kiosks"})
groupID := group["id"].(string)

hub, err := api.CreateHub(ctx, map[string]any{
  "name":             "joke-garden",
  "runtime_group_id": groupID,
  "spec":             map[string]any{"protocols": map[string]any{"wss": map[string]any{"enabled": true}}},
}, thalovant.HubCreateOptions{})
hubID := hub["id"].(string)

_, err = api.InstallRuntimeGroupSkill(ctx, groupID, "skill-weather", thalovant.RuntimeGroupSkillInstallOptions{})
_, err = api.ReleaseRuntimeGroup(ctx, groupID, thalovant.ReleaseOptions{Channel: "stable"})
_, err = api.ReleaseHub(ctx, hubID, thalovant.ReleaseOptions{Channel: "stable"})

Rust

let catalog = api.list_marketplace_skills(MarketplaceSkillsOptions::default()).await?;

let group = api.create_runtime_group(json!({"name": "kiosks"})).await?;
let group_id = group["id"].as_str().unwrap_or_default().to_string();

let hub = api
    .create_hub(
        json!({
            "name": "joke-garden",
            "runtime_group_id": group_id,
            "spec": {"protocols": {"wss": {"enabled": true}}},
        }),
        None,
    )
    .await?;
let hub_id = hub["id"].as_str().unwrap_or_default().to_string();

api.install_runtime_group_skill(&group_id, "skill-weather", SkillInstallOptions::default()).await?;
api.release_runtime_group(&group_id, ReleaseOptions { channel: Some("stable".into()), ..Default::default() }).await?;
api.release_hub(&hub_id, ReleaseOptions { channel: Some("stable".into()), ..Default::default() }).await?;

Kotlin, Swift, and .NET expose the same calls with native names. Their SDK pages show the language-specific form.

Update A Hub With Its Etag

Hub update and delete need the hub’s current etag, sent as If-Match. Read the hub first: the etag is a body field, and the API sends no ETag response header.

Python

hub = api.get_hub("hub-id")
hub = api.update_hub("hub-id", {"active": False}, etag=hub["etag"])
api.delete_hub("hub-id", etag=hub["etag"])

Node.js

let hub = await api.getHub("hub-id");
hub = await api.updateHub("hub-id", { active: false }, { etag: hub.etag as string });
await api.deleteHub("hub-id", { etag: hub.etag as string });

Go

hub, err := api.GetHub(ctx, "hub-id")
hub, err = api.UpdateHub(ctx, "hub-id", map[string]any{"active": false}, hub["etag"].(string))
err = api.DeleteHub(ctx, "hub-id", hub["etag"].(string))

Rust

let hub = api.get_hub("hub-id").await?;
let etag = hub["etag"].as_str().unwrap_or_default().to_string();

let hub = api.update_hub("hub-id", json!({"active": false}), &etag).await?;
let etag = hub["etag"].as_str().unwrap_or_default().to_string();
api.delete_hub("hub-id", &etag).await?;

A missing or stale etag fails with HTTP 412 and changes nothing. Re-read the hub and retry.

Poll An Accepted Operation

Use the operation ID returned by an asynchronous control-plane command. Stop at ready, failed, or timed_out; Git-only commands stop at committed.

Python

operation = api.get_operation("operation-id")
print(operation.status)

Node.js

const operation = await api.getOperation("operation-id");
console.log(operation.status);

Go

operation, err := api.GetOperation(ctx, "operation-id")

Rust

let operation = api.get_operation("operation-id").await?;

See Operations for lifecycle and retry guidance.

Create A Client Identity

Create an identity when a browser, service, voice client, device, or agent needs to connect to one hub.

Python

result = api.create_client_identity(
    "hub-id",
    name="checkout-kiosk",
    preferred_protocols=("wss", "https"),
)

identity = result.identity

Node.js

const result = await api.createClientIdentity("hub-id", {
  name: "checkout-kiosk",
  preferredProtocols: ["wss", "https"],
});

const identity = result.identity;

Go

result, err := api.CreateClientIdentityForHubID(ctx, "hub-id", thalovant.BootstrapIdentityOptions{
  Name:               "checkout-kiosk",
  PreferredProtocols: []thalovant.HubProtocol{thalovant.ProtocolWSS, thalovant.ProtocolHTTPS},
})
if err != nil {
  log.Fatal(err)
}

identity := result.Identity

Rust

let result = api
    .create_client_identity_for_hub_id(
        "hub-id",
        BootstrapIdentityOptions {
            name: "checkout-kiosk".into(),
            preferred_protocols: vec![HubProtocol::Wss, HubProtocol::Https],
            ..Default::default()
        },
    )
    .await?;

let identity = result.identity.clone();

Kotlin

val result = api.createClientIdentity(
    "hub-id",
    CreateClientIdentityOptions(name = "checkout-kiosk"),
)

val identity = result.identity

Swift

let result = try await api.createClientIdentity(
    hubId: "hub-id",
    options: CreateClientIdentityOptions(name: "checkout-kiosk")
)

let identity = result.identity

C#

var result = await api.CreateClientIdentityAsync(
    "hub-id",
    new CreateClientIdentityOptions("checkout-kiosk"));

var identity = result.Identity;

Caution

Do not log the full identity. Store it like a secret because it contains client connection material.

Every SDK also accepts an active option on creation, and it defaults to true. Pass false to provision the client disabled, so it cannot connect until you activate it with a client update.

Load Identity Material

Use config or a downloaded identity file when the client already exists.

On Linux and macOS, protect local config.yaml and _identity.json files with owner-only permissions before loading them:

chmod 600 ~/.config/thalovant/config.yaml
chmod 600 _identity.json

Python

from thalovant import ThalovantClient, ThalovantIdentity

identity = ThalovantIdentity.from_config(profile="prod")
same_identity = ThalovantIdentity.from_file("_identity.json")

client_from_config = ThalovantClient.from_config(profile="prod", protocol="wss")
client_from_file = ThalovantClient.from_identity_file("_identity.json")
client_from_env = ThalovantClient.from_env()

Node.js

import { ThalovantClient, ThalovantIdentity } from "@thalovant/sdk";

const identity = await ThalovantIdentity.fromConfig({ profile: "prod" });
const sameIdentity = await ThalovantIdentity.fromFile("_identity.json");

const clientFromConfig = await ThalovantClient.fromConfig({ profile: "prod", protocol: "wss" });
const clientFromFile = await ThalovantClient.fromIdentityFile("_identity.json");
const clientFromEnv = ThalovantClient.fromEnv();

Go

identity, err := thalovant.IdentityFromConfig("", "prod")
if err != nil {
  log.Fatal(err)
}

sameIdentity, err := thalovant.IdentityFromFile("_identity.json")
if err != nil {
  log.Fatal(err)
}

clientFromConfig, err := thalovant.NewClientFromConfig("", "prod")
clientFromFile, err := thalovant.NewClientFromFile("_identity.json")
clientFromEnv, err := thalovant.NewClientFromEnv()

Rust

use thalovant::{Client, Identity};

let identity = Identity::from_config(Some("prod"))?;
let same_identity = Identity::from_file("_identity.json")?;

let client_from_config = Client::from_config(Some("prod"))?;
let client_from_file = Client::from_file("_identity.json")?;
let client_from_env = Client::from_env()?;

Inspect Protocols

Use protocol helpers before forcing WSS, HTTPS, or MQTT.

Python

print(identity.enabled_protocols())
print(identity.endpoint_for("wss"))
print(identity.endpoint_for("https"))
print(identity.endpoint_for("mqtt"))
print(identity.supports_protocol("wss"))

if identity.mqtt:
    print(identity.mqtt.endpoint)

Node.js

console.log(identity.enabledProtocols());
console.log(identity.endpointFor("wss"));
console.log(identity.endpointFor("https"));
console.log(identity.endpointFor("mqtt"));
console.log(identity.supportsProtocol("wss"));

if (identity.mqtt) {
  console.log(identity.mqtt.endpoint);
}

Go

fmt.Println(identity.EnabledProtocols())
fmt.Println(identity.EndpointFor(thalovant.ProtocolWSS))
fmt.Println(identity.EndpointFor(thalovant.ProtocolHTTPS))
fmt.Println(identity.EndpointFor(thalovant.ProtocolMQTT))
fmt.Println(identity.SupportsProtocol(thalovant.ProtocolWSS))

if identity.MQTT != nil {
  fmt.Println(identity.MQTT.Endpoint)
}

Rust

println!("{:?}", identity.enabled_protocols());
println!("{:?}", identity.endpoint_for(HubProtocol::Wss));
println!("{:?}", identity.endpoint_for(HubProtocol::Https));
println!("{:?}", identity.endpoint_for(HubProtocol::Mqtt));
println!("{}", identity.supports_protocol(HubProtocol::Wss));

if let Some(mqtt) = &identity.mqtt {
    println!("{}", mqtt.endpoint);
}

Create A Runtime Client

Use a runtime client after you have identity material.

Python

from thalovant import ThalovantClient

client = ThalovantClient(identity, protocol="wss")
client.connect()
print(client.healthcheck())
client.close()

Node.js

import { ThalovantClient } from "@thalovant/sdk";

const client = new ThalovantClient(identity, { protocol: "wss" });
await client.connect();
console.log(await client.healthcheck());
await client.close();

Go

client, err := thalovant.NewClientWithOptions(identity, thalovant.ClientOptions{
  Protocol: thalovant.ProtocolWSS,
})
if err != nil {
  log.Fatal(err)
}

if err := client.Connect(ctx); err != nil {
  log.Fatal(err)
}
fmt.Println(client.Healthcheck())
client.Close(ctx)

Rust

use thalovant::{Client, HubProtocol};

let client = Client::with_protocol(identity.clone(), HubProtocol::Wss)?;
client.connect().await?;
println!("{:?}", client.healthcheck().await);
client.close().await?;

Most code should use a context manager, try/finally, defer, or ? cleanup so connections close reliably.

Ask A Hub

Use ask for one request-response interaction.

Python

reply = client.ask("What can this hub do?")

print(reply.text)
for item in reply.display_items():
    print(item)

Node.js

const reply = await client.ask("What can this hub do?");

console.log(reply.text);
for (const item of reply.displayItems()) {
  console.log(item);
}

Go

reply, err := client.Ask(ctx, "What can this hub do?", thalovant.RequestOptions{})
if err != nil {
  log.Fatal(err)
}

fmt.Println(reply.Text)
for _, item := range reply.DisplayItems(600) {
  fmt.Println(item)
}

Rust

let reply = client
    .ask("What can this hub do?", RequestOptions::default())
    .await?;

println!("{}", reply.text);
for item in reply.display_items(Some(600)) {
    println!("{item:?}");
}

Expected output shape:

{
  "text": "This hub can answer quick joke and trivia requests.",
  "display_items": []
}

Emit A Raw Event

Use raw events when you already have an event name and a structured payload.

Python

client.emit(
    "thalovant.client.status",
    {"state": "ready"},
    {"source": "checkout-kiosk"},
)

Node.js

await client.emit(
  "thalovant.client.status",
  { state: "ready" },
  { source: "checkout-kiosk" },
);

Go

err := client.Emit(ctx, "thalovant.client.status", map[string]any{
  "state": "ready",
}, map[string]any{
  "source": "checkout-kiosk",
})
if err != nil {
  log.Fatal(err)
}

Rust

use serde_json::json;

let mut data = serde_json::Map::new();
data.insert("state".into(), json!("ready"));

let mut context = serde_json::Map::new();
context.insert("source".into(), json!("checkout-kiosk"));

client
    .emit("thalovant.client.status", data, context)
    .await?;

Send An Utterance

Use an utterance when the input should behave like speech or chat text from a client.

Python

client.send_utterance(
    "What is the status?",
    lang="en-us",
    session_id="status-session",
)

Node.js

await client.sendUtterance("What is the status?", {
  lang: "en-us",
  sessionId: "status-session",
});

Go

err := client.SendUtterance(ctx, "What is the status?", thalovant.RequestOptions{
  Lang:      "en-us",
  SessionID: "status-session",
})
if err != nil {
  log.Fatal(err)
}

Rust

client
    .send_utterance(
        "What is the status?",
        RequestOptions {
            lang: Some("en-us".into()),
            session_id: Some("status-session".into()),
            ..Default::default()
        },
    )
    .await?;

Send An Action

Use actions for buttons, menu picks, confirmations, and tool commands.

Python

client.send_action(
    "/approve invoice-42",
    title="Approve invoice",
    session_id="approval-session",
)

Node.js

await client.sendAction(
  "/approve invoice-42",
  { title: "Approve invoice", sessionId: "approval-session" },
);

Go

err := client.SendAction(ctx, "/approve invoice-42", thalovant.ActionOptions{
  Title:     "Approve invoice",
  SessionID: "approval-session",
})
if err != nil {
  log.Fatal(err)
}

Rust

client
    .send_action(
        "/approve invoice-42",
        ActionOptions {
            title: Some("Approve invoice".into()),
            session_id: Some("approval-session".into()),
            ..Default::default()
        },
    )
    .await?;

Send A Code

Use code input for QR values, barcode scans, serial numbers, short codes, or typed exact values.

Python

client.send_code(
    "INV-2026-001",
    kind="invoice",
    session_id="scan-session",
)

Node.js

await client.sendCode("INV-2026-001", {
  kind: "invoice",
  sessionId: "scan-session",
});

Go

err := client.SendCode(ctx, "INV-2026-001", thalovant.CodeOptions{
  Kind:      "invoice",
  SessionID: "scan-session",
})
if err != nil {
  log.Fatal(err)
}

Rust

client
    .send_code(
        "INV-2026-001",
        CodeOptions {
            kind: Some("invoice".into()),
            session_id: Some("scan-session".into()),
            ..Default::default()
        },
    )
    .await?;

Keep A Conversation

Use a conversation when related turns should share the same session.

Python

with client.conversation(lang="en-us") as convo:
    print(convo.ask("Remember that my favorite color is blue.").text)
    print(convo.ask("What color did I mention?").text)

Node.js

const convo = client.conversation({ lang: "en-us" });

const first = await convo.ask("Remember that my favorite color is blue.");
const second = await convo.ask("What color did I mention?");
console.log(first.text, second.text);

Go

convo := client.Conversation(thalovant.ConversationOptions{Lang: "en-us"})

first, err := convo.Ask(ctx, "Remember that my favorite color is blue.", thalovant.RequestOptions{})
if err != nil {
  log.Fatal(err)
}
second, err := convo.Ask(ctx, "What color did I mention?", thalovant.RequestOptions{})
if err != nil {
  log.Fatal(err)
}
fmt.Println(first.Text, second.Text)

Rust

let convo = client.conversation(ConversationOptions {
    lang: Some("en-us".into()),
    ..Default::default()
});

let first = convo
    .ask("Remember that my favorite color is blue.", RequestOptions::default())
    .await?;
let second = convo
    .ask("What color did I mention?", RequestOptions::default())
    .await?;
println!("{} {}", first.text, second.text);

Wait For One Event

Use this when one event proves the request completed.

Python

from thalovant import EVENT_UTTERANCE_HANDLED

event = client.wait_for_event(EVENT_UTTERANCE_HANDLED, timeout=12)
print(event.text)

Node.js

import { EVENT_UTTERANCE_HANDLED } from "@thalovant/sdk";

const event = await client.waitForEvent(EVENT_UTTERANCE_HANDLED, {
  timeoutMs: 12_000,
});
console.log(event.text);

Go

events := client.Transport.Events()

select {
case event := <-events:
  fmt.Println(event.Name, event.Text())
case <-time.After(12 * time.Second):
  log.Fatal("timed out waiting for event")
}

Rust

use std::time::Duration;
use tokio::time::timeout;

let mut events = client.transport.subscribe();

if let Ok(Ok(event)) = timeout(Duration::from_secs(12), events.recv()).await {
    println!("{} {}", event.name, event.text());
}

Stream Events

Use event streams for long-running clients, live status, speech output, and UI updates.

Python

from thalovant import EVENT_SPEAK

for event in client.listen(EVENT_SPEAK, timeout=30, max_events=3):
    print(event.text)

Node.js

import { EVENT_SPEAK } from "@thalovant/sdk";

const subscription = client.on(EVENT_SPEAK, event => {
  console.log(event.text);
});

// Later, when the listener is no longer needed:
subscription.close();

Go

events := client.Transport.Events()

for event := range events {
  fmt.Println(event.Name, event.Text())
}

Rust

let mut events = client.transport.subscribe();

while let Ok(event) = events.recv().await {
    println!("{} {}", event.name, event.text());
}

Build Request Context

Context carries stable user, source, locale, and trace metadata without changing the utterance.

Python

from thalovant import build_client_context

context = build_client_context(
    user_id="user-42",
    user_name="Ada",
    source="checkout-kiosk",
    platform="kiosk",
    locale="en-US",
    metadata={"trace_id": "req-2026-06-10-001"},
)

reply = client.ask("Show the next instruction.", context=context)
print(reply.text)

Node.js

import { buildClientContext } from "@thalovant/sdk";

const context = buildClientContext({}, {
  userId: "user-42",
  userName: "Ada",
  source: "checkout-kiosk",
  platform: "kiosk",
  locale: "en-US",
  channel: "chat",
  metadata: { traceId: "req-2026-06-10-001" },
});

const reply = await client.ask("Show the next instruction.", { context });
console.log(reply.text);

Go

requestContext := thalovant.BuildClientContext(nil, thalovant.ClientContextOptions{
  UserID:   "user-42",
  UserName: "Ada",
  Source:   "checkout-kiosk",
  Platform: "kiosk",
  Locale:   "en-US",
  Channel:  "chat",
  Metadata: map[string]any{"trace_id": "req-2026-06-10-001"},
})

reply, err := client.Ask(ctx, "Show the next instruction.", thalovant.RequestOptions{
  Context: requestContext,
})

Rust

use serde_json::json;

let mut metadata = serde_json::Map::new();
metadata.insert("trace_id".into(), json!("req-2026-06-10-001"));

let context = build_client_context(None, ClientContextOptions {
    user_id: Some("user-42".into()),
    user_name: Some("Ada".into()),
    source: Some("checkout-kiosk".into()),
    platform: Some("kiosk".into()),
    locale: Some("en-US".into()),
    channel: Some("chat".into()),
    metadata: Some(metadata),
    ..Default::default()
});

let reply = client
    .ask(
        "Show the next instruction.",
        RequestOptions {
            context: Some(context),
            ..Default::default()
        },
    )
    .await?;

Tip

Context should explain the request later. Do not put passwords, API tokens, full identity files, or private user profiles in request context.

Run Diagnostics

Use diagnostics when a client cannot connect, a protocol is missing, or an event never arrives.

Python

print(client.doctor())

Node.js

console.log(await client.healthcheck());

Go

fmt.Println(client.Healthcheck())

Rust

println!("{:?}", client.healthcheck().await);

Protocol Values

Use the SDK protocol enum or string that matches your language.

Protocol	Python	Node.js	Go	Rust
WSS	"wss"	"wss"	thalovant.ProtocolWSS	HubProtocol::Wss
HTTPS	"https"	"https"	thalovant.ProtocolHTTPS	HubProtocol::Https
MQTT	"mqtt"	"mqtt"	thalovant.ProtocolMQTT	HubProtocol::Mqtt

When no protocol is forced, SDKs prefer WSS, then HTTPS, then MQTT when the identity includes broker credentials.

Common Build Patterns

1. Discover a hub. Use list_public_hubs, get_public_hub, list_hubs, or get_hub.
2. Create or load identity material. Use create_client_identity for new clients, or load an existing identity from config, file, or environment.
3. Choose a protocol. Start with WSS unless your deployment needs HTTPS or MQTT.
4. Send one request. Use ask first because it gives a clear reply.
5. Add events and context. Add listen, wait_for_event, and build_client_context once the basic request works.

Quick Reference

Use this table only when you already know the task and need the language-specific name.

Control Plane

Task	Python	Node.js	Go	Rust
Create API client	ThalovantControlPlane()	new ThalovantControlPlane()	NewDefaultControlPlane(token)	ControlPlane::default()
Sign in	login(email, password)	login(email, password)	Login(ctx, email, password, scope)	login(email, password, scope)
Sign in with MFA	login(..., otp_code=..., recovery_code=...)	login(..., { otpCode, recoveryCode })	LoginWithOptions(ctx, email, password, options)	login_with_options(email, password, options)
Sign in without a password	login_with_browser(...)	loginWithBrowser(options)	LoginWithBrowser(ctx, options)	login_with_browser(options)
Use an API token	ThalovantControlPlane(access_token=...)	new ThalovantControlPlane(url, { accessToken })	NewDefaultControlPlane(token)	ControlPlane::with_access_token(token)
List public hubs	list_public_hubs(...)	listPublicHubs(...)	ListPublicHubs(ctx, limit, cursor)	list_public_hubs(limit, cursor)
Get public hub	get_public_hub(ref)	getPublicHub(ref)	GetPublicHub(ctx, ref)	get_public_hub(ref)
List visible hubs	list_hubs(...)	listHubs(...)	ListHubs(ctx, limit, cursor, ownerID)	list_hubs(limit, cursor, owner_id)
Get hub	get_hub(hub_id)	getHub(hubId)	GetHub(ctx, hubID)	get_hub(hub_id)
Get operation	get_operation(operation_id)	getOperation(operationId)	GetOperation(ctx, operationID)	get_operation(operation_id)
Create identity	create_client_identity(...)	createClientIdentity(...)	CreateClientIdentityForHubID(...)	create_client_identity_for_hub_id(...)

The provisioning calls have their own naming table on Provision Hubs.

Identity

Task	Python	Node.js	Go	Rust
Load identity from config	ThalovantIdentity.from_config(...)	ThalovantIdentity.fromConfig(...)	IdentityFromConfig(path, profile)	Identity::from_config(profile)
Load identity file	ThalovantIdentity.from_file(path)	ThalovantIdentity.fromFile(path)	IdentityFromFile(path)	Identity::from_file(path)
Load client from file	ThalovantClient.from_identity_file(path)	ThalovantClient.fromIdentityFile(path)	NewClientFromFile(path)	Client::from_file(path)
Load client from config	ThalovantClient.from_config(...)	ThalovantClient.fromConfig(...)	NewClientFromConfig(path, profile)	Client::from_config(profile)
Load client from env	ThalovantClient.from_env()	ThalovantClient.fromEnv()	NewClientFromEnv()	Client::from_env()
Enabled protocols	enabled_protocols()	enabledProtocols()	EnabledProtocols()	enabled_protocols()
Endpoint for protocol	endpoint_for(protocol)	endpointFor(protocol)	EndpointFor(protocol)	endpoint_for(protocol)
Check protocol	supports_protocol(protocol)	supportsProtocol(protocol)	SupportsProtocol(protocol)	supports_protocol(protocol)
MQTT credentials	identity.mqtt	identity.mqtt	Identity.MQTT	identity.mqtt

Runtime Client

Task	Python	Node.js	Go	Rust
Create protocol client	ThalovantClient(identity, protocol="wss")	new ThalovantClient(identity, { protocol })	NewClientWithOptions(identity, ClientOptions{Protocol: ...})	Client::with_protocol(identity, protocol)
Connect	connect()	connect()	Connect(ctx)	connect()
Close	close()	close()	Close(ctx)	close()
Health	healthcheck()	healthcheck()	Healthcheck()	healthcheck()
Ask	ask(text, ...)	ask(text, options)	Ask(ctx, text, options)	ask(text, options)
Emit raw event	emit(event, data, context)	emit(event, data, context)	Emit(ctx, event, data, context)	emit(event, data, context)
Send utterance	send_utterance(text, ...)	sendUtterance(text, options)	SendUtterance(ctx, text, options)	send_utterance(text, options)
Send action	send_action(payload, ...)	sendAction(payload, options)	SendAction(ctx, payload, options)	send_action(payload, options)
Send code	send_code(value, ...)	sendCode(value, options)	SendCode(ctx, value, options)	send_code(value, options)
Conversation	conversation(...)	conversation(options)	Conversation(options)	conversation(options)

Events, Context, And Output

Task	Python	Node.js	Go	Rust
Wait for event	wait_for_event(name, ...)	waitForEvent(name, options)	client.Transport.Events() with timeout	client.transport.subscribe() with timeout
Stream events	listen(name, ...)	on(name, handler, options)	client.Transport.Events()	client.transport.subscribe()
Diagnostics	doctor()	healthcheck()	Healthcheck()	healthcheck()
Build context	build_client_context(...)	buildClientContext(...)	BuildClientContext(...)	build_client_context(...)
Response text	reply.text	reply.text	reply.Text	reply.text
Display items	reply.display_items(...)	reply.displayItems(...)	reply.DisplayItems(...)	reply.display_items(...)
Event text	event.text	event.text	event.Text()	event.text()

Related Pages

SDKsInstall and make the first request.

Provision HubsScopes, plan gates, etags, and provisioning errors.

Sessions and ContextPass stable metadata through requests.

Events and OutputReplies, display items, and event streams.

ActionsButtons, scans, codes, and structured commands.

MQTTBroker credentials, TLS, and topics.