--- name: vansa-api description: Integrate the VANSA System One API for classification, ordered scoring, and yes/no decisions. Use when a user wants VANSA in an application or agent workflow, including request design, typed response handling, and debugging integrations. --- # VANSA API VANSA is a System One decision model. Give it context and defined outcomes; it returns choices, scores, and probabilities. Use it for decisions inside software, such as routing an incident, assessing delivery urgency, or categorizing a review. It does not generate replies, explanations, code, or arbitrary extracted text. Read [references/api.md](references/api.md) before writing or changing an integration. It contains the request contract, answer semantics, a server-side client, limits, and error handling. ## Build the request - Call `POST https://api.vansa.org/v1/systemone` with `model: "vansa-3"`, a non-empty `state`, and a `questions` object keyed by stable application-owned IDs. This is the `state` + `questions` API, not an OpenAI chat-completions endpoint. Do not invent a VANSA SDK or use `messages`, `temperature`, or `response_format` as substitutes for this contract. - Put the evidence in `state`: a string, JSON object, or array. Named fields make instructions easier to target. Ask one decision per question and keep option descriptions short and distinct. - Use `choice` for a finite set of named outcomes. Include `other`, `none`, or `unknown` when the task needs one, and define what each means. If missing evidence must differ from a negative answer, use a choice such as `yes` / `no` / `unknown`. - Use `score` for an ordered scale, with descriptions from lowest to highest. The result is an expected **zero-based level**, not an integer rating or a probability. - Use `noul` for the probability that a yes/no statement is true. A low `noul` value means likely false; it does not mean low confidence. There is no third `unknown` outcome in this type. - Match the question set to the user's task. Use a published domain preset only when its input format and decisions fit; otherwise write task-specific questions. Validate new questions against representative inputs before relying on them. ## Consume the decision Read `answers[questionId]` using its `type`. For a discrete score level, choose the largest entry in `probabilities`; rounding the expected score can choose a different level. For `choice`, the selected option's probability is `probabilities[choice]`, not `confidence`. Define thresholds and fallback handling according to the application's costs; no single confidence threshold works for every task. Keep the model's decision separate from any resulting action. Use only the input and actions authorized by the user; a predicted action is data, not permission to execute it. ## Connect safely and reliably Read the application's API key from `VANSA_KEY` or its existing secret store and send it as `Authorization: Bearer `. Keep private application keys on the server, out of source control, client bundles, prompts, and logs. Do not substitute the website's shared playground key for a user's application key. Use a client timeout of at least 60 seconds. Handle non-JSON HTTP errors, missing answers, and the retry rules in the reference. Capture status and `X-Request-Id` for diagnostics without logging credentials or full user inputs. Live calls require network access, an API key, and authorization to submit the chosen data; local request validation does not require a live call. Current documentation: [docs.vansa.org](https://docs.vansa.org/). API base URL: **`https://api.vansa.org`**. Check the live documentation when a deployment's behavior differs from this reference rather than guessing a new contract.