Jev API Docs

Endpoint

Send POST /api/v1/decisions on this host. There is no chat-completions path and no streaming response. GET /api/v1/models lists the model id.

POST https://jev-api.org/api/v1/decisions
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Authentication

Put your dashboard key in Authorization: Bearer. A missing or rejected key returns 401. The playground creates a key for the signed-in account when you run a request.

Quickstart

Set JEV_API_KEY to a key from your dashboard, then send the request below. New accounts get 2 credits, enough for 2 successful calls.

curl https://jev-api.org/api/v1/decisions \
  -H "Authorization: Bearer $JEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "jev-1.13",
  "state": "Thanks for the refund. Still annoyed it took three emails.",
  "questions": {
    "sentiment": {
      "type": "choice",
      "instructions": "What is the overall sentiment of this message?",
      "criteria": {
        "positive": "Satisfied or thankful overall.",
        "mixed": "Both satisfied and unhappy.",
        "negative": "Unhappy overall."
      }
    },
    "needs_follow_up": {
      "type": "noul",
      "instructions": "Should a person reply to this message?"
    }
  }
}'

Request body

model is jev-1.13 or jev-latest. state is a string, JSON object, or array of text, up to 60,000 characters. questions is a map of 1 to 6 snake_case ids. The id is only the label your answer comes back under, not a question. Write the real question in instructions, as text of 1 to 2,000 characters.

{
  "model": "jev-1.13",
  "state": "Thanks for the refund. Still annoyed it took three emails.",
  "questions": {
    "sentiment": {
      "type": "choice",
      "instructions": "What is the overall sentiment of this message?",
      "criteria": {
        "positive": "Satisfied or thankful overall.",
        "mixed": "Both satisfied and unhappy.",
        "negative": "Unhappy overall."
      }
    },
    "needs_follow_up": {
      "type": "noul",
      "instructions": "Should a person reply to this message?"
    }
  }
}

Question types

Noul

type noul needs only instructions. The answer field noul is a probability from 0 to 1 that the statement is true. There is no separate confidence field. If you send criteria on a noul question, this endpoint ignores it.

Choice

type choice needs instructions and criteria, an object of 2 to 8 snake_case option ids mapped to descriptions of up to 300 characters. The answer includes choice, probabilities for every option, and confidence.

Score

type score needs instructions and criteria as an ordered array of 2 to 10 level descriptions, lowest first. The answer includes score, a legend of your levels, probabilities, and confidence.

Response

A successful body has model, answers keyed by your question ids, usage with input_tokens and output_tokens, and credits_used. model reports jev-1.13 even if you sent jev-latest. Below is an example response to the quickstart request, with usage left out.

{
  "model": "jev-1.13",
  "answers": {
    "sentiment": {
      "type": "choice",
      "choice": "mixed",
      "probabilities": { "mixed": 0.79, "negative": 0.2, "positive": 0.01 },
      "confidence": 0.61
    },
    "needs_follow_up": { "type": "noul", "noul": 0.83 }
  },
  "credits_used": 1
}

Reading probabilities and confidence

Noul is the probability that the statement in instructions is true. Choice and Score return a probability for every option or level, plus confidence.

The runner-up is the signal for a handoff. When confidence is low or two options are close, send the case to a person or ask one more specific question. Do not lower a cutoff until you have looked at those close calls.

Limits

Differences from TypeSafe's API

TypeSafe AI serves Jev at POST https://api.typesafe.ai/v1/systemone with a TypeSafe key and bills per input token. The request body here has the same shape: model, state, and questions of type noul, choice, or score. What changes:

• Path and key: POST /api/v1/decisions on jev-api.org, with a key from this site's dashboard. TypeSafe keys do not work here, and keys from this site do not work on TypeSafe.
• Model id: send jev-1.13 or jev-latest. A versioned id such as jev-1.13.0 returns 422.
• Limits: 1 to 6 questions per call and 2 to 8 Choice options. TypeSafe documents up to 255 Choice options.
• Fields: instructions must be text, and each Choice option needs a description. TypeSafe also accepts object or array instructions and null option descriptions.
• Billing: 1 credit per successful call, whatever the token count.

Errors

• 401 — missing or rejected API key.
• 402 — the key is valid and the balance cannot cover this call. A failed upstream call does not use a credit.
• 422 — the body failed validation. The message names the field.
• 429 — the decision service is rate limited. Retry later.
• 502 — the decision service did not return answers. No credit is used.