Skip to main content

Decisions (Jev)

Evaluate information with Jev, a decision model hosted by TypeSafe, through your MindsHub API key. Send a state and named questions; receive matching answers with probabilities and token usage.

New to this kind of model? Read Decision models for when to use it and how to interpret its answers.

Endpoint​

POST https://api.mindshub.ai/v1/decisions

Send Authorization: Bearer $MINDSHUB_API_KEY and Content-Type: application/json. Get your key from the MindsHub console and keep it on your server, outside source control. See Authentication.

This is a MindsHub HTTP endpoint. You do not need a TypeSafe key or SDK. Chat SDK methods such as chat.completions.create() use a different request format; use an ordinary HTTP client for decisions.

Quick example​

This example evaluates one delivery report in three ways: selects a team (choice), checks for an explicit replacement request (noul), and rates damage (score). Python uses only the standard library. The TypeScript example uses native fetch in Node.js 20+ and runs as an ES module.

Set MINDSHUB_API_KEY in your server environment, then run the example for your language. The same JSON body works in every HTTP client.

import json
import os
from urllib.error import HTTPError
from urllib.request import Request, urlopen

payload = {
    "model": "jev",
    "state": {"report": "The outer box arrived torn. The item inside is undamaged and works normally."},
    "questions": {
        "team": {
            "type": "choice",
            "instructions": "Which team should review this delivery report?",
            "criteria": {
                "packaging": "Damage to the packaging, with the item itself intact.",
                "product": "Damage to the item itself.",
                "other": "A different issue, or not enough information to identify one.",
            },
        },
        "replacement": {
            "type": "noul",
            "instructions": "Does the report explicitly ask for a replacement item?",
        },
        "damage": {
            "type": "score",
            "instructions": "How much damage does the report describe?",
            "criteria": [
                "Both packaging and item are undamaged.",
                "Packaging is damaged; the item is intact and usable.",
                "The item is damaged and cannot be used normally.",
            ],
        },
    },
}

request = Request(
    "https://api.mindshub.ai/v1/decisions",
    headers={"Authorization": f"Bearer {os.environ['MINDSHUB_API_KEY']}", "Content-Type": "application/json"},
    data=json.dumps(payload).encode(),
)
try:
    with urlopen(request, timeout=40) as response:
        result = json.load(response)
except HTTPError as error:
    raise SystemExit(f"HTTP {error.code}: {error.read().decode()}") from None

print(json.dumps(result, indent=2))
print("Team:", result["answers"]["team"]["choice"])
print("Replacement requested (probability):", result["answers"]["replacement"]["noul"])
print("Damage (0–2):", result["answers"]["damage"]["score"])

The response has the keys answers.team, answers.replacement, and answers.damage. For this report, expect the packaging team, a low probability of a replacement request, and a damage score close to 1. Exact probabilities and token counts can vary.

For a dev deployment, replace the URL with https://api.dev.mindshub.ai/v1/decisions and use a key for that environment. The examples above use the production address; a model must be activated in the environment's catalog before it can be called.

Request parameters​

FieldTypeRequiredMeaning
modelstringYesA MindsHub decision alias; see Models.
statestring, object, or arrayYesThe information every question evaluates. Objects and arrays can contain nested JSON values. A top-level number, Boolean, or null is not a valid state.
questionsobjectYesA nonempty map of question names to question definitions. Each answer is returned under its question's name.
questions.<name>.typestringYesExactly noul, choice, or score; determines the criteria and answer shape.
questions.<name>.instructionsstring, object, array, or nullNoThe judgment to make. Use a clear sentence for your first integration.
questions.<name>.criteriaDepends on typeDepends on typeSee below.

Criteria for each type​

