Eevo console
Contents
Reference
POST

Consequence-based decision

Weigh consequences, model their overlap and compute expected value for one or more stakeholders. The endpoint runs hundreds of calls to the underlying “raw” Eevo decision model to compare consequences and model their overlap. It then computes expected value separately for each stakeholder you send.

Quick example

Below is a quick example of a consequence-based decision via curl:

cURL
curl https://eevo.io/api/v1/cb-decision \
  -H "Authorization: Bearer $EEVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "eevo-1",
  "mode": "default",
  "context": "Acme Corp found a data-export bug that shows some customers a wrong invoice total. A fix is ready; a log dump that would confirm it arrives in 40 minutes.",
  "options": [
    {
      "id": "A",
      "description": "Ship the fix now.",
      "consequences": [
        {
          "id": "a1",
          "label": "Wrong totals stop now",
          "description": "About 200 customers stop seeing a wrong invoice total 40 minutes sooner.",
          "valence": "benefit"
        },
        {
          "id": "a2",
          "label": "Invoices to recheck",
          "description": "Without the log dump to confirm the fix, about 20 customers get an email asking them to recheck one invoice.",
          "valence": "harm"
        }
      ]
    },
    {
      "id": "B",
      "description": "Wait for the log dump, then ship.",
      "consequences": [
        {
          "id": "b1",
          "label": "40 more minutes of wrong totals",
          "description": "About 200 customers keep seeing a wrong invoice total for 40 more minutes.",
          "valence": "harm"
        }
      ]
    }
  ],
  "stakeholders": [
    {
      "id": "customers",
      "description": "The affected customers",
      "values": "Correct invoices, no surprises."
    }
  ]
}'

The response:

JSON
{
  "id": "dec_7b1c0e4f9a2d4c6b8e3f5a1d2c4b6e8f",
  "model": "eevo-1.2",
  "mode": "default",
  "overlap": "correct",
  "seed": 20261006,
  "results": [
    {
      "stakeholder": {
        "id": "customers",
        "description": "The affected customers"
      },
      "best": "A",
      "confidence": 0.99,
      "probabilities": {
        "A": 0.99,
        "B": 0.01
      },
      "p_best": {
        "A": 0.99,
        "B": 0.01
      },
      "p_best_uncorrected": {
        "A": 1,
        "B": 0
      },
      "best_uncorrected": "A",
      "ev": {
        "A": {
          "mean": 0.52,
          "p10": 0.38,
          "p90": 0.63
        },
        "B": {
          "mean": -0.45,
          "p10": -0.58,
          "p90": -0.33
        }
      },
      "ev_uncorrected": {
        "A": {
          "mean": 0.87,
          "p10": 0.79,
          "p90": 0.95
        },
        "B": {
          "mean": -0.81,
          "p10": -0.9,
          "p90": -0.66
        }
      },
      "harms_benefits": {
        "A": {
          "harms": {
            "mean": 0.18,
            "p10": 0.09,
            "p90": 0.31
          },
          "benefits": {
            "mean": 0.7,
            "p10": 0.6,
            "p90": 0.81
          }
        },
        "B": {
          "harms": {
            "mean": 0.45,
            "p10": 0.33,
            "p90": 0.58
          },
          "benefits": {
            "mean": 0,
            "p10": 0,
            "p90": 0
          }
        }
      },
      "consequences": [
        {
          "id": "a1",
          "option": "A",
          "description": "About 200 customers stop seeing a wrong invoice total 40 minutes sooner.",
          "label": "Wrong totals stop now",
          "valence": "benefit",
          "size": {
            "value": 1,
            "p10": 0.82,
            "p90": 1
          },
          "counted_share": 0.6,
          "overlaps_with": [
            {
              "with": "b1",
              "share": 0.88
            }
          ],
          "discounted_by": {
            "with": "b1",
            "type": "mirror",
            "overlap": 0.88,
            "share": 0.4,
            "absence_p": 0.5
          }
        },
        {
          "id": "a2",
          "option": "A",
          "description": "Without the log dump to confirm the fix, about 20 customers get an email asking them to recheck one invoice.",
          "label": "Invoices to recheck",
          "valence": "harm",
          "size": {
            "value": 0.18,
            "p10": 0.09,
            "p90": 0.31
          },
          "counted_share": 1,
          "overlaps_with": [],
          "discounted_by": null
        },
        {
          "id": "b1",
          "option": "B",
          "description": "About 200 customers keep seeing a wrong invoice total for 40 more minutes.",
          "label": "40 more minutes of wrong totals",
          "valence": "harm",
          "size": {
            "value": 0.9,
            "p10": 0.74,
            "p90": 1
          },
          "counted_share": 0.56,
          "overlaps_with": [
            {
              "with": "a1",
              "share": 0.88
            }
          ],
          "discounted_by": {
            "with": "a1",
            "type": "mirror",
            "overlap": 0.88,
            "share": 0.44,
            "absence_p": 0.5
          }
        }
      ],
      "overlaps": [
        {
          "a": "a1",
          "b": "b1",
          "share": 0.88,
          "p": 0.97,
          "type": "mirror",
          "type_p": 0.95,
          "kind": "mirror",
          "absence_side": "a1",
          "absence_p": 0.5,
          "absence": {
            "a1": 0.5,
            "b1": 0.5
          }
        }
      ],
      "removed_share": 0.41,
      "mc": {
        "draws": 1000,
        "solved": 1000
      },
      "records": {
        "ratio": 3,
        "overlap": 2
      }
    }
  ],
  "agreement": {
    "all_same": true,
    "best_by_stakeholder": {
      "customers": "A"
    }
  },
  "warnings": [],
  "usage": {
    "billed_decisions": 1,
    "ratio_records": 3,
    "overlap_records": 2
  },
  "cost_usd": 0.15,
  "links": {
    "view_url": "https://eevo.io/decisions/dec_7b1c0e4f9a2d4c6b8e3f5a1d2c4b6e8f/explicit",
    "png_url": "https://eevo.io/api/arvo/decisions/dec_7b1c0e4f9a2d4c6b8e3f5a1d2c4b6e8f/explicit.png"
  },
  "meta": {
    "tau": 0.2,
    "draws": 1000,
    "ratio_spread_scale": 0.72,
    "overlap_model": "eevo-1.2@3dacdbf4",
    "correction": {
      "mirror": false,
      "kept": true
    }
  },
  "notes": "EVs are on each stakeholder's own scale (largest consequence = 1); compare options within a stakeholder, not across stakeholders. Informative, not a recommendation."
}

