> This page is for API Reference. > Sarvam Voice Agents (Samvaad) is a voice AI agent platform for Indian languages: build, test and deploy AI calling agents on your own phone numbers, from ₹3 a minute. Start here: https://docs.sarvam.ai/voice-agents/why-voice-agents. > For clean Markdown of any page, append `.md` to the page URL. > For a complete documentation index, see https://docs.sarvam.ai/llms.txt. For a section index, append `/llms.txt` to any section URL (for example https://docs.sarvam.ai/voice-agents/llms.txt). > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.sarvam.ai/_mcp/server. # Decide (Sarvam Prism) POST https://api.sarvam.ai/v2/systemone Content-Type: application/json Answers a set of typed questions about one input and returns a calibrated probability for every allowed option. The model does not generate text, so there is nothing to parse. The order of `choice` options does not affect the answer. Requires `api-subscription-key`, or `Authorization: Bearer `. **Question types:** `noul` (yes/no), `choice` (one of your options) and `score` (a level on your ordered scale). **Repeatability:** probabilities can vary slightly between identical requests; the top answer is stable. **Not supported:** images and streaming. Generation fields such as `temperature`, `max_tokens`, `stream` and `images` are refused: image URLs return `400`, and the others return `422`. Unknown keys inside a question also return `422`. **Limits:** 32,768 tokens per question (state + question + options), 2–255 options per `choice` and 2–10 levels per `score`. There is no cap on the number of questions. The state is not truncated, and if any one question breaks a limit the whole request fails with `422`. **Timeout:** each request must finish within 60 seconds. A longer request fails with `503 model_overloaded`; split very large batches across several requests before retrying. **Errors:** every error carries a `message`, a `code` and a `request_id`. Validation errors also carry `param`, the path to the field at fault, such as `questions.urgent.noul.instruction`. Reference: https://docs.sarvam.ai/api-reference/decisions/systemone ## Authentication - `api-subscription-key` header (required) — API Key authentication via header - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Body (application/json) This endpoint expects a SystemOneRequest. - `model` (string, required) — The decision model to use. Currently `sarvam-prism` (Sarvam Prism). - `state` (SystemOneRequestState, required) — The input to decide on: text, or an object or array that is rendered as compact JSON. Required; an empty string is allowed. It is never truncated: if any one question (state + question + options) exceeds 32,768 tokens the request fails with `422`. - `questions` (map from string to SystemOneQuestion, required) — Map of your question ID to a question, at least one. There is no cap on the number of questions. Every question is answered in one call, and the answer uses the same ID. ## Response ### 200 Successful Response - `model` (string, required) - `answers` (map from string to SystemOneAnswer, required) — One answer per question, keyed by your question ID. - `usage` (SystemOneUsage, required) ## Errors ### 400 Bad Request Error Invalid request (`invalid_request_error`): the body is not valid JSON, the body is not a JSON object, `model` is missing or not a string, or an image is sent as a URL. - `error` (V2ErrorObject, required) ### 402 Payment Required Error Payment Required — Insufficient credits to complete this operation (`insufficient_quota_error`). - `any` ### 403 Forbidden Error Missing or invalid API key (`invalid_api_key_error`). - `any` ### 404 Not Found Error Unknown model ID (`not_found_error`). Model IDs are case-sensitive. - `error` (V2ErrorObject, required) ### 422 Unprocessable Entity Error The request is invalid: a missing `state` or `questions`, an unsupported question `type` or key, options outside 2–255 or levels outside 2–10, a refused generation field, or a question over the 32,768-token limit (`unprocessable_entity_error`). `param` gives the path to the field at fault. - `error` (V2ErrorObject, required) ### 429 Too Many Requests Error Rate limit exceeded (`rate_limit_exceeded_error`): too many requests per minute, or the token budget is used up. Retry with backoff. - `any` ### 500 Internal Server Error An internal error occurred (`internal_server_error`). - `error` (V2ErrorObject, required) ### 502 Bad Gateway Error The model backend could not be reached (`model_call_failed`). Retry the request. - `any` ### 503 Service Unavailable Error Model overloaded or starting up, or the request took longer than 60 seconds (`model_overloaded`). Retry with backoff; for a large request, split the questions across smaller requests first. - `any` ## Types ### SystemOneRequestState The input to decide on: text, or an object or array that is rendered as compact JSON. Required; an empty string is allowed. It is never truncated: if any one question (state + question + options) exceeds 32,768 tokens the request fails with `422`. - string - map from string to any - list of any ### SystemOneQuestion - `type`: `noul` (SystemOneNoulQuestion) - `criteria` (SystemOneQuestionDiscriminatorMappingNoulCriteria, optional) — Optional descriptions of when the answer is yes (`true`) and no (`false`). Only the keys `true` and `false` are accepted. - `instructions` (SystemOneQuestionDiscriminatorMappingNoulInstructions, optional) — The yes/no question to ask about `state`. A string, or an object or array that is rendered as compact JSON. Send `instructions`, `criteria`, or both. - `type`: `choice` (SystemOneChoiceQuestion) - `criteria` (map from string to string, required) — Map of option ID to a description of when that option applies. 2 to 255 options. The option IDs are returned verbatim as the keys of `probabilities`. A description that is `null` or empty is shown to the model as the bare ID. - `instructions` (SystemOneQuestionDiscriminatorMappingChoiceInstructions, optional) — The question to ask about `state`. A string, or an object or array that is rendered as compact JSON. Optional for `choice` and `score`, where the options alone can carry the question. - `type`: `score` (SystemOneScoreQuestion) - `criteria` (list of string, required) — The level descriptions, lowest first, 2 to 10 levels. Levels are keyed `"0"`, `"1"`, … in the answer, in the order you sent them. - `instructions` (SystemOneQuestionDiscriminatorMappingScoreInstructions, optional) — The question to ask about `state`. A string, or an object or array that is rendered as compact JSON. Optional for `choice` and `score`, where the options alone can carry the question. ### SystemOneAnswer - `type`: `noul` (SystemOneNoulAnswer) - `noul` (double, required) — Probability that the answer is yes, from 0 to 1. - `type`: `choice` (SystemOneChoiceAnswer) - `choice` (string, required) — The option ID with the highest probability. - `confidence` (double, required) — How decisive the answer is, from 0 to 1: the top option's probability rescaled so that an even split across all options is 0 and certainty is 1, `(p_top − 1/n) / (1 − 1/n)`. Use `probabilities[choice]` for the probability itself. - `probabilities` (map from string to double, required) — Probability for every option, keyed by option ID. Sums to 1. - `type`: `score` (SystemOneScoreAnswer) - `confidence` (double, required) — How decisive the rating is, from 0 (spread across the scale) to 1 (all probability on one level). - `legend` (map from string to string, required) — Your level descriptions, keyed `"0"`, `"1"`, … the same way as `probabilities`. - `probabilities` (map from string to double, required) — Probability for every level, keyed `"0"`, `"1"`, … in your order. Sums to 1. - `score` (double, required) — Expected level: the sum of level index (0-based, lowest first) × probability. A float, for example `3.83`. ### SystemOneUsage - `input_tokens` (integer, required) — Prompt tokens for the request. The state is counted once, however many questions you ask; each question adds its own instructions and options. - `output_tokens` (integer, required) — Always `0`: the model returns probabilities, not text. ### V2ErrorObject - `message` (string, optional) - `code` (string, optional) — Machine-readable code, e.g. `invalid_request_error`, `not_found_error`. - `request_id` (string, optional) - `param` (string, optional, nullable) — Present when a field was named. - `spend_limits` (map from string to any, optional, nullable) — Present only on a 429 from an exhausted seat budget. ### SystemOneQuestionDiscriminatorMappingNoulCriteria Optional descriptions of when the answer is yes (`true`) and no (`false`). Only the keys `true` and `false` are accepted. - `true` (string, optional) - `false` (string, optional) ### SystemOneQuestionDiscriminatorMappingNoulInstructions The yes/no question to ask about `state`. A string, or an object or array that is rendered as compact JSON. Send `instructions`, `criteria`, or both. - string - map from string to any - list of any ### SystemOneQuestionDiscriminatorMappingChoiceInstructions The question to ask about `state`. A string, or an object or array that is rendered as compact JSON. Optional for `choice` and `score`, where the options alone can carry the question. - string - map from string to any - list of any ### SystemOneQuestionDiscriminatorMappingScoreInstructions The question to ask about `state`. A string, or an object or array that is rendered as compact JSON. Optional for `choice` and `score`, where the options alone can carry the question. - string - map from string to any - list of any ## Examples **Request** ```json { "model": "sarvam-prism", "state": "My Stripe integration stopped working and all checkout payments are failing.", "questions": { "department": { "type": "choice", "criteria": { "billing": "Payments or invoices", "sales": "New business enquiries", "technical": "Bugs or outages" }, "instructions": "Which team should handle this?" }, "severity": { "type": "score", "criteria": [ "trivial", "minor", "moderate", "major", "critical" ], "instructions": "Rate the severity." }, "urgent": { "type": "noul", "instructions": "Is this urgent and revenue-impacting?" } } } ``` **Response** ```json { "model": "sarvam-prism", "answers": { "department": { "type": "choice", "choice": "billing", "confidence": 0.7065, "probabilities": { "billing": 0.8044, "sales": 0.0087, "technical": 0.1869 } }, "severity": { "type": "score", "confidence": 0.916, "legend": { "0": "trivial", "1": "minor", "2": "moderate", "3": "major", "4": "critical" }, "probabilities": { "0": 0.0026, "1": 0.0033, "2": 0.0115, "3": 0.1245, "4": 0.8581 }, "score": 3.8321 }, "urgent": { "type": "noul", "noul": 0.9782 } }, "usage": { "input_tokens": 153, "output_tokens": 0 } } ``` **SDK Code** ```python decisions_create_example import requests url = "https://api.sarvam.ai/v2/systemone" payload = { "model": "sarvam-prism", "state": "My Stripe integration stopped working and all checkout payments are failing.", "questions": { "department": { "type": "choice", "criteria": { "billing": "Payments or invoices", "sales": "New business enquiries", "technical": "Bugs or outages" }, "instructions": "Which team should handle this?" }, "severity": { "type": "score", "criteria": ["trivial", "minor", "moderate", "major", "critical"], "instructions": "Rate the severity." }, "urgent": { "type": "noul", "instructions": "Is this urgent and revenue-impacting?" } } } headers = { "api-subscription-key": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript decisions_create_example const url = 'https://api.sarvam.ai/v2/systemone'; const options = { method: 'POST', headers: { 'api-subscription-key': '', 'Content-Type': 'application/json' }, body: '{"model":"sarvam-prism","state":"My Stripe integration stopped working and all checkout payments are failing.","questions":{"department":{"type":"choice","criteria":{"billing":"Payments or invoices","sales":"New business enquiries","technical":"Bugs or outages"},"instructions":"Which team should handle this?"},"severity":{"type":"score","criteria":["trivial","minor","moderate","major","critical"],"instructions":"Rate the severity."},"urgent":{"type":"noul","instructions":"Is this urgent and revenue-impacting?"}}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go decisions_create_example package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.sarvam.ai/v2/systemone" payload := strings.NewReader("{\n \"model\": \"sarvam-prism\",\n \"state\": \"My Stripe integration stopped working and all checkout payments are failing.\",\n \"questions\": {\n \"department\": {\n \"type\": \"choice\",\n \"criteria\": {\n \"billing\": \"Payments or invoices\",\n \"sales\": \"New business enquiries\",\n \"technical\": \"Bugs or outages\"\n },\n \"instructions\": \"Which team should handle this?\"\n },\n \"severity\": {\n \"type\": \"score\",\n \"criteria\": [\n \"trivial\",\n \"minor\",\n \"moderate\",\n \"major\",\n \"critical\"\n ],\n \"instructions\": \"Rate the severity.\"\n },\n \"urgent\": {\n \"type\": \"noul\",\n \"instructions\": \"Is this urgent and revenue-impacting?\"\n }\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("api-subscription-key", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby decisions_create_example require 'uri' require 'net/http' url = URI("https://api.sarvam.ai/v2/systemone") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["api-subscription-key"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"model\": \"sarvam-prism\",\n \"state\": \"My Stripe integration stopped working and all checkout payments are failing.\",\n \"questions\": {\n \"department\": {\n \"type\": \"choice\",\n \"criteria\": {\n \"billing\": \"Payments or invoices\",\n \"sales\": \"New business enquiries\",\n \"technical\": \"Bugs or outages\"\n },\n \"instructions\": \"Which team should handle this?\"\n },\n \"severity\": {\n \"type\": \"score\",\n \"criteria\": [\n \"trivial\",\n \"minor\",\n \"moderate\",\n \"major\",\n \"critical\"\n ],\n \"instructions\": \"Rate the severity.\"\n },\n \"urgent\": {\n \"type\": \"noul\",\n \"instructions\": \"Is this urgent and revenue-impacting?\"\n }\n }\n}" response = http.request(request) puts response.read_body ``` ```java decisions_create_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.sarvam.ai/v2/systemone") .header("api-subscription-key", "") .header("Content-Type", "application/json") .body("{\n \"model\": \"sarvam-prism\",\n \"state\": \"My Stripe integration stopped working and all checkout payments are failing.\",\n \"questions\": {\n \"department\": {\n \"type\": \"choice\",\n \"criteria\": {\n \"billing\": \"Payments or invoices\",\n \"sales\": \"New business enquiries\",\n \"technical\": \"Bugs or outages\"\n },\n \"instructions\": \"Which team should handle this?\"\n },\n \"severity\": {\n \"type\": \"score\",\n \"criteria\": [\n \"trivial\",\n \"minor\",\n \"moderate\",\n \"major\",\n \"critical\"\n ],\n \"instructions\": \"Rate the severity.\"\n },\n \"urgent\": {\n \"type\": \"noul\",\n \"instructions\": \"Is this urgent and revenue-impacting?\"\n }\n }\n}") .asString(); ``` ```php decisions_create_example request('POST', 'https://api.sarvam.ai/v2/systemone', [ 'body' => '{ "model": "sarvam-prism", "state": "My Stripe integration stopped working and all checkout payments are failing.", "questions": { "department": { "type": "choice", "criteria": { "billing": "Payments or invoices", "sales": "New business enquiries", "technical": "Bugs or outages" }, "instructions": "Which team should handle this?" }, "severity": { "type": "score", "criteria": [ "trivial", "minor", "moderate", "major", "critical" ], "instructions": "Rate the severity." }, "urgent": { "type": "noul", "instructions": "Is this urgent and revenue-impacting?" } } }', 'headers' => [ 'Content-Type' => 'application/json', 'api-subscription-key' => '', ], ]); echo $response->getBody(); ``` ```csharp decisions_create_example using RestSharp; var client = new RestClient("https://api.sarvam.ai/v2/systemone"); var request = new RestRequest(Method.POST); request.AddHeader("api-subscription-key", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"model\": \"sarvam-prism\",\n \"state\": \"My Stripe integration stopped working and all checkout payments are failing.\",\n \"questions\": {\n \"department\": {\n \"type\": \"choice\",\n \"criteria\": {\n \"billing\": \"Payments or invoices\",\n \"sales\": \"New business enquiries\",\n \"technical\": \"Bugs or outages\"\n },\n \"instructions\": \"Which team should handle this?\"\n },\n \"severity\": {\n \"type\": \"score\",\n \"criteria\": [\n \"trivial\",\n \"minor\",\n \"moderate\",\n \"major\",\n \"critical\"\n ],\n \"instructions\": \"Rate the severity.\"\n },\n \"urgent\": {\n \"type\": \"noul\",\n \"instructions\": \"Is this urgent and revenue-impacting?\"\n }\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift decisions_create_example import Foundation let headers = [ "api-subscription-key": "", "Content-Type": "application/json" ] let parameters = [ "model": "sarvam-prism", "state": "My Stripe integration stopped working and all checkout payments are failing.", "questions": [ "department": [ "type": "choice", "criteria": [ "billing": "Payments or invoices", "sales": "New business enquiries", "technical": "Bugs or outages" ], "instructions": "Which team should handle this?" ], "severity": [ "type": "score", "criteria": ["trivial", "minor", "moderate", "major", "critical"], "instructions": "Rate the severity." ], "urgent": [ "type": "noul", "instructions": "Is this urgent and revenue-impacting?" ] ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.sarvam.ai/v2/systemone")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```