# Decisions API

Ask a decision model one typed question about each item you send (a yes/no, a pick from your options, or a position on your scale) and get the decision with its score, confidence and probabilities, the exact model version, its maker, token counts and the exact cost of each call. You pay exactly what each call costs at the model's own token rates.

**Pricing:** Metered: you pay exactly each call's cost at the selected model's rates (default TypeSafe: Jev Latest: $0.042 per 1M input tokens). Each model's rates are listed with the `model` parameter's options in the API schema.

**Endpoint:** `POST /v1/data/llm/decisions/run`

**Auth:** `Authorization: Bearer mk_live_...`

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `items` | array | Yes | The texts to judge, one per row. Each item is one call to the model. |
| `question` | string | Yes | The one question to ask about every item, e.g. 'Is this review negative?'. |
| `answerType` | string | No | yes_no, choice (decision is one of your options) or score (your options are an ordered scale, lowest first). |
| `options` | array | No | For choice: the options to pick from (2 to 50). For score: the scale, lowest first (2 to 50). Not used for yes_no. |
| `model` | string | No | The decision model. Pick from the list (the leaders first). Each model shows its own rate per 1M input tokens, and that is exactly what each call costs. |

## Example

`?wait=true` holds the request open until the run finishes (up to 60s) and returns the rows inline: one request, no polling.

```bash
curl -X POST "https://api.mindcase.co/v1/data/llm/decisions/run?wait=true" \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params":{"items":["..."],"question":"..."}}'
```

```python
import requests

resp = requests.post(
    "https://api.mindcase.co/v1/data/llm/decisions/run",
    params={"wait": "true"},
    headers={"Authorization": "Bearer mk_live_YOUR_API_KEY"},
    json={"params": {
    "items": [
        "..."
    ],
    "question": "..."
}},
)
rows = resp.json()["data"]
```

## Longer runs

If the run is still going at the 60s ceiling you get back `{ job_id, status: "running" }` instead of rows (same if the result is over 100 rows; those come back `truncated`). Poll with that `job_id`:

```bash
# 1) check status
curl https://api.mindcase.co/v1/jobs/JOB_ID \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY"

# 2) when status == completed, fetch the rows
curl https://api.mindcase.co/v1/jobs/JOB_ID/results \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY"
```

Full API reference (auth, jobs, balance, SDKs, MCP): https://mindcase.co/skills.md

## Response columns

| Field | Display name | Type |
|-------|--------------|------|
| `id` | ID | text |
| `item` | Item | text |
| `question` | Question | text |
| `answerType` | Answer Type | text |
| `options` | Options | array |
| `decision` | Decision | text |
| `score` | Score | number |
| `confidence` | Confidence | number |
| `probabilities` | Probabilities | object |
| `model` | Model | text |
| `provider` | Provider | text |
| `inputTokens` | Input Tokens | number |
| `outputTokens` | Output Tokens | number |
| `totalTokens` | Total Tokens | number |
| `costUsd` | Cost (USD) | number |
| `error` | Error | text |
| `createdAt` | Created At | datetime |
