# API reference

Base URL: `https://api.verathos.ai`. Requests and responses are JSON.

## POST /v1/systemone

Answer typed questions about a state, with a probability for every option.

Authentication: `Authorization: Bearer <key>`.

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | A model id from GET /v1/models. |
| `state` | string \| JSON | yes | The situation: text or any JSON value. With the questions' ids, instructions and criteria, within the model's max_state_tokens (4 characters per token). |
| `images` | array | no | Only for a model whose input_modalities list image: up to its images.max_count PNG, JPEG or WebP images, each a base64 data URL or {content_type, base64}, read before the state in their order. No URLs. |
| `questions` | object | yes | Your id for each question, mapped to the question. At least one. |
| `questions.<id>.type` | "noul" \| "choice" \| "score" | yes | yes/no, one of named options, or a level on a scale. |
| `questions.<id>.instructions` | string | no | What to decide, in one sentence. |
| `questions.<id>.criteria` | object \| string[] | no | choice: option name to description; score: the levels from lowest to highest. Up to 255 options. |

```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. Please refund today or we cancel.",
  "questions": {
    "team": {
      "type": "choice",
      "criteria": {"billing": "payments, invoices, refunds", "technical": "bugs, outages"}
    },
    "urgency": {"type": "score", "criteria": ["low", "normal", "high"]},
    "churn": {"type": "noul", "instructions": "Does the customer threaten to cancel?"}
  }
}'
```

```python
import os
import requests

request = {
    "model": "kev-4b",
    "state": "Hi, we were billed twice for March. Please refund today or we cancel.",
    "questions": {
        "team": {
            "type": "choice",
            "criteria": {"billing": "payments, invoices, refunds", "technical": "bugs, outages"},
        },
        "urgency": {"type": "score", "criteria": ["low", "normal", "high"]},
        "churn": {"type": "noul", "instructions": "Does the customer threaten to cancel?"},
    },
}

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. Please refund today or we cancel.",
  questions: {
    team: {
      type: "choice",
      criteria: { billing: "payments, invoices, refunds", technical: "bugs, outages" },
    },
    urgency: { type: "score", criteria: ["low", "normal", "high"] },
    churn: { type: "noul", instructions: "Does the customer threaten to cancel?" },
  },
};

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);
```

Response:

```json
{
  "id": "629b21f5f9f7934391d43557",
  "model": "kev-4b",
  "answers": {
    "team": {"type": "choice", "choice": "billing", "confidence": 0.91,
             "probabilities": {"billing": 0.97, "technical": 0.03}},
    "urgency": {"type": "score", "score": 1.62, "confidence": 0.3,
                "legend": {"0": "low", "1": "normal", "2": "high"},
                "probabilities": {"0": 0.06, "1": 0.26, "2": 0.68}},
    "churn": {"type": "noul", "noul": 0.91}
  },
  "usage": {"input_tokens": 52},
  "receipt": {
    "receipt": {"miner_hotkey": "5Czn...", "endpoint_id": "gpu0",
                "request_sha256": "...", "answers_sha256": "...", "input_tokens": 52, "...": "..."},
    "signature": "..."
  }
}
```

