TSFM.ai developer documentation.

Multiple pages, one contract. API, MCP, and CLI are aligned on the same schema so teams can move from manual calls to production automation with zero drift.

SDKs

Official client libraries

Typed clients for TypeScript and Python that wrap the TSFM.ai REST API. Both SDKs bundle the OpenAPI schema locally, discover operations at runtime, and expose a single TsfmClient class with a call(operationId, ...) interface. Zero external dependencies.

Install

terminal

npm install @tsfm-ai/tsfm-sdk

Quick start

Create a client, call an operation by id, and get typed results back.

forecast.ts

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

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

// Run a forecast
const result = await client.call("forecast", {
  body: {
    model: "amazon/chronos-t5-large",
    inputs: [{ item_id: "series_1", target: [101, 102, 103, 104, 105, 106] }],
    parameters: { prediction_length: 12, freq: "D", quantiles: [0.1, 0.5, 0.9] },
  },
});

console.log(result.predictions);

Authentication

Both SDKs send a Bearer token with every request. The credential is resolved in this order:

Explicit token passed to constructor (session tokens).
Explicit apiKey / api_key passed to constructor.
TSFM_API_KEY environment variable as automatic fallback.

Operation discovery

Both SDKs bundle the OpenAPI schema and can list or inspect operations without making a network request.

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("forecast");
console.log(spec);

Error handling

Non-2xx responses throw an ApiError with the HTTP status, operation id, and parsed response body.

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);
  }
}

Constructor options

Both SDKs accept the same options — TypeScript uses camelCase, Python uses snake_case.

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).