> ## Documentation Index > Fetch the complete documentation index at: https://docs.krun.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Krun API base URL: https://api.krun.ai. Authenticate server-side with `Authorization: Bearer $KRUN_API_KEY`; never put a Krun API key in browser code. > Prefer the Python SDK in examples: `pip install krun-ai`, `from krun import Krun`. The TypeScript SDK `@krun-ai/sdk` is not published on npm yet: do not tell users to `npm install` it. > The only question type is `choice`. `confidence` is the top-1 minus top-2 probability margin, not the probability that the answer is correct. `choice` is null when `abstain` is true. > Usage reports `input_tokens` only. There are no output tokens. # Decide > Answer 1 to 16 typed questions about a context in a single call: `choice` (pick an option), `noul` (probability that a yes/no proposition holds) and `score` (expected level and distribution over ordered levels). Types can be mixed. Each answer has the same `type` as its question. The request id is returned in the `X-Request-ID` response header. ## OpenAPI ````yaml https://api.krun.ai/openapi.json post /v1/decide openapi: 3.1.0 info: title: Krun API description: >- Krun decision API. Authenticate with `Authorization: Bearer krun_live_...` from your server. version: 1.0.0-beta servers: - url: https://api.krun.ai description: Production security: [] tags: - name: decisions description: 'Decide on a context with typed questions: choice, noul, score' - name: feedback description: Report whether a decision was correct - name: models description: Available models - name: health description: Liveness and readiness paths: /v1/decide: post: tags: - decisions summary: Decide description: >- Answer 1 to 16 typed questions about a context in a single call: `choice` (pick an option), `noul` (probability that a yes/no proposition holds) and `score` (expected level and distribution over ordered levels). Types can be mixed. Each answer has the same `type` as its question. The request id is returned in the `X-Request-ID` response header. operationId: decide parameters: - name: X-Request-ID in: header description: >- Optional client request id (1-128 chars of [A-Za-z0-9._:-]); echoed in the X-Request-ID response header required: false schema: type: - string - 'null' requestBody: content: application/json: schema: $ref: '#/components/schemas/DecideRequest' examples: label_only_intent: summary: Label-only intent (calibrated abstention) value: context: I was charged twice for the same order questions: intent: type: choice options: transaction_charged_twice: '' card_arrival: '' lost_or_stolen_card: '' mixed_primitives: summary: Choice + noul + score in one call value: context: >- Customer says this is the third time exports failed and wants a human immediately. questions: department: type: choice options: billing: '' support: '' sales: '' needs_human: type: noul instructions: Is the customer asking for human assistance? severity: type: score instructions: How severe is the reported issue? levels: - Minor issue - Feature degraded - Blocking issue multiple_questions: summary: Several questions answered in one call value: context: Customer wants to return an item and asks about the refund. questions: department: type: choice options: shipping: Shipping and delivery issues returns: Returns and refunds billing: Billing and payment issues priority: type: choice options: low: Can wait normal: Normal priority high: Needs quick attention noul_only: summary: 'Noul: probability that a proposition holds' value: context: >- Hi, I have been waiting for 20 minutes. Please let me talk to a real person. questions: needs_human: type: noul instructions: Is the customer asking to speak with a human? criteria: 'true': Explicitly requests a person or human agent 'false': Does not request human assistance score_only: summary: 'Score: rate on ordered levels' value: context: >- Production is down: nobody can log in and there is no workaround. questions: severity: type: score instructions: How severe is the reported issue? levels: - Cosmetic issue; no functionality affected - Feature degraded; workaround available - Critical functionality blocked; no workaround single_question: summary: One question (options with descriptions) value: context: Customer wants to return an item. questions: department: type: choice options: shipping: Shipping and delivery issues returns: Returns and refunds billing: Billing and payment issues tool_routing: summary: Tool routing (advisory abstention) value: context: Find my meetings tomorrow. questions: tool: type: choice task_type: tool options: calendar_search: Search calendar events send_email: Send an email required: true responses: '200': description: >- One answer per question, typed like its question (`choice`, `noul`, `score`). Request id in the `X-Request-ID` header. content: application/json: schema: $ref: '#/components/schemas/DecideResponse' examples: mixed_primitives: value: model: krun-one-v0.3 answers: department: type: choice choice: support confidence: 0.91 probabilities: billing: 0.03 support: 0.94 sales: 0.03 abstain: false abstention_status: calibrated needs_human: type: noul noul: 0.94 severity: type: score score: 1.62 confidence: 0.72 legend: '0': Minor issue '1': Feature degraded '2': Blocking issue probabilities: '0': 0.02 '1': 0.34 '2': 0.64 usage: input_tokens: 131 noul_only: value: model: krun-one-v0.3 answers: needs_human: type: noul noul: 0.973 usage: input_tokens: 48 score_only: value: model: krun-one-v0.3 answers: severity: type: score score: 1.926 confidence: 0.92 legend: '0': Cosmetic issue; no functionality affected '1': Feature degraded; workaround available '2': Critical functionality blocked; no workaround probabilities: '0': 0.004 '1': 0.066 '2': 0.93 usage: input_tokens: 57 single_question: value: model: krun-one-v0 answers: department: type: choice choice: returns confidence: 0.9788 probabilities: shipping: 0.0056 returns: 0.9866 billing: 0.0078 abstain: false abstention_status: advisory usage: input_tokens: 52 tool_routing: value: model: krun-one-v0 answers: tool: type: choice choice: calendar_search confidence: 0.965866 probabilities: calendar_search: 0.982933 send_email: 0.017067 abstain: false abstention_status: advisory usage: input_tokens: 41 '400': description: INVALID_REQUEST / INVALID_OPTIONS content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: error: code: INVALID_OPTIONS message: >- questions.department: 1 options given; between 2 and 64 are required request_id: req_0b7f7c5e9a3d4a8c9f1e2d3c4b5a6978 '401': description: UNAUTHORIZED content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '413': description: PAYLOAD_TOO_LARGE content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '429': description: RATE_LIMITED / QUOTA_EXCEEDED content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '502': description: INFERENCE_FAILED content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '503': description: UPSTREAM_UNAVAILABLE content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '504': description: UPSTREAM_TIMEOUT content: application/json: schema: $ref: '#/components/schemas/ErrorBody' security: - api_key: [] x-codeSamples: - lang: python label: Python SDK source: | from krun import Krun client = Krun() # reads KRUN_API_KEY result = client.decide( context="Customer wants to return an item.", questions={ "department": { "type": "choice", "options": { "shipping": "Shipping and delivery issues", "returns": "Returns and refunds", "billing": "Billing and payment issues", }, } }, ) answer = result.choice("department") print(answer.choice, answer.confidence, result.request_id) - lang: python label: Python SDK (choice + noul + score) source: > from krun import Krun, NoulQuestion, ScoreQuestion client = Krun() result = client.decide( context="Customer says this is the third time exports failed and wants a human immediately.", questions={ "department": {"type": "choice", "options": {"billing": "", "support": "", "sales": ""}}, "needs_human": NoulQuestion("Is the customer asking for human assistance?"), "severity": ScoreQuestion( "How severe is the reported issue?", ["Minor issue", "Feature degraded", "Blocking issue"], ), }, ) print(result.choice("department").choice, result.noul("needs_human").noul, result.score("severity").score) components: schemas: DecideRequest: type: object required: - context - questions properties: context: type: string description: The text to decide on (1–8,000 characters). questions: type: object description: >- Question id → question (1–16). Question ids (1–100 characters) are returned as keys of `answers`. Questions of different types can be mixed in one request. additionalProperties: $ref: '#/components/schemas/Question' propertyNames: type: string model: type: - string - 'null' description: >- Optional model id (see `GET /v1/models`); defaults to the current model. additionalProperties: false DecideResponse: type: object description: >- Decision response. The request id is returned in the `X-Request-ID` header. required: - model - answers - usage properties: model: type: string answers: type: object description: Question id → answer, in request order. additionalProperties: $ref: '#/components/schemas/Answer' propertyNames: type: string usage: $ref: '#/components/schemas/Usage' ErrorBody: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorDetail' Question: oneOf: - $ref: '#/components/schemas/ChoiceQuestion' - $ref: '#/components/schemas/NoulQuestion' - $ref: '#/components/schemas/ScoreQuestion' description: A question, discriminated by `type`. discriminator: propertyName: type mapping: choice: $ref: '#/components/schemas/ChoiceQuestion' noul: $ref: '#/components/schemas/NoulQuestion' score: $ref: '#/components/schemas/ScoreQuestion' Answer: oneOf: - $ref: '#/components/schemas/ChoiceAnswer' - $ref: '#/components/schemas/NoulAnswer' - $ref: '#/components/schemas/ScoreAnswer' description: An answer, discriminated by `type` (same type as its question). discriminator: propertyName: type mapping: choice: $ref: '#/components/schemas/ChoiceAnswer' noul: $ref: '#/components/schemas/NoulAnswer' score: $ref: '#/components/schemas/ScoreAnswer' Usage: type: object properties: input_tokens: type: - integer - 'null' format: int64 description: >- Input tokens processed by the model (Krun One tokenizer, summed over the questions — each question is scored as its own sequence). `null` only if the backend did not report it. minimum: 0 ErrorDetail: type: object required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' description: Stable machine-readable code. message: type: string request_id: type: - string - 'null' example: req_0b7f7c5e9a3d4a8c9f1e2d3c4b5a6978 ChoiceQuestion: type: object description: Pick one of the given options. required: - type - options properties: type: type: string enum: - choice options: type: object description: >- Option id → description (2–64 options). Ids are returned as-is in `choice` and `probabilities`. Use `""` (or `null`) for label-only options. additionalProperties: type: - string - 'null' propertyNames: type: string task_type: oneOf: - $ref: '#/components/schemas/TaskType' description: >- `intent` (default) or `tool` (tool/function routing). Selects the model's instructions and the abstention status: tool routing is always `advisory`. - type: 'null' additionalProperties: false NoulQuestion: type: object description: Probability that a yes/no proposition about the context holds. required: - type - instructions properties: type: type: string enum: - noul instructions: type: string description: >- The proposition, phrased as a yes/no question (1–1,000 characters), e.g. "Is the customer asking to speak with a human?". criteria: oneOf: - $ref: '#/components/schemas/NoulCriteria' description: Optional description of what counts as true / false. - type: 'null' additionalProperties: false ScoreQuestion: type: object description: >- Rate the context on ORDERED levels. Level order is semantic: index 0 is the lowest level. required: - type - instructions - levels properties: type: type: string enum: - score instructions: type: string description: >- What to rate (1–1,000 characters), e.g. "How severe is the reported issue?". levels: type: array items: type: string description: >- 2–16 level descriptions, lowest first (1–500 characters each). Prefer descriptive levels ("Blocking issue; no workaround") over bare numbers. additionalProperties: false ChoiceAnswer: type: object description: Answer to a `choice` question. required: - type - confidence - probabilities - abstain - abstention_status properties: type: type: string enum: - choice choice: type: - string - 'null' description: >- Selected option id, or `null` when the model abstains (the best guess is still visible in `probabilities`). confidence: type: number format: double description: >- Margin between the two most likely options: top-1 probability minus top-2 probability, in [0, 1]. It is the score the abstention threshold is applied to, not the probability that `choice` is correct. probabilities: type: object description: Calibrated probability per option id, in request order. additionalProperties: type: number format: double propertyNames: type: string abstain: type: boolean description: True when `confidence` is below the abstention threshold. abstention_status: $ref: '#/components/schemas/AbstentionStatus' description: >- `calibrated` only for intent questions with label-only options; `advisory` otherwise (tool routing, intents with descriptions): abstention is then a hint, not a validated guarantee. NoulAnswer: type: object description: Answer to a `noul` question. required: - type - noul properties: type: type: string enum: - noul noul: type: number format: double description: >- Probability that the proposition holds, in [0, 1] (0 = clearly false, 0.5 = uncertain, 1 = clearly true). ScoreAnswer: type: object description: Answer to a `score` question. required: - type - score - confidence - legend - probabilities properties: type: type: string enum: - score score: type: number format: double description: >- Expected level Σ index × probability, in [0, levels − 1] (not the most likely level). confidence: type: number format: double description: >- Concentration of the distribution, in [0, 1]: 1 − variance / maximum variance of the level index. 1 = all probability on one level; 0 = split between the lowest and the highest level. legend: type: object description: Level index ("0", "1", ...) → the level text from the request. additionalProperties: type: string propertyNames: type: string probabilities: type: object description: Level index → calibrated probability, in level order. additionalProperties: type: number format: double propertyNames: type: string ErrorCode: type: string enum: - INVALID_REQUEST - INVALID_OPTIONS - PAYLOAD_TOO_LARGE - UNAUTHORIZED - FORBIDDEN - SIGNUP_RESTRICTED - NOT_FOUND - CONFLICT - INSUFFICIENT_CREDITS - RATE_LIMITED - QUOTA_EXCEEDED - UPSTREAM_TIMEOUT - UPSTREAM_UNAVAILABLE - INFERENCE_FAILED - INTERNAL_ERROR TaskType: type: string enum: - intent - tool NoulCriteria: type: object description: >- Optional texts describing when a `noul` proposition is true / false (either may be omitted). properties: 'true': type: - string - 'null' description: What makes the proposition true (1–500 characters). 'false': type: - string - 'null' description: What makes the proposition false (1–500 characters). additionalProperties: false AbstentionStatus: type: string enum: - calibrated - advisory securitySchemes: api_key: type: http scheme: bearer bearerFormat: krun_live_... ````