Quickstart

5 min

Create or reuse an API key, validate auth, list a model, and send your first forecast request in a few minutes.

Prerequisites

A TSFM.ai account with access to /account/keys.
Shell access with curl; jq is optional but useful for formatting responses.
A place to store TSFM_API_KEY, such as your shell profile, CI secret store, or platform secret manager.

Step 1

Create credentials

The normal production path is: create a user account in the app, mint an API key from Account → API Keys, then keep that key in server-side secret storage. Direct registration is still useful for demos and local smoke tests.

UI key-creation flow

1Open `/account/keys` in the app and create one key per environment or workload.
2Copy the key once, then store it in your secret manager before closing the dialog.
3Export it locally as `TSFM_API_KEY` so the same examples work in curl, the CLI, and the SDKs.
4Keep browser session tokens for interactive account work only; use API keys for server-to-server calls.

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"
  }'

Step 2

Choose a forecast-ready model

Before you send inference traffic, shortlist one or two models from the catalog. This keeps the first forecast request intentional instead of guessing at model ids from examples.

models.sh

Read model discovery guide

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",
      "supported_tasks": ["forecast"],
      "capabilities": ["forecasting", "quantile-forecasting", "multivariate", "covariates"],
      "avg_latency_ms": 240,
      "context_length": 8192
    },
    {
      "id": "ibm/ttm-r2",
      "supported_tasks": ["forecast"],
      "capabilities": ["forecasting", "point-forecasting", "high-throughput"],
      "avg_latency_ms": 95,
      "context_length": 4096
    }
  ]
}

Confirm `supported_tasks` includes `forecast` before you compare anything else.
Use `avg_latency_ms` and cost fields to pick a sensible default and fallback for your traffic shape.
Check capabilities such as covariates or long-context support if your payload needs them.

Step 3

Validate auth before inference

Hit /v1/validate once before you wire forecasting into CI or production jobs. It confirms that the presented key exists, is active, and resolves to the account you expect.

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"
}

Step 4

Send a forecast request

Use the canonical request shape: { model, inputs, parameters }. This exact payload moves cleanly into the SDKs, CLI, MCP tools, and playground without a contract rewrite.

forecast.sh

Forecast field reference

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"
    }
  }'

Step 5

Inspect the response

Do not stop at “it returned 200”. Confirm the forecast horizon, uncertainty bands, and timestamps before you move on to charts, alerts, or automated decisions.

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"
  }
}

predictions[].mean length matches parameters.prediction_length.
predictions[].quantiles includes every quantile you requested.
usage.total_tokens equals input_tokens + output_tokens.
timestamps[] advances at the cadence implied by your request freq.

Common first-run failures

`valid: false` from `/v1/validate`

The key is revoked, copied incorrectly, or not being passed from the environment you think it is. Fix auth before you debug request payloads.

`401 invalid_credential` on `/v1/forecast`

You are missing the `Authorization: Bearer $TSFM_API_KEY` header or the key belongs to a different environment than the one you are testing.

`400` or `422` validation errors

Check that `inputs[]` is an array, `prediction_length` is present, and any timestamp or covariate arrays align to the history or horizon they describe.

Next steps

Authentication and API keys

Credential types, validation behavior, and rotation guidance.

Forecast API

Canonical request and response fields for `/v1/forecast`.

Models and discovery

Learn how to filter the catalog and choose a default plus fallback model.

CLI

Inspect operations and automate smoke checks from CI.