The /v1/systemone endpoint takes the System One API’s request and returns its response. A client written for TypeSafe’s API or for a vLLM Semantic Router engine works against Rolter by changing its base URL and using a Rolter virtual key. Rolter authenticates the request, picks a target from the route, writes the target’s upstream model into model, and forwards the body unchanged, so question types and fields Rolter has never seen still reach the model.
Set up the decision servers behind it under System One decisions.
Request#
POST /v1/systemone
Headers#
Must be application/json.
Body#
The route name, for example jev. Rolter replaces it with the target’s upstream model id (jev-latest, vllm-sr/d3-edge) before forwarding. Returns 404 if no route matches.
The input the questions are about: a ticket, a message, a document, a JSON record.
Questions keyed by ids you choose. Each answer comes back under the same id. Every question has a type and instructions; most have criteria:
choice:criteriamaps each option to a description. The answer names the most likely option.score:criteriais a list of 2 to 10 level descriptions, lowest first. The answer is a probability-weighted level.noul: a yes/no question;criteriamay describetrueandfalse. The answer is the probability of yes.
Other types (Vela’s span and set, for example) are forwarded as written; whether they are answered depends on the model.
Fields beyond these are forwarded as written too. Their names are upstream-specific.
Images with OpenJev#
The Playground’s Decisions mode accepts text or JSON state, a questions object,
and one JPEG, PNG or WebP image. It sends the image separately as image_data
(a base64 data URI), not as chat messages, image_url, or an images array:
This follows AlexWortega’s OpenJev image-serving contract,
used by the image and frame-scoring examples in the OpenJev Space.
The image is shared by all questions; <<IMG>> is optional and positions it in the
premise. OpenJev appends it when absent. Limits are 4 MiB decoded and 12 million
pixels. Remote image URLs and server file paths are not accepted. Vision needs a
compatible upstream; fake-llm exercises the request shape but does not inspect pixels.
The Space’s video example samples frames and scores each separately; it is not a
native video payload for this endpoint.
The Playground renders choice probabilities, score legends, yes probabilities,
confidence and per-question errors, with the full JSON response available below.
Its model picker uses rolter_capabilities from the gateway model list, so a
decision-only address is not offered in Chat. Older gateways without that metadata
still offer fake-llm in Decisions; update the gateway to discover configured routes.
Example#
Response#
The decision server’s response, as it wrote it:
usage drives the request’s cost and its budget and rate-limit accounting. The response headers carry x-rolter-provider and x-rolter-target, as on every proxied endpoint.
Errors#
| Status | Code | When |
|---|---|---|
400 | unsupported_endpoint | The route’s targets cannot answer decisions (none is system_one, openai_compatible or ollama) |
400 | guardrail_blocked | A guardrail rule matched text in state or in a question |
401 | invalid_api_key | The virtual key is missing or not valid |
404 | model_not_found | No route matches model |
429 | A rate limit or the route’s caps refused the request |
An error the decision server returns (TypeSafe’s 422 for a malformed question, for example) reaches the caller unchanged.
The reverse also holds: a route whose targets are all system_one refuses /v1/chat/completions, /v1/messages, /v1/embeddings and the audio endpoints with 400 unsupported_endpoint, since a decision model cannot answer them.
Without a decision server#
The built-in fake-llm model answers choice, score and noul questions deterministically and reports input-only usage, so the endpoint can be tried and tested with no key and no GPU: