# Quickstart

With an AI agent, give it this prompt:

```text
Read https://verathos.ai/skills/verathos-api/SKILL.md and use it to add Verathos Decide to this project. My API key is in the VERATHOS_KEY environment variable.
```

## 1. Create a key

[Sign in](https://verathos.ai/login), then create a key under [API keys](https://verathos.ai/account/keys). The key is shown once; store it like a password.

## 2. Put the key in your environment

```bash
export VERATHOS_KEY=vd_...
```

## 3. Send a request

```bash
curl https://api.verathos.ai/v1/systemone \
  -H "Authorization: Bearer $VERATHOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "kev-4b",
  "state": "Hi, we were billed twice for March and nobody answers our emails. Please refund today or we cancel the contract.",
  "questions": {
    "team": {
      "type": "choice",
      "instructions": "Which team should handle this ticket?",
      "criteria": {
        "billing": "payments, invoices, refunds",
        "technical": "bugs, outages, integrations",
        "sales": "plans, pricing, upgrades"
      }
    },
    "urgency": {
      "type": "score",
      "instructions": "How urgent is this ticket?",
      "criteria": ["low", "normal", "high", "critical"]
    },
    "churn": {"type": "noul", "instructions": "Is the customer threatening to leave?"}
  }
}'
```

```python
import os
import requests

request = {
    "model": "kev-4b",
    "state": "Hi, we were billed twice for March and nobody answers our emails. Please refund today or we cancel the contract.",
    "questions": {
        "team": {
            "type": "choice",
            "instructions": "Which team should handle this ticket?",
            "criteria": {
                "billing": "payments, invoices, refunds",
                "technical": "bugs, outages, integrations",
                "sales": "plans, pricing, upgrades",
            },
        },
        "urgency": {
            "type": "score",
            "instructions": "How urgent is this ticket?",
            "criteria": ["low", "normal", "high", "critical"],
        },
        "churn": {"type": "noul", "instructions": "Is the customer threatening to leave?"},
    },
}

response = requests.post(
    "https://api.verathos.ai/v1/systemone",
    headers={"Authorization": f"Bearer {os.environ['VERATHOS_KEY']}"},
    json=request,
    timeout=30,
)
response.raise_for_status()
answers = response.json()["answers"]
print(answers)
```

```typescript
const request = {
  model: "kev-4b",
  state: "Hi, we were billed twice for March and nobody answers our emails. Please refund today or we cancel the contract.",
  questions: {
    team: {
      type: "choice",
      instructions: "Which team should handle this ticket?",
      criteria: {
        billing: "payments, invoices, refunds",
        technical: "bugs, outages, integrations",
        sales: "plans, pricing, upgrades",
      },
    },
    urgency: {
      type: "score",
      instructions: "How urgent is this ticket?",
      criteria: ["low", "normal", "high", "critical"],
    },
    churn: { type: "noul", instructions: "Is the customer threatening to leave?" },
  },
};

const response = await fetch("https://api.verathos.ai/v1/systemone", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.VERATHOS_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify(request),
});
if (!response.ok) throw new Error(`Decide answered ${response.status}`);
const { answers } = await response.json();
console.log(answers);
```

## 4. Read it like this

```json
{
  "id": "629b21f5f9f7934391d43557",
  "model": "kev-4b",
  "answers": {
    "team": {"type": "choice", "choice": "billing", "confidence": 0.93,
             "probabilities": {"billing": 0.96, "technical": 0.01, "sales": 0.03}},
    "urgency": {"type": "score", "score": 2.13, "confidence": 0.31,
                "legend": {"0": "low", "1": "normal", "2": "high", "3": "critical"},
                "probabilities": {"0": 0.02, "1": 0.15, "2": 0.51, "3": 0.32}},
    "churn": {"type": "noul", "noul": 0.93}
  },
  "usage": {"input_tokens": 112},
  "receipt": {"receipt": {"miner_hotkey": "5Czn...", "endpoint_id": "gpu0", "...": "..."}, "signature": "..."}
}
```

- `answers.team.probabilities`: a probability for every option; `choice` is the most likely one.
- `answers.urgency`: probabilities per level, keyed by the level's index; `score` is the expected level (2.13 is a little above "high"); `legend` names the levels.
- `answers.churn.noul`: the probability of yes. Pick a threshold that fits the cost of a mistake.
- `usage.input_tokens`: what the request cost. Output is free.
- `receipt`: the miner that answered, signed over your request and the answers. See [Receipts](https://verathos.ai/docs/receipts.md).

The example values are illustrative; your answer will differ.

## Next

- [Questions](https://verathos.ai/docs/questions.md): the three types and how to word them.
- [Reading answers](https://verathos.ai/docs/answers.md): thresholds and what a value near 0.5 means.
- [Errors](https://verathos.ai/docs/errors.md) and [Rate limits](https://verathos.ai/docs/rate-limits.md).
