AI agents

Reference guidance for AI agents that need to retrieve TSFM.ai documentation, choose the right source page, and execute forecasting workflows safely.

Forecast API MCP guide

Why this page exists

This page is for AI agents that need to search TSFM.ai documentation and decide which references to trust for a given task. The goal is not just to point at every docs page. It is to help an agent retrieve the minimum useful set of references, in the right order, so it can answer accurately and act safely.

If an agent is helping with forecasting, the docs should function as the reference bundle it retrieves and uses. Quickstart establishes the first-run flow, Models narrows the model choice, Forecasting defines the canonical payload, and Errors and limits handles the failure path.

Retrieval order

Retrieve by job, not by doc title

Start with Quickstart for first-run flows

If the task sounds like setup, onboarding, or “how do I do my first forecast?”, retrieve Quickstart before you retrieve deeper references.

Use Authentication when credentials are involved

If the task mentions API keys, validation, rotation, session tokens, or failed auth, retrieve Authentication and API keys immediately.

Use Models before choosing defaults

If the task involves model choice, latency, cost, or capabilities such as covariates, retrieve Models and discovery before making a recommendation.

Use Forecasting for payload truth

If the task is about request or response shape, covariates, timestamps, quantiles, batching, or ensembles, Forecasting is the canonical reference.

Use Errors and limits for retries and failures

If a request failed or an automation path needs recovery logic, retrieve Errors, auth, and rate limits alongside the primary task page.

Reference bundle

The core pages an agent should retrieve

Quickstart

Best for first-run setup, first request flow, validation, and response inspection.

Authentication and API keys

Best for Bearer credentials, validation, rotation, and surface-specific auth behavior.

Models and discovery

Best for model selection, capability filtering, and routing policy.

Forecasting API

Best for request semantics, canonical payloads, validation rules, and response interpretation.

Errors and limits

Best for failure codes, retry behavior, throttling, and operational recovery.

MCP

Best when the agent is operating through a hosted MCP client rather than raw HTTP, SDK, or CLI.

Example workflow

Example: what an agent should retrieve and use

If the agent is answering a forecasting question, this is the retrieval pattern it should follow. It should not jump directly to writing code before it has verified the workflow, model choice, and canonical request shape.

agent-retrieval-plan.txt

User asks: "Use TSFM.ai to forecast daily sales for my store data"

Agent retrieval order:
1. /docs/quickstart
2. /docs/models
3. /docs/forecast
4. /docs/errors-and-limits (if validation or retry logic matters)

Answer shape:
- choose a forecast-ready model
- validate auth
- send the canonical { model, inputs, parameters } payload
- explain what to inspect in the response

agent-forecast-workflow.sh

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

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

# send a forecast
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]
    }
  }'

Choose an interface

Pick the execution surface that matches the agent

MCP

Use when the agent is embedded in ChatGPT, Claude, Cursor, or another MCP-compatible client and can discover tools directly from the TSFM.ai endpoint.

HTTP API

Use when the task needs explicit request construction, canonical endpoint names, or exact payload control.

SDKs

Use when the task is implementation-oriented and the user is working in TypeScript or Python application code.

CLI

Use when the task is operator-driven, CI-oriented, or best expressed as a schema-aligned terminal workflow.

validate.sh

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

models.sh

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

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