- Body up to 1 MiB (with images, the model's images.max_request_bytes); the answers must fit 64 KiB.
- With images: usage.image_tokens, the images' part of input_tokens; each image costs (width / 32) x (height / 32) + 2 tokens at the size the model reads it, and the request one more.
- The miners get 10 s per request, retries on other miners included, once the gateway has received and checked it; set the client timeout well above that.
- Charged per answered request: usage.input_tokens times the model's price.
- Errors: {"error": {"type", "message"}}; 429 and 503 carry Retry-After.

## GET /v1/models

Every active model with its price, limits, availability and weights.

Public: no key needed.

```bash
curl https://api.verathos.ai/v1/models
```

Response:

```json
{"object": "list", "data": [{
  "id": "kev-4b", "object": "model", "max_state_tokens": 65536, "input_modalities": ["text"], "images": null,
  "price": {"usd_per_million_input_tokens": 0.015, "usd_per_million_output_tokens": 0},
  "available": true, "state": "operational",
  "latency_ms": {"p50": 236, "p95": 440, "window_s": 900},
  "license": "apache-2.0",
  "weights": {"repo": "jaredpalmer/kev-4b", "revision": "6cfce5c..."},
  "base_model": {"repo": "Qwen/Qwen3.5-4B-Base", "revision": "1001bb4..."}
}]}
```

- input_modalities: "text" (a state of plain text or JSON) for every model, and "image" for a model that reads images.
- images: the image limits of a model that reads images (max_count, max_bytes, max_total_bytes, max_input_pixels, max_pixels, min_pixels, token_px, max_request_bytes, max_aspect_ratio, formats); null for a model that reads text only.
- state: operational, degraded or unavailable.
- latency_ms covers window_s: the last 15 minutes, or, when the latest 20 answers (all of the last 24 hours' when fewer) go back further, the fewest whole hours that hold them (null without answers in 24 hours).

## GET /v1/status

Per model: state, endpoints, capacity, latency, success rate and availability.

Public: no key needed.

```bash
curl https://api.verathos.ai/v1/status
```

Response:

```json
{"updated_at": "2026-10-07T17:42:56+00:00", "since": "2026-10-07T17:42:14+00:00",
 "models": [{"id": "kev-4b", "state": "operational", "endpoints": 4, "capacity_rps": 47.19,
             "latency_ms": {"p50": 236, "p95": 440, "window_s": 900},
             "success_rate_1h": 1.0, "busy_rate_1h": 0.0, "requests_1h": 5212, "availability_24h": 1.0}]}
```

- Cacheable for 15 s; figures cover the gateway process since `since`.
- degraded: under 98% of the last 15 minutes' requests answered (those refused as busy left out), or more than half the endpoints failing.
- success_rate_1h: answered over answered and failed requests in the last hour, null under 20 of them; busy_rate_1h: the share refused for want of free capacity; requests_1h: all of them.
- The last 90 days per day, with uptime and incidents: GET /api/status/history on this site.

## GET /api/status/history

The API and each model per UTC day: minutes unavailable and degraded, the day's level, uptime and incidents, as the status page shows them.

Public: no key needed.

Served by this site, `https://verathos.ai`, not the gateway.

| Field | Type | Required | Description |
|---|---|---|---|
| `days` | integer | no | 1 to 90 (default 90): the days listed per component, today last. |

```bash
curl https://verathos.ai/api/status/history
```

Response:

```json
{"days": 90, "first_day": "2026-07-13", "recorded_from": "2026-08-31T11:23:00+00:00",
 "updated_at": "2026-10-10T12:45:00+00:00",
 "components": [{"id": "model:clef-flash", "name": "clef-flash", "uptime": 0.9917,
   "days": [{"day": "2026-10-10", "level": "partial", "minutes": 766, "unavailable": 71,
             "degraded": 0, "no_data": 0, "incidents": [8], "more_incidents": 0}]}],
 "incidents": [{"id": 8, "component": "model:clef-flash", "name": "clef-flash", "status": "ongoing",
   "state": "unavailable", "started_at": "2026-10-10T11:35:00+00:00", "ended_at": null,
   "minutes": 71, "unavailable": 71, "degraded": 0,
   "text": "clef-flash unavailable since 11:35 UTC (1 h 11 min so far). No miner endpoint serves it. The other models are available."}],
 "recent": [8],
 "thresholds": {"model_partial_min": 30, "model_degraded_min": 240, "model_major_min": 240,
                "api_partial_min": 5, "api_major_min": 30, "open_unavailable_min": 10,
                "open_degraded_min": 30, "recovered_min": 5}}
```

- components: "api", then each model the gateway lists now as "model:<id>"; each with every day of the range, oldest first, and its uptime over them (minutes not unavailable among those measured).
- level: none (no data), ok, degraded, partial or major. A model is unavailable while the gateway reports it so or does not answer; the API, while the gateway does not answer or more than half the models are unavailable.
- incidents: the ongoing ones and the newest of the last 90 days (at most 200); recent: the ongoing ones, then those of the last 14 days (at most 10).
- Recomputed at most every minute.
