Skip to content

Decisions

Is this ticket asking for a refund? Which team should take it? How urgent is it? A decision model answers questions like these about a text or an image. It returns a probability for each possible answer, in one round trip, and does not write a reply. Models with the Decisions badge on the Models & pricing page work this way.

What a decision looks like

A request has a state, the text or image the questions are about, and a set of named questions. Each question has one of 3 types:

Type The question The answer
noul a yes or no the probability of yes
choice pick one of 2 to 255 options you name a probability per option, and the chosen one
score a position on a scale of 2 to 10 levels you describe, lowest first a probability per level, and the probability-weighted score

The model answers each question independently, against the same state, in one call.

curl https://api.keln.ai/v1/decisions \
  -H "Authorization: Bearer $KELN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cloudflare/clef",
    "state": "I was charged twice for my subscription this month and I want the extra charge refunded.",
    "questions": {
      "refund":     { "type": "noul",   "instructions": "Is the customer asking for money back?" },
      "department": { "type": "choice", "instructions": "Which team should handle this?",
                      "criteria": { "billing": "Charges and refunds", "technical": "Bugs and outages" } },
      "urgency":    { "type": "score",  "instructions": "How urgent is this?",
                      "criteria": ["Can wait", "This week", "Blocking revenue now"] }
    }
  }'

The answers come back under the names you chose:

{
  "answers": {
    "refund":     { "type": "noul",   "noul": 0.98 },
    "department": { "type": "choice", "choice": "billing", "confidence": 0.98,
                    "probabilities": { "billing": 0.99, "technical": 0.01 } },
    "urgency":    { "type": "score",  "score": 1.0, "confidence": 0.47,
                    "probabilities": { "0": 0.11, "1": 0.79, "2": 0.10 } }
  },
  "usage": { "input_tokens": 322, "output_tokens": 0, "cost": 0.0000773 }
}

The full response also includes model, and a legend for each score. The API reference lists every field.

Where it fits

  • Triage and routing. Pick the queue, the tool or the priority before a chat model spends tokens on the conversation.
  • Moderation and screening. Check whether content is harmful, which category it falls in and how severe it is. Each answer is a probability, so you can set your own threshold.
  • Grading and checks. Check whether an answer is correct or meets a rubric, with a score you can average across a batch.
  • Images. Models with image input take an image as the state, or a text and an image together. For example: does the photo show a damaged package?

A chat model can do each of these too, with a prompt and code to parse its reply. A decision model returns probabilities in one short round trip, and Keln bills only its input tokens.

Using it

  • The endpoint is POST /v1/decisions, and it takes the same API key as chat completions. The API reference lists the request, the answers and the errors.
  • The TypeSafe SDK works with Keln once you change its base URL. Clients built for another gateway's decisions endpoint work the same way, because they send the same request.
  • In the playground, pick a decision model, write a state, add questions and send the request. The Playground page has the details.
  • Keln charges per million input tokens, at the price on the rate card, and the answers are free. usage.cost on each response is the exact charge.

What Keln does on each request

  • Hosting. Keln sends each request to a verified provider for the model, and moves it to another provider if the first one does not answer.
  • Answer checks. Keln checks every answer before it reaches you and retries a faulty one on another provider.
  • Parsing. The answers are numbers under the names you chose.
  • Retention. Zero data retention applies here as on chat completions (privacy).

Errors

The API reference lists every error, such as a streamed request, a choice with 1 option, a remote image URL or a chat model on this endpoint.