TypeScript SDK

The Brix TypeScript SDK is a typed client for the REST API. It has one method for each operation in the OpenAPI spec, with request and response types. It has no runtime dependencies and uses the platform fetch, so it runs in Node 18 or later, Deno, Bun, browsers and Cloudflare Workers.

The package name is @brixsignage/sdk. Brix hosts it on brixsignage.com. It is not on the npm registry.

Install

npm install https://brixsignage.com/sdk/latest.tgz

pnpm and yarn take the same URL:

pnpm add https://brixsignage.com/sdk/latest.tgz
yarn add @brixsignage/sdk@https://brixsignage.com/sdk/latest.tgz

latest.tgz is always the newest version. To pin a version, install its own file, for example https://brixsignage.com/sdk/brix-sdk-0.1.0.tgz. The list of versions, with a SHA-256 checksum and the npm integrity hash for each file, is at brixsignage.com/sdk/manifest.json.

Without a package manager

Deno, a browser page or a Worker can import the ES module directly:

import { BrixClient } from "https://brixsignage.com/sdk/v1/index.js";

/sdk/v1/index.js is the newest version. /sdk/<version>/index.js is a fixed version. The type declarations are next to the module (index.d.ts), and Deno finds them without extra setup.

Do not put an API key in code that runs in a browser. Anyone who opens the page can read it. Call the API from a server or a Worker.

Create a client

You need an API key. See Quickstart to make one.

import { BrixClient } from "@brixsignage/sdk";

const brix = new BrixClient({ token: process.env.BRIX_API_KEY! });

Option	Default	What it does
token	none	Your API key (ak_...). Sent as Authorization: Bearer <key>.
baseUrl	https://api.brixsignage.com	The API origin.
timeoutInSeconds	60	Time limit for each request.
maxRetries	2	Retries for a 408, 429, 502, 503 or 504 response, with backoff.
fetch	global fetch	A different fetch implementation.
headers	none	Extra headers on every request.

Example: list screens and assign a playlist

This script prints your screens, then makes the first screen play the first playlist by default. Save it as brix.ts and run it with BRIX_API_KEY=ak_... npx tsx brix.ts.

import { BrixClient, BrixError } from "@brixsignage/sdk";

const brix = new BrixClient({ token: process.env.BRIX_API_KEY! });

async function main() {
  // 1. Who am I? The key's workspace and permissions.
  const { data: me } = await brix.me.getMe();
  console.log("workspace:", me.workspace.name);

  // 2. List screens (up to 50; pass nextCursor as cursor for the next page).
  const { data: screens, nextCursor } = await brix.screens.listScreens({ limit: 50 });
  for (const screen of screens) console.log(screen.id, screen.name, screen.status);
  if (nextCursor) console.log("more screens after", nextCursor);

  // 3. Pick a playlist.
  const { data: playlists } = await brix.playlists.listPlaylists();
  const screen = screens[0];
  const playlist = playlists[0];
  if (!screen || !playlist) return;

  // 4. Assign it: the screen plays this playlist by default from now on.
  await brix.screens.assignContent({ id: screen.id, contentKind: "playlist", contentId: playlist.id });
  console.log(`assigned ${playlist.name} to ${screen.name}`);
}

main().catch((err) => {
  if (err instanceof BrixError) {
    console.error(`Brix API error ${err.statusCode}:`, err.body);
    process.exit(1);
  }
  throw err;
});

The key needs screen.view, screen.edit and playlist.view. contentKind is one of playlist, schedule, layout, creative, signage, app or media. Send contentKind: null to clear the assignment. For many screens at once, use brix.screens.bulkAssignContent({ screenIds, contentKind, contentId }).

Example: cast content for one hour

A cast is a timed takeover. The screens go back to their normal content when it ends.

const { data: cast } = await brix.casts.castContent({
  contentKind: "playlist",
  contentId: "pl_...",
  scopeKind: "screens",
  screenIds: ["scr_..."],
  expiresAt: new Date(Date.now() + 60 * 60_000).toISOString(),
});

// End it early:
await brix.casts.endCast({ id: cast.id });

Always send scopeKind. If you leave it out, the cast goes to every screen the key can reach. The key needs screen.cast.

Errors

A response with a 4xx or 5xx status throws BrixError. It has statusCode and body (the API’s { "error", "message" } object). A request that runs past timeoutInSeconds throws BrixTimeoutError. See Errors and rate limits for each error code.

Types

Every request and response type is in the Brix namespace:

import { Brix } from "@brixsignage/sdk";

const request: Brix.CastContentRequest = { contentKind: "media", contentId: "med_...", scopeKind: "all" };

The type declarations do not need @types/node. They type-check under strict in a browser, Deno, Bun or Workers project with only the DOM and ES2022 libraries. File uploads take a Blob, File, ReadableStream, Uint8Array or ArrayBuffer. In Node they also take a Buffer or a stream from fs.createReadStream.

Find a method

Methods are grouped by resource, the same groups as the API reference: brix.screens, brix.playlists, brix.media, brix.schedules, brix.casts and so on. The method name is the operation’s operationId in the OpenAPI spec. For example, GET /v1/screens is listScreens and POST /v1/screens/{id}/assign is assignContent.

For an endpoint without a method, brix.fetch(path, init) sends a request with the same key, retries and timeout.

Versions and checksums

The SDK is generated from the public OpenAPI spec, so it follows the API. Version numbers use semver. A published version never changes. manifest.json lists each version with:

• tarball.url, tarball.sha256 and tarball.integrity (the npm sha512- hash)
• esm.url and types.url, with their SHA-256
• gitCommit: the source commit it was built from
• specSha256: the OpenAPI document it was generated from

To check a download:

curl -sO https://brixsignage.com/sdk/brix-sdk-0.1.0.tgz
shasum -a 256 brix-sdk-0.1.0.tgz