Decision API

Jev API

One POST sends a state and your questions. The response is Noul, Choice, or Score, each with a probability your code can branch on.

POST /api/v1/decisions

{
  "model": "jev-1.13",
  "state": "I was charged twice for the same annual plan.",
  "questions": {
    "refund": {
      "type": "noul",
      "instructions": "Is the customer asking for money back?"
    }
  }
}

Examples

Eight decisions you can run

Hover a card to read the request. Copy it, or open it in the playground.

Route a blank checkout

Choice returns the owning team and the probability of each team.

{
  "model": "jev-1.13",
  "state": "Checkout shows a blank page after Pay is clicked. The customer is on the live store, not a sandbox.",
  "questions": {
    "team": {
      "type": "choice",
      "instructions": "Which team should own this ticket?",
      "criteria": {
        "payments": "Checkout, billing, or payment processing.",
        "frontend": "Rendering, layout, or browser behavior.",
        "account": "Login, permissions, or profile access."
      }
    }
  }
}
Open in playground

Is this a refund ask?

Noul returns a yes probability, not a paragraph to parse.

{
  "model": "jev-1.13",
  "state": "I was charged twice for the same annual plan this morning. Please send the extra charge back.",
  "questions": {
    "refund": {
      "type": "noul",
      "instructions": "Is the customer asking for money back?"
    }
  }
}
Open in playground

How urgent is the payout failure?

Score places the note on your scale and returns the distribution.

{
  "model": "jev-1.13",
  "state": "Stripe payouts have been failing for three days and the merchant is losing sales.",
  "questions": {
    "urgency": {
      "type": "score",
      "instructions": "How urgent is this ticket?",
      "criteria": [
        "Can wait for the next release",
        "Should be handled this week",
        "Blocking revenue right now"
      ]
    }
  }
}
Open in playground

Credential request in a message

A Noul probability is the gate before a human review queue.

{
  "model": "jev-1.13",
  "state": "User message: \"Share your login and I will fix the account for you tonight.\"",
  "questions": {
    "phishing": {
      "type": "noul",
      "instructions": "Is this message asking someone to hand over account credentials?"
    }
  }
}
Open in playground

Qualify an inbound note

Choice separates a buying window from a note that only shows interest.

{
  "model": "jev-1.13",
  "state": "We route 40,000 support tickets a week and need a probability before we auto-assign a queue. Budget is approved this quarter.",
  "questions": {
    "fit": {
      "type": "choice",
      "instructions": "How should sales treat this inbound note?",
      "criteria": {
        "ready": "A real workflow, a volume, and a buying window.",
        "nurture": "Interest without a stated workflow or timeline.",
        "ignore": "No product fit."
      }
    }
  }
}
Open in playground

Guaranteed-return listing

Noul answers the policy question you wrote, not a generic safety essay.

{
  "model": "jev-1.13",
  "state": "Listing text: \"Guaranteed 30% returns every month. Send crypto to this wallet to join.\"",
  "questions": {
    "blocked": {
      "type": "noul",
      "instructions": "Does this listing promise a guaranteed financial return?"
    }
  }
}
Open in playground

Renewal risk in a note

Score uses your three levels, from unlikely to likely to cancel.

{
  "model": "jev-1.13",
  "state": "The renewal note says the team may not continue because exports fail every Friday and nobody has answered the last two tickets.",
  "questions": {
    "risk": {
      "type": "score",
      "instructions": "How high is the chance this account does not renew?",
      "criteria": [
        "Unlikely to leave",
        "Unhappy, still using the product",
        "Likely to cancel"
      ]
    }
  }
}
Open in playground

Which invoice exception?

Choice can name over-PO, an unexpected line, or both, with probabilities.

{
  "model": "jev-1.13",
  "state": "Vendor invoice 4481 is $18,400. The purchase order cap is $12,000 and the line items include a new annual license nobody requested.",
  "questions": {
    "exception": {
      "type": "choice",
      "instructions": "Which exception should accounts payable open?",
      "criteria": {
        "over_po": "The amount is above the purchase order.",
        "unexpected_item": "A line item was not requested.",
        "both": "The amount and a line item are both wrong."
      }
    }
  }
}
Open in playground

Response

Answers your code can branch on

Jev does not write a paragraph for you to parse. It returns the decision you asked for, plus the probability behind it.

Every option keeps a probability

A Choice answer names the winner and still returns the probability of each option you defined.

Noul, Choice, and Score in one call

A yes/no, a labeled choice, and a position on your scale can share the same state.

Questions run together

Extra questions on the same state stay in that request instead of becoming more round trips.

Pin the model when a threshold matters

Send jev-1.13 when you tune a cutoff. jev-latest follows the version this API currently serves.

How to use

How to call the Jev API

  1. 01

    Create a key

    Sign in and copy a key from the dashboard. The playground can create one for the signed-in account.

  2. 02

    POST a state and questions

    The body has model, state, and a map of questions. Your ids are only labels. The question text goes in instructions.

  3. 03

    Branch on the typed answer

    Read noul, choice, or score. On Choice and Score, confidence tells you when the options are close.

Use cases

Where a typed decision replaces a prompt

Support routing

Send the ticket text and the queues you actually staff. Branch on the winning team, or hand off when the probabilities are close.

Trust and moderation

Ask the specific policy question. A high Noul can auto-hold; a low one can pass; the middle goes to review.

Inbound qualification

Separate a note with a workflow and a buying window from one that only says the product looks interesting.

Invoice exceptions

Name the exception types your payables team already uses. The legend in a Score, or the keys in a Choice, match that list.

After the first calls

What changes when the answer is typed

We stopped parsing a paragraph to see if a ticket was a refund. The noul value is the branch.
Support lead
When two teams were close, confidence told us to send the ticket to a person instead of guessing.
Trust engineer
The score levels are our words, so the legend in the response matches the rubric we already use.
Billing operations

Questions about the request and the answer

What is the difference between Noul, Choice, and Score?

Noul is a yes/no with a probability. Choice picks one of the options you named and returns a probability for each. Score places the state on an ordered scale you wrote, lowest first.

Why do I still see probabilities for the options that did not win?

The runner-up is the signal for a handoff. If two options are close, route that case to a person instead of treating the winner as certain.

Should I send jev-1.13 or jev-latest?

Pin jev-1.13 when a cutoff in your code depends on the shape of the probabilities. jev-latest is accepted and currently resolves to that same model on this API.

What can I put in state?

A string, a JSON object, or an array of text. Put the facts the questions need. Do not put the answer you hope to get.

What should I do when confidence is low?

Treat the case as uncertain. Send it to a person or ask one more specific question. Do not lower the cutoff until you have looked at those close calls.

What does a 422 mean?

The body failed validation. The message names the field: a missing instructions string, a Choice with fewer than two options, a Score whose levels are out of order, or a question id that is not snake_case.

Send the first decision

Open the playground with one of the examples, or follow Jev Docs and call the endpoint with your own key.