A decision that is still running after about 50 seconds answers 202 instead, with a poll_url to fetch it from (Get a decision).

Request body

application/json
  • modelstringOptional

    The identifier of the Eevo model: eevo-1 (the default when left out), which always points at the latest Eevo-1 version.

  • modestringOptional

    default, which this endpoint always runs; it may be left out. Each option lists its consequences; Eevo sizes them and gives each option’s expected value per stakeholder.

    ValuedefaultDefaultdefault
  • contextstringRequired
  • stakeholdersarray of objectsRequired
    • idstringOptional
    • descriptionstringRequired
    • valuesstringOptional
  • optionsarray of objectsRequired
    • idstringRequired

      An option id: a letter from A to H, given to the options in order.

    • descriptionstringRequired
    • consequencesarray of objectsRequired
      • idstringOptional
      • descriptionstringRequired
      • labelstringOptional
      • stakeholdersarray of stringsOptional
      • valencestring or map of stringsRequired
        • benefitGood for the stakeholders it affects.
        • harmBad for the stakeholders it affects.
  • seedintegerOptional
  • asyncbooleanOptional
  • metadataobjectOptional
    5 fields
    • conversationobjectOptional
      3 fields
      • platformstringRequired
        One ofslackteamsgoogle_chatother
      • channelstringOptional
      • thread_urlstringOptional
    • issueobjectOptional
      4 fields
      • trackerstringRequired
        One oflinearjiragithubother
      • urlstringRequired
      • keystringOptional
      • titlestringOptional
    • pull_requestobjectOptional
      5 fields
      • platformstringRequired
        One ofgithubgitlabbitbucketazure_devopsother
      • urlstringRequired
      • repostringOptional
      • numberintegerOptional
      • titlestringOptional
    • on_behalf_ofobjectOptional
      2 fields
      • namestringOptional
      • emailstring <email>Optional
    • linksarray of objectsOptional
      2 fields
      • urlstringRequired
      • labelstringOptional
  • revisesstringOptional
  • revision_noteobjectOptional
    2 fields
    • reasonstringOptional
    • missedarray of objectsRequired
      • kindstringRequired
        • contextSomething about the situation.
        • consequenceA consequence of an option.
        • stakeholderA stakeholder.
        • optionAn option.
        • size_or_probabilityHow large or how likely a consequence is.
        • otherAnything else.
      • descriptionstringRequired
  • share_with_orgbooleanOptional

