TypeScript SDK getting started

The repository includes a first-party TypeScript SDK published as @radioso/typescript-sdk.

What you need

Node.js 24+
A Radioso base URL
A personal token or service-account credential

Use a personal token for a client that acts as your current workspace membership; it needs an expiry no more than 90 days away. Use a service-account credential for CI or a long-running service; create the stable identity under Settings → API access, and set each credential to expire within 365 days. Save the one-time secret in a secret manager. The SDK does not cover browser sign-in or credential lifecycle actions.

These workspace credentials are different from the role-free credentials on an agent’s Channels page. Use a REST-audience agent credential with POST /api/v1/agents/{agentId}/chat, or an MCP-audience credential with the standalone MCP server. Neither can replace the SDK’s workspace credential.

Install

bash

npm install @radioso/typescript-sdk

To work on the SDK itself in this repo instead of installing the published package:

bash

cd typescript-sdk
pnpm install --filter @radioso/typescript-sdk...
pnpm run build

Create a client

typescript

import { createRadiosoClient } from '@radioso/typescript-sdk'
 
const client = createRadiosoClient({
  apiToken: process.env.RADIOSO_API_TOKEN!,
})

createRadiosoClient talks to https://api.radioso.ai by default, exported as DEFAULT_BASE_URL. Set baseUrl when your workspace lives somewhere else:

https://api.radioso.ai — the default, EU-hosted instance
https://api-us.radioso.ai — the US-hosted instance
your own origin, for a self-hosted deployment (for example https://radioso.acme.com, or http://localhost:8080 for a local backend)

An API credential only works against the instance that issued it, so baseUrl has to match wherever that workspace’s data actually lives.

First request

List the documents available to that token:

typescript

const documents = await client.documents.list({ limit: 10 })

Then ask the workspace’s default agent a question. If a matching document is indexed, the answer comes back grounded in it rather than as a generic guess:

typescript

const response = await client.chat.create({
  message: 'What does our refund policy say?',
  stream: false,
})
 
console.log(response.answer)

A request that fails throws RadiosoError with a status you can branch on — see Error handling in Basic usage.

Common development commands

From typescript-sdk/:

bash

pnpm run sync
pnpm run test
pnpm run build

pnpm run sync updates the SDK’s generated types from the backend API description.

What the SDK covers

typescript

client.settings.getIngestion(...)
client.settings.updateIngestion(...)
client.settings.reprocessIngestion()
client.settings.getGeneral(...)
client.settings.updateGeneral(...)
 
client.workspace.getSummary()
client.skills.list(...)
client.skills.get(...)
client.agents.list(...)
client.agents.create(...)
client.agents.get(...)
client.agents.update(...)
client.agents.setDefault(...)
 
client.documents.list(...)
client.documents.create(...)
client.documents.importFile(...)
client.documents.get(...)
client.documents.update(...)
client.documents.delete(...)
client.documents.search(...)
client.documents.listHistory(...)
client.documents.getHistory(...)
client.documents.reprocess(...)
client.documents.reprocessSource(...)
 
client.history.list(...)
client.history.listChats(...)
client.history.listSearches(...)
client.history.getChat(...)
client.history.getSearch(...)
client.history.listVisitorConversations(...)
 
client.chat.create(...)              // assistant chat
client.chat.listHistory(...)
client.chat.getHistoryConversation(...)
client.chat.stream(...)

Next step

Move to Basic usage or API first success.