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.

API Reference

HTTP endpoints

Source of truth is OpenAPI: /openapi.json and /api/schema. MCP tools and CLI commands are generated from the same operation ids listed below.

View live OpenAPI schema →

Request and response conventions

All request and response bodies are JSON unless an endpoint explicitly returns SSE (text/event-stream).
Auth is Bearer token in Authorization header. Session tokens and API keys both use Bearer format.
Unknown routes return { error, code } with 404.
Validation and payload shape errors return 400 with a stable code field.
Endpoint compatibility aliases are accepted for forecast payloads to reduce migration pain.

Auth reference

Session and API key credentials both use Bearer format.

Field	Type	Required	Description
Session token	Bearer token	Conditional	Issued by `/api/auth/register` or `/api/auth/login`; accepted across account and inference endpoints.
API key	Bearer token	Conditional	Created on `/api/account/keys`; intended for server-to-server inference and automation.
Credential validation	POST /v1/validate	No	Accepts `api_key` or bearer header and returns `{ valid, auth_type, user }`.

System + Schema

Health, status, and source-of-truth contract discovery.

Method	Path	Operation Id	Summary	Auth
GET	/healthz	getHealth	Service health	None
GET	/api/system/status	getSystemStatus	Runtime status + regions	None
GET	/openapi.json	getOpenApiSchema	OpenAPI schema	None
GET	/api/schema	getApiSchema	OpenAPI schema alias	None

Model Catalog

Discover TSFMs and route by capabilities, cost, and latency.

Method	Path	Operation Id	Summary	Auth
GET	/api/models	listModels	Catalog list with filters	None
GET	/api/models/{modelId}	getModelById	Catalog detail	None
GET	/v1/models	listOpenAiModels	OpenAI-compatible model list	None
GET	/v1/models/{modelId}	getOpenAiModelById	OpenAI-compatible model detail	None

Auth + Account

User auth, API keys, usage, and billing state.

Method	Path	Operation Id	Summary	Auth
POST	/api/auth/register	registerUser	Create account + session token	None
POST	/api/auth/login	loginUser	Login + session token	None
GET	/api/auth/oauth/start	startOAuth	Begin Google/GitHub OAuth	None
GET	/api/auth/oauth/callback/{provider}	completeOAuthCallback	OAuth callback completion redirect	None
POST	/v1/validate	validateCredential	Validate token/API key	None
GET	/api/account/me	getAccountMe	Current user	Bearer token/API key
GET	/api/account/keys	listAccountKeys	List API keys	Bearer token/API key
POST	/api/account/keys	createAccountKey	Create API key	Bearer token/API key
DELETE	/api/account/keys/{keyId}	revokeAccountKey	Revoke key	Bearer token/API key
GET	/api/account/usage	listUsageEvents	Usage events	Bearer token/API key
GET	/api/account/billing	getBillingSummary	Billing summary	Bearer token/API key
GET	/api/account/billing/stripe	getStripeBillingProfile	Stripe profile	Bearer token/API key
POST	/api/account/billing/stripe	createStripeBillingSession	Create Stripe checkout/portal session	Bearer token/API key

Forecasting + Inference

Forecast-native TSFM interfaces for time-series inference.

Method	Path	Operation Id	Summary	Auth
POST	/v1/series/ingest	ingestSeriesSource	Normalize series from URL or inline payload	Bearer token/API key
POST	/v1/forecast	forecast	Canonical TSFM forecast	Bearer token/API key
POST	/v1/detect-anomalies	detectAnomalies	Anomaly detection	Bearer token/API key
POST	/v1/forecast/batch	forecastBatch	Batch forecast jobs	Bearer token/API key
POST	/v1/classify	classifySeries	Roadmap placeholder (501)	Bearer token/API key
POST	/v1/impute	imputeSeries	Roadmap placeholder (501)	Bearer token/API key
POST	/v1/finetune	finetuneModel	Roadmap placeholder (501)	Bearer token/API key
POST	/v1/cross-validate	crossValidate	Roadmap placeholder (501)	Bearer token/API key

Rate limit headers

Present on inference responses and forwarded when available from upstreams.

Field	Type	Required	Description
x-ratelimit-limit	string	No	Configured request limit for the current window.
x-ratelimit-remaining	string	No	Remaining requests in the current rate-limit window.
x-ratelimit-reset	string (unix seconds)	No	Timestamp when the current window resets.
retry-after	string (seconds)	No	Returned when the upstream or gateway asks clients to slow down.

Common error codes

Errors return consistent shape: { error, code }.

Field	Type	Required	Description
missing_credential	400	No	No bearer token or `api_key` provided for `/v1/validate`.
invalid_credential	401	No	Token/API key not found, expired, or revoked.
invalid_credentials	401	No	Incorrect email/password pair on login.
model_not_found	404	No	The requested model id does not exist in catalog.
not_implemented	501	No	Roadmap endpoint called before GA support.
upstream_timeout	504	No	Inference gateway timeout waiting for upstream model response.