Skip to content

Get up and running with Kimi, GLM, MiniMax, DeepSeek, gpt-oss, Qwen, Gemma and other models.

docs: document System One API (#18702)

Parth Sareen1abe35e6e6e7
diff --git a/docs/api/introduction.mdx b/docs/api/introduction.mdx
index 0b42a6b30..2d7a73d4b 100644
--- a/docs/api/introduction.mdx
+++ b/docs/api/introduction.mdx
@@ -22,7 +22,7 @@ The Anthropic client appends `/v1/messages` to its base URL.
Cloud requests need an API key. Local requests do not. To use cloud models through your local server, [sign in to Ollama](/api/authentication#signing-in).
-Creating or deleting models requires a local Ollama server. For supported API features, see [OpenAI compatibility](/api/openai-compatibility) and [Anthropic compatibility](/api/anthropic-compatibility).
+Creating or deleting models requires a local Ollama server. [System One](/capabilities/decision) also requires a local server and is not yet available on Ollama Cloud. For supported API features, see [OpenAI compatibility](/api/openai-compatibility) and [Anthropic compatibility](/api/anthropic-compatibility).
## Ollama API example
diff --git a/docs/capabilities/decision.mdx b/docs/capabilities/decision.mdx
new file mode 100644
index 000000000..5ba05daf2
--- /dev/null
+++ b/docs/capabilities/decision.mdx
@@ -0,0 +1,113 @@
+---
+title: Decision
+description: Classify text, estimate yes/no probabilities, and score ordered criteria.
+---
+
+<Note>
+Currently available locally in Ollama.
+</Note>
+
+Use System One to classify text, answer yes/no questions, or score text against a rubric.
+
+## Setup
+
+Start [Ollama](/quickstart) v0.35.0 or later, then download [Nimble](https://ollama.com/library/nimble):
+
+```shell setup.sh
+ollama pull nimble
+```
+
+Local requests do not need an API key.
+
+## Choose a label
+
+Put your input in `state` and describe the possible answers in `criteria`:
+
+```shell choice.sh
+curl http://localhost:11434/v1/systemone \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "model": "nimble",
+ "state": "Our checkout has returned 500 errors since 9am.",
+ "questions": {
+ "label": {
+ "type": "choice",
+ "instructions": "Which label fits this ticket?",
+ "criteria": {
+ "billing": "Payments and refunds",
+ "bug": "Software errors",
+ "account": "Login and account access"
+ }
+ }
+ }
+ }'
+```
+
+Example response:
+
+```json
+{
+ "model": "nimble",
+ "answers": {
+ "label": {
+ "type": "choice",
+ "choice": "bug",
+ "probabilities": {"billing": 0.0125, "bug": 0.9781, "account": 0.0093},
+ "confidence": 0.8906
+ }
+ },
+ "usage": {"input_tokens": 174, "output_tokens": 1}
+}
+```
+
+## Question types
+
+| Type | Criteria | Result |
+| --- | --- | --- |
+| `choice` | 2–26 named options with descriptions | The most likely option and each option's probability |
+| `noul` | Descriptions for `"false"` and `"true"` | The probability of `true`, from 0 to 1 |
+| `score` | 2–26 descriptions, ordered from lowest to highest | The probability-weighted average of the zero-based levels |
+
+For the urgency criteria below:
+
+```text
+score = 0 × P(Routine) + 1 × P(Soon) + 2 × P(Immediate)
+```
+
+For `choice` and `score`, `confidence` measures how strongly the model favors one answer over the others, from 0 to 1. A higher value does not guarantee the answer is correct.
+
+## Ask multiple questions
+
+Combine question types in one request. Here, both questions use the same ticket:
+
+```shell multiple.sh
+curl http://localhost:11434/v1/systemone \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "model": "nimble",
+ "state": {"ticket": "I was charged twice. Please refund the extra payment."},
+ "questions": {
+ "refund": {
+ "type": "noul",
+ "instructions": "Is the customer requesting a refund?",
+ "criteria": {
+ "false": "No refund is requested",
+ "true": "The customer requests a refund"
+ }
+ },
+ "urgency": {
+ "type": "score",
+ "instructions": "How urgently does this ticket need a response?",
+ "criteria": [
+ "Routine: no time pressure",
+ "Soon: a customer is inconvenienced",
+ "Immediate: a critical service is unavailable"
+ ]
+ }
+ }
+ }'
+```
+
+This returns a refund probability of `0.9989` and an urgency score of `0.8308` on the 0–2 scale (rounded). Results can vary with the model and configuration.
+
+See the [API reference](/api/systemone) for request fields, limits, errors, and token usage.
diff --git a/docs/docs.json b/docs/docs.json
index 1f7524517..44a655bcd 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -128,6 +128,7 @@
"/capabilities/streaming",
"/capabilities/thinking",
"/capabilities/structured-outputs",
+ "/capabilities/decision",
"/capabilities/vision",
"/capabilities/embeddings",
"/capabilities/tool-calling",
@@ -249,6 +250,7 @@
"POST /api/generate",
"POST /api/chat",
"POST /api/embed",
+ "POST /v1/systemone",
"GET /api/tags",
"GET /api/ps",
"POST /api/show",
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index e79419e1f..655d1ec5b 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -828,6 +828,189 @@ components:
items:
$ref: "#/components/schemas/TokenLogprob"
description: Most likely tokens and their log probabilities at this position
+ SystemOneContent:
+ description: A nonempty string, or an object or array serialized as JSON text. Not interpreted as chat messages or multimodal input.
+ oneOf:
+ - type: string
+ pattern: '\S'
+ - type: object
+ additionalProperties: true
+ - type: array
+ items: {}
+ SystemOneChoiceQuestion:
+ title: Choice
+ type: object
+ required: [type, instructions, criteria]
+ properties:
+ type:
+ type: string
+ enum: [choice]
+ instructions:
+ $ref: "#/components/schemas/SystemOneContent"
+ criteria:
+ type: object
+ description: Option keys mapped to descriptions. A null description uses the key itself. Keys must not be blank; ties select the first option in request order.
+ minProperties: 2
+ maxProperties: 26
+ propertyNames:
+ pattern: '\S'
+ additionalProperties:
+ type: [string, "null"]
+ SystemOneNoulQuestion:
+ title: Noul
+ type: object
+ required: [type, instructions]
+ properties:
+ type:
+ type: string
+ enum: [noul]
+ instructions:
+ $ref: "#/components/schemas/SystemOneContent"
+ criteria:
+ type: object
+ description: Optional descriptions for the two outcomes. Omitted entries use No and Yes.
+ properties:
+ "false":
+ type: string
+ default: "No"
+ "true":
+ type: string
+ default: "Yes"
+ additionalProperties: false
+ SystemOneScoreQuestion:
+ title: Score
+ type: object
+ required: [type, instructions, criteria]
+ properties:
+ type:
+ type: string
+ enum: [score]
+ instructions:
+ $ref: "#/components/schemas/SystemOneContent"
+ criteria:
+ type: array
+ description: Descriptions ordered from the lowest score (index 0) to the highest. Defines a scale from 0 to the number of criteria minus 1.
+ minItems: 2
+ maxItems: 26
+ items:
+ type: string
+ SystemOneRequest:
+ type: object
+ required: [model, state, questions]
+ properties:
+ model:
+ type: string
+ pattern: '\S'
+ description: Local model trained for System One, such as nimble. Requires compatible GGUF weights and a scoring-capable runner; cloud and MLX/Safetensors models are not supported.
+ state:
+ $ref: "#/components/schemas/SystemOneContent"
+ questions:
+ type: object
+ description: Named questions about the shared state. Each is scored separately against the full state and question schema; answers are not passed to later questions.
+ minProperties: 1
+ maxProperties: 64
+ propertyNames:
+ pattern: '\S'
+ additionalProperties:
+ oneOf:
+ - $ref: "#/components/schemas/SystemOneChoiceQuestion"
+ - $ref: "#/components/schemas/SystemOneNoulQuestion"
+ - $ref: "#/components/schemas/SystemOneScoreQuestion"
+ keep_alive:
+ oneOf:
+ - type: string
+ - type: number
+ description: How long to keep the model loaded after the request, as a duration string (such as 5m) or seconds. Zero unloads after the request; a negative value keeps it loaded. Defaults to the server's keep-alive setting (5m unless configured otherwise).
+ SystemOneProbabilities:
+ type: object
+ description: Probabilities normalized over the supplied candidates, summing to 1 subject to floating-point precision.
+ additionalProperties:
+ type: number
+ minimum: 0
+ maximum: 1
+ SystemOneConfidence:
+ type: number
+ minimum: 0
+ maximum: 1
+ description: Distribution concentration, calculated as 1 - H(p) / ln(N), where H(p) is entropy and N is the candidate count. Zero means uniform probabilities; values near 1 mean one candidate dominates. Not calibrated correctness.
+ SystemOneChoiceAnswer:
+ title: Choice
+ type: object
+ required: [type, choice, probabilities, confidence]
+ properties:
+ type:
+ type: string
+ enum: [choice]
+ choice:
+ type: string
+ description: Option key with the highest probability. Ties select the first option in request order.
+ probabilities:
+ $ref: "#/components/schemas/SystemOneProbabilities"
+ confidence:
+ $ref: "#/components/schemas/SystemOneConfidence"
+ SystemOneNoulAnswer:
+ title: Noul
+ type: object
+ required: [type, noul]
+ properties:
+ type:
+ type: string
+ enum: [noul]
+ noul:
+ type: number
+ minimum: 0
+ maximum: 1
+ description: Probability of true among the false and true candidates. This is a number, not a Boolean.
+ SystemOneScoreAnswer:
+ title: Score
+ type: object
+ required: [type, score, legend, probabilities, confidence]
+ properties:
+ type:
+ type: string
+ enum: [score]
+ score:
+ type: number
+ minimum: 0
+ maximum: 25
+ description: Probability-weighted average of the zero-based criterion indices, from 0 to the number of criteria minus 1. Not rounded to a level or normalized to 0–1.
+ legend:
+ type: object
+ description: Zero-based indices as string keys mapped to the criterion descriptions.
+ additionalProperties:
+ type: string
+ probabilities:
+ $ref: "#/components/schemas/SystemOneProbabilities"
+ description: Probabilities keyed by zero-based criterion indices as strings.
+ confidence:
+ $ref: "#/components/schemas/SystemOneConfidence"
+ SystemOneResponse:
+ type: object
+ required: [model, answers, usage]
+ properties:
+ model:
+ type: string
+ description: Model name from the request.
+ answers:
+ type: object
+ description: Answers keyed by the question names in the request.
+ additionalProperties:
+ oneOf:
+ - $ref: "#/components/schemas/SystemOneChoiceAnswer"
+ - $ref: "#/components/schemas/SystemOneNoulAnswer"
+ - $ref: "#/components/schemas/SystemOneScoreAnswer"
+ usage:
+ type: object
+ required: [input_tokens, output_tokens]
+ properties:
+ input_tokens:
+ type: integer
+ minimum: 0
+ description: Sum of full rendered prompt lengths across all questions, including repeated shared context even when cached.
+ output_tokens:
+ type: integer
+ minimum: 0
+ description: Tokens generated internally for scoring, including prefix preparation and retries. May exceed the question count; not the length of the JSON response.
ErrorResponse:
type: object
properties:
@@ -835,6 +1018,109 @@ components:
type: string
description: Error message describing what went wrong
paths:
+ /v1/systemone:
+ post:
+ summary: Answer typed questions
+ description: |
+ Answer choice, yes/no, and scoring questions with a local System One model. Requires Ollama v0.35.0 or later. See the [decision guide](/capabilities/decision) for examples.
+ operationId: systemone
+ x-mint:
+ href: /api/systemone
+ metadata:
+ title: System One
+ sidebarTitle: System One
+ content: |
+ <Note>
+ Currently available locally in Ollama.
+ </Note>
+
+ - Returns one JSON response; streaming, images, tools, and generation controls are not supported.
+ - Requests must fit within 64 KiB. Each rendered prompt must fit the loaded context window with two token positions left for scoring. Input is never truncated.
+ x-codeSamples:
+ - lang: bash
+ label: Choose a label
+ source: |
+ curl http://localhost:11434/v1/systemone \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "model": "nimble",
+ "state": "Our checkout has returned 500 errors since 9am.",
+ "questions": {
+ "label": {
+ "type": "choice",
+ "instructions": "Which label fits this ticket?",
+ "criteria": {
+ "billing": "Payments and refunds",
+ "bug": "Software errors",
+ "account": "Login and account access"
+ }
+ }
+ }
+ }'
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/SystemOneRequest"
+ example:
+ model: nimble
+ state: Our checkout has returned 500 errors since 9am.
+ questions:
+ label:
+ type: choice
+ instructions: Which label fits this ticket?
+ criteria:
+ billing: Payments and refunds
+ bug: Software errors
+ account: Login and account access
+ responses:
+ "200":
+ description: Answers and token usage for all questions. Example probabilities and confidence are rounded to four decimal places; results and usage can vary with the model and server configuration.
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/SystemOneResponse"
+ example:
+ model: nimble
+ answers:
+ label:
+ type: choice
+ choice: bug
+ probabilities:
+ billing: 0.0125
+ bug: 0.9781
+ account: 0.0093
+ confidence: 0.8906
+ usage:
+ input_tokens: 174
+ output_tokens: 1
+ "400":
+ description: Invalid request, unsupported model or runner, or a rendered prompt that exceeds the loaded context. Cloud models are rejected.
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/ErrorResponse"
+ "404":
+ description: Local model not found. Download the model before making a request.
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/ErrorResponse"
+ "413":
+ description: Request body exceeds 64 KiB.
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/ErrorResponse"
+ example:
+ error: request body must not exceed 64 KiB
+ "500":
+ description: Model loading, rendering, or scoring failed.
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/ErrorResponse"
/api/generate:
post:
summary: Generate a response