SDKs — TSFM.ai

SDKs

Use the TypeScript and Python clients to call the same forecast, model discovery, and schedule operations exposed by the HTTP API.

Start with quickstart Browse operations

Install

Start from TypeScript or Python without changing the API shape

The SDKs are useful when you want less boilerplate than raw HTTP but still need the same payloads and operation ids used by the API, CLI, and MCP server.

terminal

npm install @tsfm-ai/tsfm-sdk

The SDKs stay aligned with the HTTP contract instead of hiding it behind a separate object model.
Both clients expose one `TsfmClient` shape, which keeps examples easy to translate between languages.
Start with a single `call()` and promote the same payloads into services, tests, or notebooks.

Quickstart

Create a client and call the same forecast operation shown elsewhere in the docs

forecast.ts

import { TsfmClient } from "@tsfm-ai/tsfm-sdk";

const client = new TsfmClient({
  apiKey: process.env.TSFM_API_KEY,
});

const result = await client.call("forecast", {
  body: {
    model: "amazon/chronos-bolt-small",
    inputs: [{
      item_id: "store_017",
      start: "2026-02-01T00:00:00Z",
      target: [428, 435, 441, 438, 446, 452, 460, 458, 466, 472],
    }],
    parameters: {
      prediction_length: 7,
      freq: "D",
      quantiles: [0.1, 0.5, 0.9],
    },
  },
});

console.log(result.predictions[0].mean);

Authentication behavior

Pass a session `token` when you need user-scoped account behavior.
Pass an `apiKey` or `api_key` for unattended server-to-server inference.
Both SDKs fall back to `TSFM_API_KEY`, which keeps local scripts simple.

Use the SDKs when you are building application code and want fewer raw HTTP details in your service layer. If you are still exploring the API surface, start with the CLI or the Playground.

Operation discovery

Inspect operations before you wire them into app code

discover.ts

const client = new TsfmClient({ apiKey: process.env.TSFM_API_KEY });

// Discover all available operations
const ops = client.listOperations();
console.log(ops.map((op) => op.operationId));

// Inspect a specific operation
const spec = client.getOperation("createSchedule");
console.log(spec);

Constructor options

TypeScript uses camelCase while Python uses snake_case, but the semantics stay aligned.

Field	Type	Required	Description
apiKey / api_key	string	Conditional	API key for Bearer authentication. Falls back to `TSFM_API_KEY` env var when omitted.
token	string	Conditional	Session token alternative. Takes precedence over `apiKey` when both are set.
baseUrl / base_url	string	No	API base URL. Defaults to `https://api.tsfm.ai`.
timeout	number (ms)	No	Request timeout in milliseconds. Defaults to 60 000 (60 s).

Error handling

Treat non-2xx responses as normal application events

Both SDKs raise an `ApiError` with the HTTP status, operation id, and parsed response body, which makes logging and retry handling much more straightforward.

error-handling.ts

import { TsfmClient, ApiError } from "@tsfm-ai/tsfm-sdk";

const client = new TsfmClient({ apiKey: process.env.TSFM_API_KEY });

try {
  await client.call("forecast", { body: payload });
} catch (error) {
  if (error instanceof ApiError) {
    console.error(error.status, error.operationId, error.body);
  }
}