Response body

application/json
  • idstring

    Request id, as in the Eevo console decision log.

  • modelstring
  • modestring
    Valuedefault
  • overlapstring
    • correctThe shared part of overlapping consequences is counted once. Every new decision does this.
    • reportOverlaps were returned but not applied (older decisions).
    • offOverlap was not assessed (older decisions).
  • seednumber
  • resultsarray of objects

    One result per stakeholder, in request order.

    • stakeholderobject
      • idstring
      • descriptionstring
    • beststring

      The option with the highest expected value for this stakeholder. Takes an option id: a letter from A to H, given to the options in order.

    • confidencenumber
    • probabilitiesmap of numbers

      P(highest EV) per option.

    • evmap of objects

      Expected value per option on this stakeholder's own scale, with p10-p90.

      • {key}object
        • meannumber
        • p10number
        • p90number
    • harms_benefitsmap of objects

      Per option, its harms and its benefits each added up (the counted parts, so ev = benefits - harms), each with its own p10-p90.

      • {key}object
        • harmsobject
          • meannumber
          • p10number
          • p90number
        • benefitsobject
          • meannumber
          • p10number
          • p90number
    • consequencesarray of objects
      • idstring
    • overlapsarray of objects
      • astring
      • bstring
      • sharenumber
  • agreementobject
    • all_sameboolean
    • best_by_stakeholdermap of strings
      • {key}string

        An option id: a letter from A to H, given to the options in order.

  • warningsarray of strings
  • usageobject
    • billed_decisionsnumber

      The standard decisions this decision counts as; its price is a multiple of the decision price.

    • ratio_recordsnumber
    • overlap_recordsnumber
  • cost_usdnumber
  • linksobject
    • view_urlstring
    • png_urlstring
  • metaobject
  • notesstring
  • lineageobject

    Where the decision sits in its revision chain: the first decision, its number (1 = first) and the one it revises.

    • root_idstring
    • numbernumber
    • previous_idstring

Response body: 202

application/json

The decision is still running after about 50 seconds (a model waking from idle takes a few minutes), or async was true. It goes on running and is billed when it completes; poll poll_url (GET /v1/decisions/{id}) every retry_after seconds until status is ok (the answer is in response) or error.

  • idstring
  • modelstring
  • modestring
  • statusstring
  • progressobject
    • doneinteger
    • totalinteger
  • poll_urlstring

    The GET /v1/decisions/{id} URL to poll.

  • retry_afterinteger

    Seconds to wait between polls.

  • lineageobject

Error responses

An error answers with its status and a body with its type and a message. See Errors for the format and every type.

StatusTitleDescription
400Bad RequestThe request is invalid; the message says which field and why.
401UnauthorizedNo valid API key.
402Payment RequiredNo credit left for the request, or an EU request from an organization that has neither bought credit nor has credit.
403ForbiddenOnly the person who made the decision, or the API key it was made with, can change who sees it or publish it.
409ConflictThe model is not served yet, or the revised decision already has a newer revision.
410GoneNo such decision that you can see: none in your organization, or one not shared with you.
429Too Many RequestsRate limit or concurrent request limit reached; retry after Retry-After seconds.
502Bad GatewayThe model failed to answer, or the decision could not be completed. Nothing is billed.
503Service UnavailableThe model is starting after being idle (`model_warming`), or a request for the EU found no EU server available (`region_unavailable`); retry after Retry-After seconds. Nothing is billed.