API Reference — TSFM.ai

API reference

Browse endpoint families, auth behavior, OpenAPI links, and the fastest way to find the right request path for your integration.

OpenAPI schema Forecast API

Base URLs

Start from the canonical API host

Every example in the docs assumes the public API origin at https://api.tsfm.ai. Keep that host explicit in automation and client constructors so environment mismatches are easy to spot when debugging.

Core surfaces

Field	Type	Required	Description
https://api.tsfm.ai	base URL	Yes	Primary HTTPS origin for all documented REST endpoints, including `/v1/forecast`, `/api/models`, and account routes.
/openapi.json	schema document	No	Authoritative machine-readable contract used by generated tooling, operation inspection, and schema-aware integrations.
/api/schema	schema alias	No	Convenience alias for the OpenAPI schema when older tooling expects an `/api/*` path.
/healthz / /api/system/status	health and status	No	Use for liveness checks, readiness probes, and lightweight operator dashboards before you begin authenticated calls.

schema.sh

curl -s https://api.tsfm.ai/openapi.json | jq '.paths | keys[]'

Source of truth: OpenAPI

The live OpenAPI schema describes the contract that powers HTTP, the generated CLI, SDK helpers, and MCP tool names. Use it when you need the latest operation list or want to confirm an operation id exactly.

View live OpenAPI schema

All request and response bodies are JSON unless an endpoint explicitly returns SSE (text/event-stream).
Auth is Bearer token in Authorization header. API keys, OAuth tokens, and session tokens all use Bearer syntax when sent programmatically.
Forecast responses return stable wrapper fields such as object, created, horizon, prediction_length, and usage.
Application-level errors expose { error, code } for recovery logic; payload and validation issues still surface through standard HTTP status codes such as 400 or 422.
Recurring automation lives under /v1/schedules and uses the same forecast parameters object as direct inference calls.

Start here

The four routes most teams touch first

The full API surface is broader than most first integrations need. These entry points cover contract discovery, credential validation, model selection, and the canonical forecast call that everything else builds on.

If you need to...	Start with	Why it matters
Confirm the live contract or inspect operation ids	GET /openapi.json	The generated CLI, SDK helpers, and MCP tool names all derive from the OpenAPI schema.
Check whether a key or token is valid before protected calls	POST /v1/validate	Validate once during setup, after rotation, and before long-running automation jobs.
Find a model that supports the task you want	GET /api/models	List first, shortlist by search or task, then fetch one model detail for deeper inspection.
Run production inference with the canonical TSFM payload	POST /v1/forecast	This is the stable forecast surface used by the playground, SDKs, CLI, and MCP tools.

Common workflows

Work from concrete requests, not just route lists

These examples cover the operational sequence most teams use in practice: verify the credential, shortlist a model, then send a canonical forecast request. Use them as the baseline before you expand into schedules, batch jobs, or multi-step evaluation flows.

Validate credentials before automation

Treat `/v1/validate` as a deployment check. It is the fastest way to catch expired keys, malformed secrets, or account mismatches before a scheduled job starts failing.

Send either `{"api_key":"..."}` in the body or a bearer header if your client already has one.
Use the returned `auth_type` to confirm you are using the credential class you expect.
Run it immediately after key creation or rotation, then cache only the credential metadata you need.

validate.sh

curl -X POST https://api.tsfm.ai/v1/validate \
  -H "Content-Type: application/json" \
  -d '{"api_key":"'$TSFM_API_KEY'"}'

validate.response.json

{
  "valid": true,
  "auth_type": "api_key",
  "user": "44d1e8a7-8b33-4dcf-a65a-b8a8e02ca9aa",
  "key": "tsfm_liv"
}

Discover models before you hardcode one

List candidates first, then fetch a specific model only after you know which ids are worth evaluating. That keeps initial integrations simple and gives you a clean path to routing logic later.

Start with a narrow search term or task filter to keep results short enough to inspect.
Read `supported_tasks`, `avg_latency_ms`, and `capabilities` before benchmarking on your own data.
Use the model id you select here directly in `/v1/forecast` requests without translation.

models.sh

curl -s "https://api.tsfm.ai/api/models?q=chronos" | jq '.models | map({
  id,
  supported_tasks,
  avg_latency_ms
})'

models.response.json

{
  "models": [
    {
      "id": "amazon/chronos-bolt-base",
      "provider": "tsfm (us)",
      "supported_tasks": ["forecast"],
      "avg_latency_ms": 240,
      "context_length": 8192,
      "capabilities": ["forecasting", "quantile-forecasting", "multivariate", "covariates"]
    },
    {
      "id": "ibm/ttm-r2",
      "provider": "tsfm (us)",
      "supported_tasks": ["forecast"],
      "avg_latency_ms": 95,
      "context_length": 4096,
      "capabilities": ["forecasting", "point-forecasting", "high-throughput"]
    }
  ]
}

Promote a request shape that can survive into production

The canonical forecast contract is the operational baseline. If you standardize on `{ model, inputs, parameters }`, the same payload can move across curl, SDKs, CI smoke tests, and internal tooling.

