> ## Documentation Index
> Fetch the complete documentation index at: https://gomodel-feat-mcp-discovery.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Jev / Kev (TypeSafe System One)
> Route TypeSafe System One decision requests through GoModel, to the hosted Jev API or a self-hosted Kev server.
[Jev](https://docs.typesafe.ai/introduction) is TypeSafe's System One model: a
decision model rather than a text generator. A request carries a `state` (the
text or record to evaluate) and a map of typed questions, and the answer is a
calibrated probability per question. [Kev](https://github.com/jaredpalmer/kev)
is a family of small open-weight models that implement the same API, so one
`jev` provider type covers both.
There are three question types:
| Type | Asks | Answer |
| - | - | - |
| `noul` | A yes/no question | `noul`: the probability of yes |
| `choice` | Pick one option from a set you define | `choice`, plus `probabilities` and `confidence` |
| `score` | Rate against ordered levels | `score`, plus `legend`, `probabilities` and `confidence` |
The API is not OpenAI-compatible, and its answers have no chat equivalent, so
GoModel forwards it natively instead of translating it: `POST /v1/systemone`
is available as soon as a `jev` or `openrouter` provider is configured, and
[passthrough](/features/passthrough-api) at `/p/jev/...` reaches every other
upstream route. Chat, `/responses`, and `/v1/embeddings` return
`invalid_request_error` for `jev` models, pointing at `/v1/systemone`.
## Configure
For the hosted API, the key is the whole setup:
```bash theme={null}
JEV_API_KEY=ts-...
GOMODEL_MASTER_KEY=change-me
```
For a self-hosted Kev server, set the base URL instead. Kev has no
authentication of its own, so leave the key unset:
```bash theme={null}
JEV_BASE_URL=http://host.docker.internal:8009
GOMODEL_MASTER_KEY=change-me
```
The default base URL is `https://api.typesafe.ai`, the origin TypeSafe's SDKs
use; a trailing `/v1` is accepted and trimmed, so both spellings address the
same server. To run the hosted API and a local Kev side by side, register the
second under a suffixed name: `JEV_KEV_BASE_URL=...` creates provider
`jev-kev`, reached at `/p/jev-kev/...`. In `config.yaml`, any name works,
such as `kev: {type: jev, base_url: ...}`, and that name is what logs,
usage, and model prefixes show.
## Verify
```bash theme={null}
curl -s http://localhost:8080/v1/systemone \
-H "Authorization: Bearer change-me" \
-H "Content-Type: application/json" \
-d '{
"state": "Shoes arrived two weeks late and in the wrong size. Also I see two charges on my card.",
"model": "jev-latest",
"questions": {
"department": {"type": "choice", "instructions": "Which team should handle this?",
"criteria": {"returns": "Exchanges, refunds, wrong or damaged items",
"shipping": "Delivery status, delays, lost packages",
"billing": "Charges, invoices, payment problems"}},
"escalate": {"type": "noul", "instructions": "Does this need urgent human attention?"},
"frustration": {"type": "score", "instructions": "How frustrated is the customer?",
"criteria": ["Calm", "Frustrated", "Very angry"]}
}
}'
```
```json theme={null}
{
"model": "jev-1.13.0",
"answers": {
"department": {"type": "choice", "choice": "returns", "confidence": 0.21,
"probabilities": {"returns": 0.47, "shipping": 0.28, "billing": 0.25}},
"escalate": {"type": "noul", "noul": 0.93},
"frustration": {"type": "score", "score": 1.44, "confidence": 0.78,
"legend": {"0": "Calm", "1": "Frustrated", "2": "Very angry"},
"probabilities": {"0": 0.00, "1": 0.56, "2": 0.44}}
},
"usage": {"input_tokens": 101, "output_tokens": 161}
}
```
Use `kev-latest` as the model on a Kev server; it also answers to
`jev-latest`. The same request works at `/p/jev/v1/systemone`, but that
passthrough route skips virtual models and guardrails; see
[the native endpoint](#the-native-endpoint).
## Using the TypeSafe SDKs
The SDKs send `POST {base_url}/v1/systemone`, so point them at the gateway
itself and authenticate with your GoModel key:
```python Python theme={null}
from typesafe_sdk import Noul, TypeSafeClient
client = TypeSafeClient(api_key="change-me", base_url="http://localhost:8080")
response = client.system_one(
state="I was charged twice. Please fix this ASAP.",
questions={"billing": Noul(instructions="Is this ticket about billing?")},
)
print(response.nouls["billing"].noul)
```
```typescript JavaScript theme={null}
import { TypeSafeClient, noul } from "@typesafe-ai/sdk";
const client = new TypeSafeClient({ apiKey: "change-me", baseURL: "http://localhost:8080" });
const result = await client.systemOne({
state: "I was charged twice. Please fix this ASAP.",
questions: { billing: noul({ instructions: "Is this ticket about billing?" }) },
});
console.log(result.answers.billing.noul);
```
The same works with `TYPESAFE_BASE_URL=http://localhost:8080` and
`TYPESAFE_API_KEY=change-me` in the environment. With several System One
providers, name the model with its provider (`kev/kev-latest`) or a
[virtual model](/features/virtual-models).
The SDKs' model listing expects TypeSafe's shape, while the gateway's
`/v1/models` is OpenAI-shaped; list upstream models at `/p/jev/v1/models`.
## System One API
`POST /v1/systemone` is a gateway endpoint, not a raw proxy: it applies
virtual models, guardrails on `state`, the response cache, failover, audit,
and usage, and it forwards the request natively without translating it. Kev's
`/v1/systemone/permute` and `/v1/systemone/separate` work the same way. See
[System One API](/advanced/systemone-api) for the full behavior, including
OpenRouter, which serves Jev natively too.
Every other upstream route is reachable through
[passthrough](/features/passthrough-api), without virtual models, guardrails,
or caching:
| Route | What it does |
| - | - |
| `GET /p/jev/v1/models` | The names the `model` field accepts, in the upstream's own shape |
| `POST /p/jev/v1/systemone` | The evaluation route, forwarded as sent |
Upstream errors keep their status code, with the provider's body carried in
the gateway error message: a malformed question comes back as TypeSafe's `422`
naming the offending field, and `429` or `529` mean back off and retry.
## Models, access control, and cost
`GET /v1/models` lists what the upstream reports, as `jev/jev-latest` and so
on. TypeSafe lists its aliases (`jev-latest`, `jev-preview`); a Kev server
lists its checkpoint (`kev-latest`) and the aliases it answers to. Versioned
IDs such as `jev-1.13.0` are accepted by the `model` field whether or not they
are listed. The models are categorized as utility models with no generation
mode, since there is no OpenAI endpoint to route them to.
Every System One request names its model, so both `/v1/systemone` and the
passthrough surface apply the caller's [model allowlist](/features/users) to
it like any other request.
A pinned version such as `jev-1.13.0` works without being declared; see
[Models](/advanced/systemone-api#models) for how unlisted names are routed.
The response's `usage.input_tokens` and `usage.output_tokens` are recorded, so
System One calls appear in the usage API and dashboard under the model that
answered (`jev-1.13.0`, or the Kev checkpoint). Jev is priced per input token
and is not in the upstream model catalog; declare its pricing on the provider
to have those rows costed, or set it in the
[pricing override editor](/features/cost-tracking):
```yaml theme={null}
providers:
jev:
type: jev
api_key: "${JEV_API_KEY}"
models:
- id: "jev-1.13.0"
metadata:
pricing:
currency: USD
input_per_mtok: 0.042
output_per_mtok: 0
```
A local Kev server costs nothing per token, so it needs no pricing.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.