# Decide (Beta)

> Ask Decide typed questions about a text through the API and get probabilities back instead of prose, for one text or a batch of up to 100.

Decide is in (Beta). It answers typed questions about a text with probabilities instead of prose: which category a letter belongs to, how urgent it is, whether it contains personal data. A decision model writes no text, so there is nothing to parse. Every answer comes with the full probability distribution behind it and a confidence.

Decide runs on komplai's local infrastructure in Denmark, with no AI charge. The text is not stored.

## Before you start

- Your organisation has Decide in its agreement and has approved its processing, and an administrator has given you access to Decide under **Organisation › People › Tool access** in the hub.
- You have a personal API key (`kp_live_...`) with the scope `decide:process`, created on the hub's **API keys** page at [hub.komplai.dk/api-access](https://hub.komplai.dk/api-access). An organisation integration key (`kp_org_...`) gets 403 [integration_not_permitted](https://developers.komplai.dk/errors/integration_not_permitted).
- Beta operations may still change, with notice. Without an approved data processing agreement, use test data only.

## Your first call

Send one text in `state` and your questions in `questions`, each under an id you choose.

```bash
curl https://api.komplai.dk/v1/decide \
  -H "Authorization: Bearer $KOMPLAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "Hej. Jeg vil gerne have en kopi af min ansøgning om byggetilladelse fra marts. Venlig hilsen Mette Kjærgaard Holm",
    "questions": {
      "category": {
        "type": "choice",
        "instructions": "Hvad handler henvendelsen om?",
        "criteria": {
          "aktindsigt": "Borgeren beder om kopi af dokumenter eller aktindsigt",
          "klage": "Borgeren klager over en afgørelse",
          "andet": "Noget andet"
        }
      },
      "urgency": {
        "type": "score",
        "instructions": "Hvor hurtigt skal henvendelsen besvares?",
        "criteria": ["Inden for den normale frist", "Inden for en uge", "Samme dag"]
      },
      "personal_data": {
        "type": "noul",
        "instructions": "Indeholder teksten personoplysninger?",
        "criteria": {
          "true": "Ja, for eksempel et navn eller et CPR-nummer",
          "false": "Nej"
        }
      }
    }
  }'
```

```json
{
  "model": "convaiinnovations/laya/multilingual",
  "answers": {
    "category": {
      "type": "choice",
      "choice": "aktindsigt",
      "probabilities": { "aktindsigt": 0.91, "klage": 0.03, "andet": 0.06 },
      "confidence": 0.672,
      "action": { "act_probability": 0.88 }
    },
    "urgency": {
      "type": "score",
      "score": 0.32,
      "max": 2,
      "probabilities": [0.72, 0.24, 0.04],
      "confidence": 0.356
    },
    "personal_data": {
      "type": "noul",
      "noul": 0.97,
      "probabilities": { "true": 0.97, "false": 0.03 },
      "confidence": 0.806
    }
  },
  "usage": { "input_tokens": 118, "output_tokens": 0 },
  "latency_ms": 38
}
```

The answers come back under the same ids. `usage.output_tokens` is always 0, and `latency_ms` is the model's own time without the network.

## Question types

Each question has `type`, `instructions` (the question in your own words) and `criteria`, whose shape depends on the type.

| Type | `criteria` | The answer |
| --- | --- | --- |
| `choice` | An object of 2 to 32 options: a short key and what that option means | `choice` is the key with the highest probability, and `probabilities` gives every key its probability |
| `score` | A list of 2 to 32 levels, lowest first | `score` is the expected level (each level times its probability, added up), `max` the highest level, and `probabilities` one value per level in the order you sent them |
| `noul` | `true` and `false`, and what each means | `noul` is the probability that the statement is true |

The probabilities in an answer add up to 1. Keep option keys short and machine-friendly, because the answer names the key.

Every answer also has:

- `confidence`: how decided the answer is, from 0 (spread evenly) to 1 (everything on one option). It says nothing about whether the answer is right.
- `action.act_probability`, when the model gives it: how likely the answer is safe to act on without a person checking it.

A request takes from 1 to 64 questions. They share one reading of the text, so several questions cost little more than one. `state` is a text or a JSON object, which komplai turns into text; arrays and other values are refused. The request may have at most 80,000 characters as JSON and the body at most 320,000 bytes. Fields that are not listed are ignored.

## Models

`model` chooses the decision model:

| `model` | Model |
| --- | --- |
| `komplai-decide` | Laya |
| `komplai-decide-claes` | Claes |

Leave it out for the default: the model you chose in the hub, else your organisation's default, else `komplai-decide`. `model` in the answer names the model that answered by its checkpoint. A model Decide does not offer your organisation answers 409 [model_not_enabled](https://developers.komplai.dk/errors/model_not_enabled), and 404 when local infrastructure does not offer it right now. The API never picks another model for you.

## Many texts in one call

POST /v1/decide/batch asks the same questions about up to 100 texts in `states`, in one pass of the model. The answers come back in `results` in the order of `states`, and the batch is answered whole or refused whole. It counts as one request against your request limit.

```bash
curl https://api.komplai.dk/v1/decide/batch \
  -H "Authorization: Bearer $KOMPLAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "states": [
      "Hej. Jeg vil gerne have en kopi af min ansøgning om byggetilladelse fra marts.",
      "Jeg klager over afslaget på min ansøgning om boligstøtte. Afgørelsen er forkert, og jeg har brug for svar hurtigt."
    ],
    "questions": {
      "category": {
        "type": "choice",
        "instructions": "Hvad handler henvendelsen om?",
        "criteria": {
          "aktindsigt": "Borgeren beder om kopi af dokumenter eller aktindsigt",
          "klage": "Borgeren klager over en afgørelse",
          "andet": "Noget andet"
        }
      }
    }
  }'
```

```json
{
  "model": "convaiinnovations/laya/multilingual",
  "results": [
    {
      "answers": {
        "category": { "type": "choice", "choice": "aktindsigt", "probabilities": { "aktindsigt": 0.91, "klage": 0.03, "andet": 0.06 }, "confidence": 0.672 }
      },
      "usage": { "input_tokens": 61, "output_tokens": 0 }
    },
    {
      "answers": {
        "category": { "type": "choice", "choice": "klage", "probabilities": { "aktindsigt": 0.08, "klage": 0.86, "andet": 0.06 }, "confidence": 0.544 }
      },
      "usage": { "input_tokens": 66, "output_tokens": 0 }
    }
  ],
  "usage": { "input_tokens": 127, "output_tokens": 0 },
  "latency_ms": 52
}
```

A batch request may have at most 200,000 characters as JSON and the body at most 800,000 bytes.

## Time limits and failures

The model has 30 seconds to answer. When it fails, does not answer in time or cannot be reached, the call answers [service_unavailable](https://developers.komplai.dk/errors/service_unavailable). An answer that fails komplai's checks, such as a missing answer or probabilities that do not add up, is never passed on: the call answers [invalid_response](https://developers.komplai.dk/errors/invalid_response). A request that does not have the documented form answers [invalid_input](https://developers.komplai.dk/errors/invalid_input).

## Where data is processed

Decide runs only on komplai's validated decision models, on komplai's local infrastructure in Denmark. Data does not leave the EU, and your organisation's own AI connections are never used for Decide. The text is not stored; komplai records the call's metadata, such as who called, when and which model.

## Reference and errors

- [Decide reference](https://developers.komplai.dk/reference/decide): every field of POST /v1/decide and POST /v1/decide/batch, with code samples and a console to try each call.
- [Errors](https://developers.komplai.dk/errors): every code with what to do. Request limits are on [Limits](https://developers.komplai.dk/limits).

---

https://developers.komplai.dk/tools/decide