TypeCriteria contractGuidance
noulOptional object with optional true and false descriptions, or null. Each description may be a string, object, array, or null.Define what yes and no mean when the instruction alone is ambiguous.
choiceRequired object mapping option names to descriptions. Each description may be a string, object, array, or null; the criteria object itself cannot be null.Provide meaningful descriptions and an other option when appropriate.
scoreRequired nonempty array. Each level is a string, object, or array; a level cannot be null. Positions start at 0.Start with a few clearly distinct levels ordered along one dimension.

For example, a noul can make its boundary explicit:

{
  "type": "noul",
  "instructions": "Does the customer explicitly request a replacement?",
  "criteria": {
    "true": "The customer asks for another item to be sent.",
    "false": "The customer only describes a problem or asks for information."
  }
}

Instructions are optional in the wire schema, but the question's name is not an instruction. Always supply the meaning in instructions, criteria, or both. Prefer complete descriptions to relying on a name such as urgent.

The gateway preserves omitted fields, explicit null values, and additional JSON fields when forwarding the request. TypeSafe applies its own semantic validation. Unknown fields are not a promise of additional capabilities: use the documented fields above. In particular, chat parameters such as messages, temperature, max_tokens, tools, and stream are not supported controls for this endpoint.

The generated endpoint reference contains the complete schemas. For interpretation and question design, see Decision models.

Response​

One illustrative response to the complete quick example is shown below. Values are simplified for readability; do not assert exact numeric outputs in your application.

{
  "model": "jev-1.13.0",
  "answers": {
    "team": {
      "type": "choice",
      "choice": "packaging",
      "confidence": 1.0,
      "probabilities": {"packaging": 1.0, "product": 0.0, "other": 0.0}
    },
    "replacement": {"type": "noul", "noul": 0.0},
    "damage": {
      "type": "score",
      "score": 1.0,
      "confidence": 1.0,
      "legend": {
        "0": "Both packaging and item are undamaged.",
        "1": "Packaging is damaged; the item is intact and usable.",
        "2": "The item is damaged and cannot be used normally."
      },
      "probabilities": {"0": 0.0, "1": 1.0, "2": 0.0}
    }
  },
  "usage": {"input_tokens": 420, "output_tokens": 46}
}
FieldHow to use it
modelThe actual model version returned by TypeSafe. Record it when comparing results over time.
answersMap with the same names and question types as your request. Read by name, not object order.
Noul: noulProbability of yes, from 0 to 1. It is a number, not a Boolean.
Choice: choiceThe selected option name from your criteria.
Choice/score: probabilitiesProbabilities across the named choices or numbered levels. Allow small floating-point rounding differences when checking their sum.
Choice/score: confidenceTypeSafe's certainty statistic from 0 to 1. It is not necessarily the highest option probability.
Score: scoreProbability-weighted mean of the level numbers, between 0 and the last index. May be fractional.
Score: legendMap from string indices to your original level descriptions.
usage.input_tokens, usage.output_tokensProvider-reported token counts for the whole request, not one counter per question. Both are present even while the price is zero.

Models and versions​

Send in modelMeaning
jevThe Jev version adopted by MindsHub; currently jev-1.13.0.
jev-latestAn accepted synonym for jev. Moves when MindsHub updates its catalog.
jev-1.13.0The version pinned by this integration. Use it when evaluating changes against a fixed model.

MindsHub's aliases advance through MindsHub catalog updates; a new TypeSafe release does not automatically change them. Pinning a version controls selection, not how long the provider will keep serving it.

Use GET /v1/models with the same key to discover catalog models. Jev entries have kind: "decision"; an accepted synonym need not have its own row. TypeSafe-only aliases such as jev-preview are not automatically MindsHub aliases.

Unlike the chat and embedding endpoints, the decisions response's model reports the served version rather than echoing the requested alias. For example, requesting jev currently returns jev-1.13.0.

