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.

Quickstart

Make your first forecast call in under a minute

This flow is intentionally minimal: create credentials, validate auth, send one forecast request, and verify usage fields in the response. After that, you can switch to CLI or MCP without changing payload shape.

Prerequisites

A TSFM.ai account with access to account pages.
An API key created from Account -> API Keys.
Shell tooling with curl and jq (optional but helpful).
A model id from /api/models (for example amazon/chronos-2).

1. Register

Use auth endpoints directly or create account in UI. Registration returns a session token.

2. Validate key

Verify key/token before inference using /v1/validate. This catches revoked keys early.

3. Forecast

Send canonical payload to /v1/forecast and read predictions + usage.

curl -X POST https://api.tsfm.ai/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "founder@company.com",
    "password": "change-me-before-prod",
    "name": "Forecast Team"
  }'

validate.sh

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

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-2",
    "inputs": [{
      "item_id": "series_1",
      "start": "2026-01-01",
      "target": [101.1, 102.3, 103.8, 103.2, 104.6, 105.0]
    }],
    "parameters": {
      "prediction_length": 12,
      "freq": "D",
      "quantiles": [0.1, 0.5, 0.9]
    }
  }'

forecast.response.json

{
  "id": "forecast_9a4f0df8",
  "model": "amazon/chronos-2",
  "provider": "metis-tsfm-mock",
  "predictions": [{
    "item_id": "series_1",
    "mean": [106.1, 106.8, 107.2, 108.0, 108.6, 109.1, 109.7, 110.0, 110.4, 110.9, 111.2, 111.8],
    "quantiles": {
      "0.1": [104.4, 104.8, 105.1, 105.7, 106.0, 106.4, 106.8, 107.0, 107.2, 107.6, 107.8, 108.1],
      "0.5": [106.1, 106.8, 107.2, 108.0, 108.6, 109.1, 109.7, 110.0, 110.4, 110.9, 111.2, 111.8],
      "0.9": [107.6, 108.6, 109.3, 110.2, 111.1, 111.9, 112.6, 113.0, 113.5, 114.1, 114.8, 115.4]
    }
  }],
  "usage": {
    "input_tokens": 154,
    "output_tokens": 36,
    "prompt_tokens": 154,
    "completion_tokens": 36,
    "total_tokens": 190
  },
  "latency_ms": 42
}

What to validate in the response

predictions[].mean length should match requested horizon.
predictions[].quantiles should include every requested quantile key.
usage.total_tokens should equal input + output token counts.
latency_ms should remain inside your SLO threshold for chosen model tier.

Troubleshooting quick map

Issue	Likely cause	Fix
401 invalid_credential	Using a revoked key or malformed Bearer header.	Run `/v1/validate` and regenerate key from `/api/account/keys` if needed.
400 request_failed	Payload JSON shape is invalid or missing required fields.	Start from canonical `inputs[] + parameters` format and verify with CLI inspect.
404 model_not_found	Model id typo or stale id.	Fetch `/api/models` and use exact id returned by catalog.
504 upstream_timeout	Provider timed out for current horizon/context size.	Reduce horizon/context and retry; configure upstream timeout and fallback routing.

Next steps

Forecast contract Automate with CLI Integrate MCP Production checklist