jev http api

The Endpoint Evaluates State; It Does Not Execute a Workflow

The HTTP boundary is deliberately small. state holds evidence, questions defines bounded semantic measurements and model selects the Jev release channel or pinned version. The service does not fetch private records, validate permissions, execute the chosen action or decide whether a probability is sufficient for that action.

Authenticate and construct the request on a trusted server. Validate, redact and minimize state before it crosses the provider boundary. The how-Jev-works guide explains the current state-projection and application-control boundary.

Complete Request with All Three Question Types

State and instructions may be strings, JSON objects or arrays. Choice accepts up to 255 options. Score requires at least two levels and accepts up to 10. Question IDs are returned to the caller but, according to the API docs, are not sent to the underlying model; semantic meaning belongs in instructions and criteria.

{
  "model": "jev-1.13.0",
  "state": {
    "message": "I was charged twice; payroll is blocked.",
    "plan": "business"
  },
  "questions": {
    "refund_requested": {
      "type": "noul",
      "instructions": "Does the customer explicitly ask to reverse a charge?"
    },
    "queue": {
      "type": "choice",
      "instructions": "Which approved team should handle this?",
      "criteria": {
        "billing": "Charges, invoices and refunds",
        "technical": "Product errors and integrations",
        "other": "Neither billing nor technical"
      }
    },
    "urgency": {
      "type": "score",
      "instructions": "How urgent is this ticket?",
      "criteria": [
        "Routine: no deadline or blocked work",
        "Time-sensitive: deadline or degraded work",
        "Critical: essential work is blocked"
      ]
    }
  }
}

Answers Form a Discriminated Union

This response illustrates the documented shape rather than a captured model result. Dispatch on type: Noul contains noul; Choice contains choice, probabilities and confidence; Score contains score, legend, probabilities and confidence. Option and level probabilities sum to one. Preserve usage.input_tokens and usage.output_tokens for capacity and cost analysis.

{
  "model": "jev-1.13.0",
  "answers": {
    "refund_requested": { "type": "noul", "noul": 0.91 },
    "queue": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.88, "technical": 0.09, "other": 0.03 },
      "confidence": 0.81
    },
    "urgency": {
      "type": "score",
      "score": 1.7,
      "legend": { "0": "Routine", "1": "Time-sensitive", "2": "Critical" },
      "probabilities": { "0": 0.05, "1": 0.20, "2": 0.75 },
      "confidence": 0.68
    }
  },
  "usage": { "input_tokens": 420, "output_tokens": 52 }
}

Validate at Both Sides of the Boundary

A valid response can become stale between request and action. Re-check mutable permissions, inventory or account state after inference. Never use a returned Choice key as authority to invoke an action that was not already in the permitted candidate set.

HTTP Failures Have Different Retry Semantics

TypeSafe says its client SDKs handle 429 and 529 with exponential backoff under their defaults. Raw HTTP clients must implement equivalent bounded behavior. Retrying a non-idempotent downstream action is a separate concern: the Jev POST evaluates state, while application code must ensure it does not duplicate the action after a retry or ambiguous timeout.

Log Enough to Reproduce a Decision Without Leaking State

Avoid indiscriminate request-body logging when state can contain private or adversarial content. Store controlled evidence references or redacted projections according to retention policy. The model card explains provider and data-use boundaries.

• Internal decision/event ID and provider request ID when present.
• Resolved model, endpoint/provider and client version.
• Question, criteria and state-projection versions or hashes.
• Complete typed answers, token usage, latency, attempts and final transport outcome.
• Derived action, threshold/policy version, override and eventual observed outcome.