API reference

Send a state and named questions to POST /v1/systemone. The aliases /api/alpha/decisions and /v1/decisions accept the same request. The interface follows Jev; the underlying model and probabilities are different.

Authentication

You create the key yourself. For example, run python -c 'import secrets; print(secrets.token_urlsafe(32))' and keep the result private. Set that value as SELFJEV_API_KEYS on the server. Set the same value as SELFJEV_API_KEY in your client environment, or pass it as api_key in the Python SDK. The client sends it in the Authorization: Bearer ... header and the server checks for an exact match. SELFJEV_API_KEYS can contain several comma-separated keys; any one is accepted. If you do not configure server keys, requests require no authentication.

This is your SelfJev server key, separate from a Hugging Face token, AWS credentials, or a TypeSafe/Jev key. The AWS deployment helper generates a key automatically if you do not pass --api-key; it prints it and stores it in ~/.selfjev/deployments/<name>.json.

Make a request

curl http://localhost:8000/v1/systemone \
  -H "Authorization: Bearer $SELFJEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "selfjev-4b",
    "state": "My invoice was charged twice. Please refund me.",
    "questions": {
      "refund": {
        "type": "noul",
        "instructions": "Does the customer ask for a refund?"
      },
      "team": {
        "type": "choice",
        "instructions": "Which team should handle this?",
        "criteria": {"billing": "payments and refunds", "tech": "technical issues"}
      }
    }
  }'

SELFJEV_API_KEY is the client-side environment variable; set it to one of the server’s configured keys.

Four answer types

multi is a SelfJev extension. Its probabilities do not sum to one. For choice, add an explicit “none of the above” option if that outcome is valid.

Response shape

Illustrative response; probabilities below are examples, not a recorded inference:

{
  "id": "dec_example",
  "model": "selfjev-4b",
  "answers": {
    "refund": {"type": "noul", "noul": 0.97},
    "team": {
      "type": "choice",
      "choice": "billing",
      "probabilities": {"billing": 0.99, "tech": 0.01},
      "confidence": 0.98
    }
  },
  "usage": {"input_tokens": 296, "output_tokens": 0}
}

output_tokens is always zero: the engine scores answers rather than generating them. For a choice with K options, confidence is (K × max_probability − 1) / (K − 1). It is not a separate guarantee of correctness.

Limits and errors

Up to 64 questions per request. The default path limit is 32,768 tokens, but training used texts up to 16K; longer accepted contexts are not validated. Invalid or oversized inputs receive 422, never silent truncation.

The Python SDK retries 429, 529, and 5xx responses. AsyncSelfJev provides the same methods with await.

Further reference

See the complete API contract for score and multi examples, file uploads, fine-tuning endpoints, and the native /classify schema.