Limits and billing​

  • Launch promotion: Jev input and output both cost $0 through MindsHub, and requests do not consume the included allowance. See Billing.
  • Free daily allowance: an organization with wallet credit, or with a card that has completed a top-up and has no payment error, calls Jev without a daily cap. Every other organization gets a free allowance of 100,000 tokens and 100 requests while shared free capacity lasts, and it refills continuously by that much over every 24 hours. A new organization starts with a full allowance, so it can use roughly twice that on its first day. Past it, this endpoint returns 402 wallet_empty, and the X-MindsHub-Recovery-Url header carries the console path /billing, where you add credit. Organization permissions and rate limits apply to every organization.
  • Usage still exists: input and output token counts are returned and recorded on every call. Zero price does not mean zero tokens, and those tokens count toward the free daily allowance. Check the usage summary to reconcile your calls.
  • Context: the current Jev model allows 64,000 tokens for state plus all questions, and 32,000 tokens for state plus the longest individual question. Both limits must be met; TypeSafe enforces them. See the provider's model limits.
  • Several questions: include independent questions about the same state in one request. The state is shared, while the questions and their criteria still contribute input tokens. This is not a separate batch-jobs API.
  • Request rate: MindsHub's rate limits and provider capacity apply. TypeSafe's direct-account limits are not a throughput entitlement for a MindsHub key.

Endpoint behavior​

The call is synchronous: it returns one JSON response after evaluation. There is no SSE streaming, background polling, tool execution, or conversation chaining. Each request must contain all the state its questions need. No image, audio, or video input is supported.

MindsHub handles authentication, access, model selection, and usage accounting; TypeSafe serves Jev. Successful provider answers and usage are returned in their native JSON shape. The endpoint validates the response before returning it, so an invalid provider response can produce a 503 (upstream_status: 502) instead of partial answers.

Errors and retries​

Check the HTTP status before reading answers. Errors may contain a MindsHub error object, a validation detail list, or TypeSafe's original body. The examples retain the error status and body rather than assuming one universal shape.

StatusTypical causeWhat to do
400Wrong model kind, model not configured, or provider rejectionInspect the code/message. Use a decision model and correct the request; report a configuration failure.
401 / 403Invalid MindsHub key or insufficient accessCheck the key, its environment, and organization permissions.
402wallet_empty: neither wallet credit nor a topped-up card free of payment errors, and the free daily allowance or shared free capacity is used upAdd credit; the X-MindsHub-Recovery-Url header carries the console path. Without credit the allowance refills gradually over 24 hours, so an immediate retry is refused again.
404Alias absent from this environment's catalog or unavailable to this accountCheck GET /v1/models on the same host with the same key.
422Missing field, invalid question type/shape, or provider validationInspect the field error, fix the payload, and resend.
429 / 529Rate limit or provider overloadHonor Retry-After when supplied; use bounded backoff.
503Access policy temporarily unavailableRetry with bounded backoff.
503 with upstream_status: 502Provider connection, credential, or response problemPreserve the response for diagnosis. Check the retry caveat below before resending.
503 with upstream_status: 504Provider timeoutThe evaluation may already have run; do not assume that resending is free of duplicate work.

The gateway never sends a 502 or 504: the network edge would replace them with its own page and discard the body, so both arrive as a 503 with the original status in error.upstream_status (at the top level when the body has no error object). Provider validation, rate-limit, and overload errors keep their status and body, including Retry-After when supplied. A provider credential failure becomes a 503 with upstream_status: 502; it does not mean your MindsHub key needs replacing. Other provider failures may retain their original status. See Errors for common MindsHub access failures.

The gateway may retry one explicit provider 429 or 529 refusal when the requested delay is at most one second. It does not automatically retry ambiguous timeouts or disconnects. There is no documented idempotency key for this endpoint: a repeated POST can execute another evaluation. Even at a $0 price, a repeated evaluation uses rate-limit capacity and, for an organization without credit, its free daily allowance. Every request that passes the funding check counts toward the daily requests, including one the provider refuses or times out, so account for duplicate work before adding client retries.

For support, retain the HTTP status, response body, any request ID in the response headers, requested model, and timestamp. Keep API keys out of logs and support messages.