SDKs - RIVI Software Docs

The RadioTools SDKs wrap the listener API so your website, app, or encoder automation does not need to build requests, follow resource links, or parse responses by hand. They are open source (MIT) and live in the radiotools-sdk repository. All SDKs target listener contract v1 and cover station-facing routes only. Studio administration is not part of the SDKs.

Choose an SDK

TypeScript

The complete client: REST, GraphQL, the public realtime feed, ETag caching, retries, and playback ingest.

Framework bindings

React hooks, Vue composables, Svelte stores, and Next.js server helpers.

Other languages

Starter REST clients for Python, Go, .NET, Ruby, PHP, Kotlin, and Swift.

You are building	Start with
A Node.js, Bun, or edge backend for a listener site	TypeScript
A Next.js site	Next.js helpers
A React, Vue, or Svelte front end that polls a server	Framework bindings
An encoder or automation that reports now-playing tracks	Playback ingest
A backend in another language	Other languages, or call the HTTP operations directly

Feature support

Only the TypeScript client has the full feature set. The framework bindings take a TypeScript client, so you keep its full feature set. The other languages are minimal REST starters.

Capability	TypeScript and framework bindings	Other languages
Published content, schedule, now playing, weather, traffic	Yes	Starter methods; some need extension
Content by slug, sorting, and field filters	Yes	No
GraphQL transport	Yes	No
Public realtime feed	Yes, from a server or a browser	No
ETag conditional reads	Yes	No
Automatic retries on `429` and `503`	Yes	No
Response validation	Yes (Zod)	No
Draft preview handoff	Yes	No
Playback ingest	Yes	Yes

Credentials

Create keys in the dashboard — see Integrations and Authentication.

Use	Credential	Scope	Environment variable
Website, app, or player backend	Station key	`listener:read`	`RADIOTOOLS_API_TOKEN`
Encoder or automation	Integration key named `playback`	`ingest:write`	`RADIOTOOLS_INGEST_TOKEN`

Pass the raw rtm_… secret. The SDK adds the Bearer prefix. Keep both keys on your server; browser code should talk to your own backend, never to RadioTools with a station key. The public realtime feed is the exception: it needs no key, so a browser can subscribe to it directly. The TypeScript, Next.js, Python, Go, .NET, Ruby, and PHP clients have a helper that reads the same environment variables. Kotlin and Swift take the values as arguments.

Variable	Required	Purpose
`RADIOTOOLS_BASE_URL`	Yes	RadioTools origin, for example `https://radiotools.rivi.software`
`RADIOTOOLS_STATION_SLUG`	Yes	The station to read from
`RADIOTOOLS_API_TOKEN`	For reads	Station key with `listener:read`
`RADIOTOOLS_INGEST_TOKEN`	For ingest	Integration key with `ingest:write`

Versioning

The npm packages (@rivi-software/radiotools-sdk, the React, Vue, Svelte, and Next.js bindings, and @rivi-software/radiotools-contract) share one version number and are released together. The current release is 0.3.0. Use 0.3.0 or later for the public realtime feed, content by slug, sorting and field filters, the draft preview handoff, and the card and square media variants. The other-language starters are not part of this release group; see Other languages. The listener contract is versioned separately through contractVersion — see Errors and versioning.

Alternatives

Download the OpenAPI 3.1 document to generate a client in any language or to import into API tools.
Use GraphQL directly with any GraphQL client.

​Choose an SDK

TypeScript

Framework bindings

Other languages

​Feature support

​Credentials

​Versioning

​Alternatives

Choose an SDK

Feature support

Credentials

Versioning

Alternatives