Quickstart

1. Create an account

Sign up in the console with your email address. We send you a sign-in link; open it to verify your email and sign in. There is no password.

2. Add credit

The API draws from a prepaid USD balance, and a request needs enough balance to run. Card top-ups in the console are not available yet: to add credit, contact us at contact@torchcast.ai. See Billing.

3. Create an API key

In the console, open API keys and choose Create key. Copy the key when it is shown: it is displayed only once. Decision API keys start with tcd_. Keys from the Torchcast app (tc_) do not work here. Store the key in an environment variable:

export TORCHCAST_API_KEY="tcd_..."

4. Make a request

This request asks two questions about a support email: whether the customer wants a refund (a yes/no noul question) and which team should handle it (a choice question).

curl https://api.torchcast.ai/v1/decisions \
  -H "Authorization: Bearer $TORCHCAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "torchcast-decider-latest",
    "state": "Hi, I was charged twice for my October invoice. Please send the extra payment back to my card.",
    "questions": {
      "refund_request": {
        "type": "noul",
        "instructions": "Is the customer asking for money back?"
      },
      "team": {
        "type": "choice",
        "instructions": "Which team should handle this email?",
        "criteria": {
          "billing": "Payments, invoices and refunds.",
          "technical": "Bugs, errors and outages.",
          "sales": "Plans, pricing questions and upgrades."
        }
      }
    }
  }'

import os

import requests

response = requests.post(
    "https://api.torchcast.ai/v1/decisions",
    headers={"Authorization": f"Bearer {os.environ['TORCHCAST_API_KEY']}"},
    json={
        "model": "torchcast-decider-latest",
        "state": "Hi, I was charged twice for my October invoice. Please send the extra payment back to my card.",
        "questions": {
            "refund_request": {
                "type": "noul",
                "instructions": "Is the customer asking for money back?",
            },
            "team": {
                "type": "choice",
                "instructions": "Which team should handle this email?",
                "criteria": {
                    "billing": "Payments, invoices and refunds.",
                    "technical": "Bugs, errors and outages.",
                    "sales": "Plans, pricing questions and upgrades.",
                },
            },
        },
    },
    timeout=130,
)
response.raise_for_status()
answers = response.json()["answers"]

const response = await fetch("https://api.torchcast.ai/v1/decisions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TORCHCAST_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "torchcast-decider-latest",
    "state": "Hi, I was charged twice for my October invoice. Please send the extra payment back to my card.",
    "questions": {
      "refund_request": {
        "type": "noul",
        "instructions": "Is the customer asking for money back?"
      },
      "team": {
        "type": "choice",
        "instructions": "Which team should handle this email?",
        "criteria": {
          "billing": "Payments, invoices and refunds.",
          "technical": "Bugs, errors and outages.",
          "sales": "Plans, pricing questions and upgrades."
        }
      }
    }
  }),
  signal: AbortSignal.timeout(130_000),
});
if (!response.ok) throw new Error(`Decision API error ${response.status}`);
const { answers } = await response.json();

torchcast-decider-latest always points at the newest stable model. To pin a version, use a pinned id from GET /v1/models.

5. Read the answer

Response

{
  "model": "torchcast-decider-4b-v1-1-api-1",
  "answers": {
    "refund_request": { "type": "noul", "noul": 0.97 },
    "team": {
      "type": "choice",
      "choice": "billing",
      "confidence": 0.96,
      "probabilities": { "billing": 0.96, "technical": 0.01, "sales": 0.03 }
    }
  },
  "usage": { "input_tokens": 61, "output_tokens": 2 }
}

answers.refund_request.noul is the probability that the answer is yes: here 0.97.
answers.team.choice is the most likely option, and probabilities gives every option’s probability.
model is the pinned model that answered, even though the request named the alias. Log it with your results.
usage.input_tokens is what you are charged for. Every response also carries an x-request-id header; quote it if you contact support.

The model id in this example is illustrative; your response names the model that actually answered. Turn probabilities into actions with a threshold that fits the cost of a mistake in your application:

if answers["refund_request"]["noul"] >= 0.8:
    route_to_refunds()

Next steps

Concepts

All three question types, including score.

Errors

Every error and what to do about it.

Get started

Core concepts

Using the API

More

1. Create an account

2. Add credit

3. Create an API key

4. Make a request

5. Read the answer

Next steps

Concepts

Errors

​1. Create an account

​2. Add credit

​3. Create an API key

​4. Make a request

​5. Read the answer

​Next steps

Concepts

Errors

1. Create an account

2. Add credit

3. Create an API key

4. Make a request

5. Read the answer

Next steps