Jev API Guide: Choice, Noul and Score Decisions | AutoJev

The Jev API turns supplied state into structured decisions. Instead of asking a generative model for prose and parsing the result, an application defines bounded questions and receives typed answers, probabilities and usage metadata.

AutoJev exposes the Jev Decisions protocol at POST https://autojev.ai/api/v1/decisions. It is useful for application code that needs custom decisions beyond AutoJev's ready-made routing and guardrail presets.

TypeSafe AI develops Jev and its System One model family. AutoJev is an independent integration layer and is not affiliated with or endorsed by TypeSafe AI.

Does the Jev API require login or an API key?

Production REST calls require an AutoJev access key. Sign in, create a user-scoped key in API key settings, and keep it in a server-side environment variable. Do not embed the key in browser code or commit it to a repository.

The public Ask Jev experience is different: visitors can try a bounded question without signing in or supplying an API key. It is intended for exploration, while the authenticated API is the interface for applications and agents.

export AUTOJEV_API_KEY="your-autojev-access-key"

Jev API endpoint

Send a JSON request with Bearer authentication:

curl https://autojev.ai/api/v1/decisions \
  -H "Authorization: Bearer ${AUTOJEV_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "~typesafe/jev-latest",
    "state": {
      "action": "Refund USD 680 after a verified duplicate charge",
      "policy": "Refunds above USD 500 require human approval"
    },
    "questions": {
      "next_step": {
        "type": "choice",
        "instructions": "Choose the safest permitted next step.",
        "criteria": {
          "allow": "Issue the refund immediately.",
          "review": "Require human approval before issuing the refund.",
          "deny": "Reject the refund request."
        }
      },
      "needs_review": {
        "type": "noul",
        "instructions": "Does the stated policy require human review?"
      },
      "risk": {
        "type": "score",
        "instructions": "Score the financial and policy risk.",
        "criteria": ["Low", "Moderate", "High", "Critical"]
      }
    }
  }'

The model field is optional and defaults to ~typesafe/jev-latest. AutoJev accepts Jev model identifiers only. A request must contain between 1 and 32 named questions.

Jev API request fields

State

state is the evidence being evaluated. It can be a string, an object or an array. Send only information relevant to the decision; smaller, explicit state is easier to test and less likely to expose private data.

Questions

Each key in questions names an independent judgment over the same state:

• Choice selects one caller-defined outcome and can return confidence and a probability distribution.
• Noul returns a value from 0 to 1 for a yes-or-unknown judgment.
• Score evaluates the state against an ordered rubric defined by the caller.

Choice questions accept 2 to 20 criteria. Score questions accept 1 to 10 rubric entries. Clear criteria produce more useful decision boundaries than vague labels.

Optional context

session_id, user and trace can carry identifiers and non-secret observability context. Do not place credentials, passwords or unrelated personal data in these fields.

Jev API response

AutoJev wraps successful results in its standard { code, message, data } envelope. The data object contains the resolved model, an answer for every named question and token usage. Provider and request identifiers may also be present.

{
  "code": 0,
  "message": "ok",
  "data": {
    "model": "typesafe/jev-1.13-20260917",
    "answers": {
      "next_step": {
        "type": "choice",
        "choice": "review",
        "confidence": 0.94,
        "probabilities": {
          "allow": 0.02,
          "review": 0.94,
          "deny": 0.04
        }
      },
      "needs_review": {
        "type": "noul",
        "noul": 0.97
      },
      "risk": {
        "type": "score",
        "score": 2
      }
    },
    "usage": {
      "input_tokens": 183,
      "output_tokens": 74
    }
  }
}

The values above illustrate the response shape; real answers vary with the state, criteria and current model version. Treat probabilities as decision signals, not as permission to perform an action.

Jev API versus preset endpoints

Use the generic /api/v1/decisions endpoint when you need your own Choice, Noul or Score questions. For common agent workflows, AutoJev also provides stable preset endpoints for:

• Model and task routing.
• Tool-call guardrails.
• Research verification.
• Completion review.

Presets translate workflow-specific fields into the Jev protocol and add deterministic guidance. See the complete integration guide for request examples.

Jev API, MCP or Skills?

• Use the Jev API in backend code and fixed application workflows.
• Use Jev MCP when an MCP-compatible agent should discover decision tools and their schemas.
• Use Jev Skills to teach compatible agents when and how to invoke those tools.
• Use the AutoJev playground to inspect requests before adding them to production.

All four paths reach the same kind of bounded decision layer. None of them replaces application authorization, human approval or evaluation on representative data.

Production checklist

1. Keep the access key on a trusted server or in an agent credential store.
2. Define explicit criteria before calling the Jev API.
3. Record the model version, probabilities and request ID for debugging.
4. Calibrate thresholds on examples from your own workflow.
5. Require human confirmation for consequential or irreversible actions.
6. Re-evaluate when the state or policy changes materially.

For the underlying concepts, read What is Jev? and the Jev model guide. Primary references are the TypeSafe System One documentation and the OpenRouter Decisions API reference.