Persist the response `id`, `model`, `usage`, and `latency_ms` so you can trace expensive or slow requests later.
Keep `item_id` stable across retries and batch jobs; it is the cleanest join key for downstream charts and warehouse tables.
When you need covariates, batching, or ensembles, keep the same top-level structure and expand from there.

forecast.sh

curl -X POST https://api.tsfm.ai/v1/forecast \
  -H "Authorization: Bearer $TSFM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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]
    },
    "metadata": {
      "surface": "docs.quickstart"
    }
  }'

forecast.response.json

{
  "id": "8de64ea3-1d1e-4e72-87f0-0ac4a0c2693b",
  "object": "forecast",
  "created": 1773369600,
  "model": "amazon/chronos-bolt-small",
  "provider": "harpoon",
  "horizon": 7,
  "prediction_length": 7,
  "quantile_levels": [0.1, 0.5, 0.9],
  "input_points": 10,
  "predictions": [{
    "item_id": "store_017",
    "mean": [478.1, 482.6, 487.4, 491.8, 495.2, 499.3, 503.0],
    "quantiles": {
      "0.1": [470.9, 474.1, 478.0, 481.8, 484.6, 488.1, 491.4],
      "0.5": [478.1, 482.6, 487.4, 491.8, 495.2, 499.3, 503.0],
      "0.9": [485.5, 491.3, 496.1, 501.0, 505.7, 510.8, 515.2]
    },
    "timestamps": [
      "2026-02-11T00:00:00Z",
      "2026-02-12T00:00:00Z",
      "2026-02-13T00:00:00Z",
      "2026-02-14T00:00:00Z",
      "2026-02-15T00:00:00Z",
      "2026-02-16T00:00:00Z",
      "2026-02-17T00:00:00Z"
    ]
  }],
  "usage": {
    "input_tokens": 128,
    "output_tokens": 21,
    "total_tokens": 149
  },
  "latency_ms": 38.4,
  "metadata": {
    "surface": "docs.quickstart"
  }
}

Operational behavior

Auth and rate-limit details clients should actually log

Most integration issues are not caused by the happy-path JSON payload. They come from credentials expiring, using the wrong token class, or ignoring the headers that explain why requests are slowing down or being rejected.

Credential types

Field	Type	Required	Description
Session token	Bearer token	Conditional	Issued by `/api/auth/register` or `/api/auth/login`; best for interactive account flows. Browser-cookie sessions can use the web playground, while programmatic bearer use still consumes free credits or metered billing.
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, key? }`.

Rate-limit headers

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 failure codes

Field	Type	Required	Description
missing_credential	400	No	No bearer token or `api_key` was provided for an authenticated route.
invalid_credential	401	No	Token/API key not found, expired, or revoked.
invalid_credentials	401	No	Incorrect email/password pair on login.
billing_required	402	No	Free credits are exhausted and billing is not active. Set up billing to continue programmatic inference after the initial 500 credits.
no_model_access	403	No	Account does not have access to the requested model.
model_not_found	404	No	The requested model id does not exist in catalog.
conflict	409	No	Resource conflict (e.g. duplicate key name or email already registered).
validation_error	422	No	Request body failed schema validation.
rate_limit_exceeded	429	No	Rate limit exceeded (1,000 rpm free; 1,000,000 rpm with billing).
grpc_error	502	No	Inference gateway encountered an error communicating with the upstream model service.

Endpoint families

Browse the platform by domain

System + Schema

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

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

Model Catalog

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

Model discovery guide

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

Auth + Account

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

Auth and API keys

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

Forecasting + Inference

Forecast-native TSFM interfaces for time-series inference.

Forecast API contract

Method	Auth	Path	Operation id	Summary
POST	Bearer	/v1/forecast	forecast	Canonical TSFM forecast
POST	Bearer	/v1/forecast/batch	forecastBatch	Batch forecast jobs
POST	Bearer	/v1/forecast/ensemble	forecastEnsemble	Rank multiple models and return a weighted blend
POST	Public	/v1/validate	validateCredential	Validate token/API key

Forecast Schedules

Recurring forecast jobs with automatic data fetching and webhook delivery.

Method	Auth	Path	Operation id	Summary
POST	Bearer	/v1/schedules	createSchedule	Create recurring schedule
GET	Bearer	/v1/schedules	listSchedules	List user schedules
GET	Bearer	/v1/schedules/{scheduleId}	getSchedule	Get schedule detail
PATCH	Bearer	/v1/schedules/{scheduleId}	updateSchedule	Update schedule config
DELETE	Bearer	/v1/schedules/{scheduleId}	deleteSchedule	Soft-delete schedule
POST	Bearer	/v1/schedules/{scheduleId}/pause	pauseSchedule	Pause schedule
POST	Bearer	/v1/schedules/{scheduleId}/resume	resumeSchedule	Resume schedule
GET	Bearer	/v1/schedules/{scheduleId}/runs	listScheduleRuns	List run history

Reference map

Jump into the focused reference pages

This page is intentionally the API index. Use the pages below when you need the canonical forecast payload, model-selection inputs, or the operational details around errors and rate limits.

Forecast API

Canonical request fields, covariates, quantiles, and response interpretation.

Models and discovery

Model catalog endpoints, capabilities, and routing guidance.

Errors and limits

Common failure codes, rate-limit headers, and production recovery guidance.