Quickstart

From zero to a typed prediction in under 2 minutes. You'll train a model and get your first CLASS / POSSIBILITIES / UNDETERMINED result.

1. Get your API key

Sign up for free — no credit card required. You'll receive an API key starting with sk_.

2. Train a model

Send your training data to the /train endpoint. The data is a list of samples (features) and their labels.

curl -X POST https://api.example.com/train \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "my_first_model",
    "X": [[5.1, 3.5, 1.4, 0.2],
          [7.0, 3.2, 4.7, 1.4],
          [6.3, 3.3, 6.0, 2.5]],
    "y": ["setosa", "versicolor", "virginica"]
  }'

Response:

{
  "model_id": "my_first_model",
  "n_classes": 3,
  "classes": ["setosa", "versicolor", "virginica"],
  "status": "trained"
}

3. Predict with typed uncertainty

Send a sample to the /predict endpoint. Every response includes a type field telling you what to do.

curl -X POST https://api.example.com/predict \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "my_first_model",
    "X": [5.1, 3.5, 1.4, 0.2],
    "cost": 10
  }'

Response:

{
  "type": "CLASS",
  "class_": "setosa",
  "alternatives": [],
  "margin": 4,
  "support": 7,
  "total_evidence": 9,
  "action": "commit",
  "evidence": {
    "setosa":     {"support": 7, "against": 0},
    "versicolor": {"support": 3, "against": 4},
    "virginica":  {"support": 2, "against": 5}
  }
}

4. Using Python

import httpx

API = "https://api.example.com"
KEY = "sk_your_key_here"
headers = {"X-API-Key": KEY, "Content-Type": "application/json"}

# Train
httpx.post(f"{API}/train", headers=headers, json={
    "model_id": "demo",
    "X": X_train.tolist(),
    "y": y_train.tolist(),
})

# Predict
result = httpx.post(f"{API}/predict", headers=headers, json={
    "model_id": "demo",
    "X": sample.tolist(),
    "cost": 10,
}).json()

print(result["type"])    # CLASS, POSSIBILITIES, or UNDETERMINED
print(result["action"])  # commit, narrow, or abstain

5. Check your usage

curl https://api.example.com/billing/usage \
  -H "X-API-Key: sk_your_key_here"

# → {"tier": "free", "predictions_used": 4, "predictions_limit": 50000, ...}

Next steps

• Read Concepts to understand the three output types and cost-aware actions
• See the full API Reference for all endpoints
• Browse Examples for credit risk, medical triage, and quality control use cases