TypeScript SDK
The official Node.js & TypeScript client for the Teradek REST API. Control your Prism encoders with full type safety and automatic OAuth token management.
Installation
Install the SDK from npm:
Quick Start
Create a client and start controlling your encoder in just a few lines:
import { Teradek } from "@teradek/sdk";
const device = new Teradek({
host: "192.168.1.100",
password: "your-device-password",
rejectUnauthorized: false,
});
// Get device info
const info = await device.system.info();
console.log(info.settings["Device Model"]); // "Prism-855"
// Start a stream
await device.streams.start(0);The client automatically handles OAuth token acquisition and refresh. All responses follow the ApiResponse shape:
{
"status": "Success",
"message": "",
"timestamp": 1740000000,
"settings": {
"Device Model": "Prism-855",
"Serial": "12855XXXXX",
"Firmware Version": "2.25.20260122"
}
}Constructor Options
Configure the client with TeradekOptions:
| Option | Type | Default | Description |
|---|---|---|---|
host | string | — | Device IP address or hostname |
password | string | — | Device admin password (for auto token grant) |
accessToken | string | — | Pre-existing access token (skip password grant) |
refreshToken | string | — | Pre-existing refresh token |
https | boolean | true | Use HTTPS for API requests |
rejectUnauthorized | boolean | true | Verify TLS certificates (set to false for self-signed) |
onTokenRefresh | function | — | Callback fired when tokens are refreshed |
const device = new Teradek({
host: "192.168.1.100",
password: "admin-password",
https: true,
rejectUnauthorized: false,
onTokenRefresh: (tokens) => {
// Persist tokens for next session
saveTokens(tokens.access_token, tokens.refresh_token);
},
});Resources
The SDK organizes the API into typed resource namespaces. Each resource maps to a section of the REST API.
device.system
4 methodsDevice info, firmware check, and firmware settings.
await device.system.info()
await device.system.firmware.check()device.encoders
10 methodsVideo/audio settings, metadata, recording, and snapshots.
await device.encoders.info()
await device.encoders.video.getSettings()device.decoders
11 methodsVideo ingest mode, audio output, metadata, recording, and snapshots.
await device.decoders.info()
await device.decoders.video.getMode()device.streams
12 methodsStart, stop, configure, and monitor live streams.
await device.streams.start(0)
await device.streams.info(0)device.network
4 methodsWired ports, Wi-Fi settings, and cellular modems.
await device.network.wired(0)
await device.network.wifi.getSettings()device.settingsSync
2 methodsImport settings and push to other devices.
await device.settingsSync.import(data)
await device.settingsSync.push(payload)Filtering & Describing Settings
All getSettings() and describeSettings() methods accept an optional settings array to filter the response to specific keys. This reduces payload size when you only need a subset of fields.
Filter to specific keys
Pass a settings array to retrieve only those keys. The SDK maps this to the ?settings=key1,key2 query parameter.
// Only fetch codec and bitrate — skips the rest of the video settings
const res = await device.encoders.video.getSettings({
settings: ["codec", "bitrate_list"],
});
console.log(res.settings.codec); // "h264"
console.log(res.settings.bitrate_list); // 20000Describe settings
Use describeSettings() to fetch metadata about each setting — its type, default value, and allowed values — instead of the current values. The SDK sends ?command=description under the hood.
const res = await device.encoders.video.describeSettings();
// Each key returns a descriptor instead of a value
console.log(res.settings.codec);
// { type: "string", default: "h264", choices: ["h264", "hevc"] }
console.log(res.settings.bitrate_list);
// { type: "integer", default: 20000, minimum: 100, maximum: 80000 }Combine filtering with descriptions
Both options can be used together to describe only a subset of keys.
const res = await device.encoders.video.describeSettings({
settings: ["codec", "bitrate_list"],
});Supported resources
| Resource | getSettings() | describeSettings() |
|---|---|---|
device.system.firmware | ✓ | ✓ |
device.encoders.video | ✓ | ✓ |
device.encoders.audio | ✓ | ✓ |
device.encoders.metadata | ✓ | ✓ |
device.encoders.record | ✓ | ✓ |
device.decoders.video | ✓ | ✓ |
device.decoders.audio | ✓ | ✓ |
device.decoders.audio.channel(n) | ✓ | ✓ |
device.decoders.metadata | ✓ | ✓ |
device.decoders.record | ✓ | ✓ |
device.streams | ✓ | ✓ |
device.network.wifi | ✓ | ✓ |
Error Handling
The SDK throws typed error classes for different HTTP status codes, making it easy to handle specific failure modes:
import {
Teradek,
AuthenticationError,
RateLimitError,
} from "@teradek/sdk";
try {
const info = await device.system.info();
} catch (err) {
if (err instanceof AuthenticationError) {
// 401 — token expired or invalid password
console.error("Auth failed:", err.message);
} else if (err instanceof RateLimitError) {
// 429 — back off and retry
console.error("Rate limited, retry after:", err.retryAfter);
} else {
throw err;
}
}| Error Class | Status | When |
|---|---|---|
AuthenticationError | 401 | Invalid or expired credentials |
BadRequestError | 400 | Invalid request parameters |
RateLimitError | 429 | Too many requests |
ServerError | 500 | Internal device error |