TypeScript SDK

@trickroom/client wraps the REST API for your backend: typed calls for users, jobs, connected accounts, flows and approvals, idempotent retries, and errors that keep the API’s code. It uses the standard fetch, so it runs on Node.js 18 or later and other runtimes that have it.

Install

Shell

npm install @trickroom/client

Preview: @trickroom/client isn’t on npm yet. These pages document it as it will ship; until then, call the REST API directly. Methods follow the v1 API, which only adds fields, so ignore fields you don’t use.

Configure

Create an application key in Settings → API keys; the Backend preset covers users, jobs and their files. Keep it in your server’s environment, never in browser or mobile code.

Backend environment

TRICKROOM_API_URL=https://your-deployment.example/v1
TRICKROOM_API_KEY=tak_…

Create a client

One client per process. Its key decides the application, so there is no application ID to pass.

TypeScript

import { Trickroom } from "@trickroom/client";

const client = new Trickroom({
  baseUrl: process.env.TRICKROOM_API_URL!,
  apiKey: process.env.TRICKROOM_API_KEY!,
});

const user = await client.users.create({ external_id: "customer_123" });
const job = await client.jobs.create(
  { user_id: user.id, task: "Summarize this text: we shipped v1.", execution_mode: "tools" },
  "first-summary",
);
const done = await client.jobs.wait(job.id);

The cheatsheet has an example for each part of the client.

What’s in the client

Client

Trickroom: The client. One per backend process, with an application key.
TrickroomError: What every method throws when the API refuses a call.

Resources

client.application: The application the key belongs to.
client.users: Your product's users, each with a computer and connections.
client.jobs: Tasks an agent runs for one user.
client.connections: Accounts a user connected, and ways to connect more.
client.flows: Versioned, repeatable tasks with named inputs.
client.skills: Procedures the application's jobs can follow.
client.harnesses: Named settings the application's jobs run with.
client.plugins: Which integrations jobs may use, and how much they may do unasked.
client.approvals: Actions and payments waiting for a person to decide.

Assistants and evaluation

client.assistants: Chat assistants and their versions.
client.conversations: Chats between a user and an assistant, with memories.
client.events: Events that start assistant work.
client.triggers: Schedules and conditions that start assistants.
client.alerts: Email alerts that interrupt a user only when it matters.
client.subscriptions: Delivery of events to your backend, pushed or polled.
client.feedback: Ratings and corrections on assistant replies.
client.evals: Evaluation suites and their runs.
client.datasets: References to data used by evaluations and pipelines.
client.pipelines: Runs of your own training or data pipelines, reported to Trickroom.
client.models: Model endpoints you connect yourself.
client.inference: Saved model requests and responses.