# Writing requests for Eevo

> Eevo docs. Every page as Markdown is listed at https://eevo.io/llms.txt; the API is described at https://eevo.io/api/openapi.json.

This guide covers how to write requests for Eevo's two APIs. Choose the tab for the API you are calling.

**SystemOne-compatible API**

The SystemOne-compatible API follows the SystemOne endpoint format, introduced by Typesafe for asking a model typed questions about a state; [SystemOne decision](https://eevo.io/api/docs/reference/api-systemone.md) has the full reference.

A SystemOne request consists of a `state`, which holds the content the questions are about as plain text or a JSON object, and the `questions` themselves.

**Choice questions**

A choice question's probabilities add up to 1 across the choices you send, so a case that fits none of them goes to whichever choice is closest. If such cases can occur, add a choice for them, as the [model routing](https://eevo.io/api/docs/how-to/model-routing.md) example does with `general`.

There is no need to ask a choice question again with its options reordered: Eevo already averages over their order, as described under [Option order](https://eevo.io/api/docs/reference/api-systemone.md#option-order).

**Score questions**

List the levels of a score question from lowest to highest, since a level's position in the list is its score.

**Yes/no questions**

A yes/no question can be phrased as a statement or as a question; the examples in these docs use statements, such as "The customer is attempting fraud." Keep each to a single proposition. "The task needs tools or a long context" should be split into two questions, since one probability cannot say which half is true.

**Several questions in one request**

When you need several answers about the same input, ask for them in one request. The state is then sent and billed only once.

**Setting thresholds**

The probabilities let your code decide when to act on its own and when to hand a case to a person. Set that threshold separately for each question, based on a small labelled sample of your own cases. [Probability, confidence and expected value](https://eevo.io/api/docs/explanation/probability-and-ev.md) explains what the numbers mean.

**Consequence-based Decision API**

A consequence-based decision consists of a `context`, the `options`, the `stakeholders`, and the `consequences` of each option. Eevo weighs the consequences for each stakeholder and returns each option's expected value, as [How Eevo’s Consequence-based Decision API works](https://eevo.io/api/docs/explanation/how-eevo-decides.md) explains.

**Context, options and stakeholders**

The context states what is being decided and the facts that separate the options, including what is not yet known. Include waiting or doing nothing as an option when it is a real one. As stakeholders, include everyone the decision materially affects, not only whoever asked. There are usually two to five.

**Consequences**

Each consequence describes one effect of an option, with amounts: "About 200 customers see a wrong invoice total for 40 more minutes" gives Eevo something to size, while "customer impact" does not. When consequences are in different units, such as money and time, also give each one's rough value to the stakeholder in a common unit.

With several stakeholders, give each one its own consequences, name it in each consequence's `stakeholders` field, and write each consequence from that stakeholder's side. When one event affects two stakeholders, list it once for each, in each one's terms, rather than as one shared text.

Describe every option against the same starting point: what would happen if none of the options were taken. A wait or do-nothing option is that starting point, so describe its consequences relative to the other options. [Process photos in insurance claims](https://eevo.io/api/docs/how-to/claim-photos.md) shows why this matters: a first version of that decision counted the claim payment as a benefit of paying from the photos, even though the household is paid under every option, and Eevo picked that option for the household.

Eevo sizes each consequence as if it will happen, so write an uncertain effect at its expected amount, followed by its chance and full amount: "about €400 of lost sales saved, expected (a 25% chance of saving about €1,600)".

## Read next

- [SystemOne decision](https://eevo.io/api/docs/reference/api-systemone.md): POST /api/v1/systemone
- [Consequence-based decision](https://eevo.io/api/docs/reference/api-cb-decision.md): POST /api/v1/cb-decision
- [Probability, confidence and expected value](https://eevo.io/api/docs/explanation/probability-and-ev.md): Learn what the probabilities in an answer mean.
