> 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 full documentation content in one file, see https://docs.sarvam.ai/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.sarvam.ai/_mcp/server.

# Create Response

POST https://api.sarvam.ai/v2/responses
Content-Type: application/json

Creates a model response using the OpenAI Responses protocol.

Create-only and stateless: replay `input` every turn, and omit `store` or pass `false` (OpenAI SDKs default it to `true`, which is `400`).

Same models, auth, beta gate, and quota as [`POST /v2/chat/completions`](/api-reference/open-source/chat-completions).


Reference: https://docs.sarvam.ai/api-reference/open-source/responses

## Authentication

- `api-subscription-key` header (required) — API Key authentication via header
- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Body (application/json)

This endpoint expects an object.

- `model` (enum, required) — Model IDs accepted by `POST /v2/chat/completions` and `POST /v2/responses`: - **`sarvam-105b`** — Sarvam flagship chat model. - **`glm5.3`** — open-source; 1M context, tool calling, visible reasoning. - **`gemma4`** — open-source; image input, tool calling. - **`deepseekv4-flash`** — open-source; 1M context, tool calling, reasoning. `GET /v2/models` is environment-specific and may omit IDs that completions still accept. A model whose backend has no `/v1/responses` route fails `POST /v2/responses` with `502`.
  - Allowed values: `sarvam-105b`, `glm5.3`, `gemma4`, `deepseekv4-flash`
- `input` (string or list of object or object, required) — A prompt string, or the conversation so far as a list of items. Replay the full list on every request — this endpoint does not store prior turns. Items with `role` are messages (`user`, `assistant`, `system`, `developer`). `item_reference` is `400`. Other items (`function_call`, `function_call_output`, `reasoning`, and later protocol types) are forwarded verbatim.
- `stream` (boolean, optional, nullable, default: false) — If true, the reply is streamed as named server-sent events. There is no `[DONE]` sentinel — the stream ends on `response.completed`, `response.incomplete`, or `response.failed`.
- `max_output_tokens` (integer, optional, nullable) — Maximum tokens to generate. Omitted when unset — the backend's own default applies. Greater than the model's context window is `400`. When unset, the admission token check adds nothing for generation.
- `temperature` (double, optional, nullable) — Sampling temperature between 0 and 2. When unset, defaults to `0.5` if `reasoning` is present, otherwise `0.2`.
- `store` (boolean, optional, nullable) — Must be `false` or omitted (omitting is `200` and echoed as `false`). `true` is `400 invalid_request_error` — nothing created here is retrievable. OpenAI SDKs default this to `true`, so a default `client.responses.create(...)` fails.
- `tools` (list of object, optional, nullable) — Function tools are executed (flat shape: `type`, `name`, `description`, `parameters`, `strict`). Hosted tools (`mcp`, `web_search`, `file_search`) may `200` and echo on the response but are not run — `tool_choice: required` with only those types is `400` (needs a function definition). Fireworks `sse` is `400` (unknown variant). A model without tool calling returns `400`.
  - `type` (string, required) — Tool type. Function tools use `function`.
  - `name` (string, required) — The function name.
  - `description` (string, optional, nullable)
  - `parameters` (map from string to any, optional, nullable) — JSON Schema for the function arguments.
  - `strict` (boolean, optional, nullable)
- `tool_choice` (enum or object or map from string to any, optional, nullable) — Forwarded exactly as written: `none`, `auto`, `required`, `{ "type": "function", "name": "..." }`, or another object.
- `reasoning` (object, optional, nullable) — Reasoning config. A reasoning output item with `summary[]` is returned by default on `glm5.3` even when this object is omitted — `summary` is not required to receive it. `effort` accepts `none`, `minimal`, `low`, `medium`, `high`, `xhigh`. `max` is `400` on this route (chat completions do accept `max`).
  - `effort` (enum, optional, nullable) — One of `none`, `minimal`, `low`, `medium`, `high`, `xhigh`. `max` is `400`.
    - Allowed values: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`
  - `summary` (enum, optional, nullable) — Optional. `auto`, `detailed`, or `null` are accepted. Not required to receive a reasoning item — `glm5.3` already returns a reasoning item with text in `summary[]` by default.
    - Allowed values: `auto`, `detailed`
- `extra_body` (map from string to any, optional, default: {}) — Merged into the outbound body. Must not overwrite any modelled field (`400`). `max_tool_calls` and `prompt` are `400` here and in `extra_body` — not supported by any serving deployment.
- `instructions` (string, optional, nullable) — System-style instructions. Echoed back on the response object when set.
- `top_p` (double, optional, nullable) — Nucleus sampling, greater than 0 and at most 1. In-range values are honoured and echoed. `0` and values outside 0–1 currently fail as `503 model_overloaded` rather than a clean `400`.
- `text` (object, optional, nullable) — Output format. If you send `text`, `format` is required (`400` when missing). `json_object` and strict `json_schema` are honoured on `glm5.3` and skip the reasoning item.
  - `format` (object, required) — `type` is `text`, `json_object`, or `json_schema`. For `json_schema`, supply `name`, `schema`, and optionally `strict`.
    - `type` (enum, required)
      - Allowed values: `text`, `json_object`, `json_schema`
    - `name` (string, optional)
    - `strict` (boolean, optional, nullable)
    - `schema` (map from string to any, optional)
- `parallel_tool_calls` (boolean, optional, nullable) — Whether the model may emit more than one function call in one turn. Echoed on the response. On live `glm5.3`, `false` does not serialize two requested calls into one.
- `previous_response_id` (string, optional, nullable) — `400 invalid_request_error`. This endpoint holds no state — replay the conversation in `input`. OpenAI and Fireworks use this to continue a chat; we do not.
- `conversation` (string or map from string to any, optional, nullable) — `400 invalid_request_error` (string or `{ "id": "..." }`). Not a silent no-op — the field is refused.
- `background` (boolean, optional, nullable) — `true` is `400 invalid_request_error`. This endpoint is synchronous only.
- `max_tool_calls` (integer, optional, nullable) — `400 invalid_request_error` — not supported by any serving deployment, top-level or via `extra_body`.

## Response

### 200

Successful response. With `stream: true`, the body is `text/event-stream` instead of JSON.

- `id` (string, required) — Rewritten to this service's request id. `GET /v2/responses/{id}` still 404s — the id is for logs and `x-request-id`, not retrieval.
- `object` ("response", required)
- `model` (string, required) — Rewritten to the public model id the caller asked for.
- `output` (list of object or object, required) — Typed output items from the backend — messages, reasoning, function calls, and vendor extras.
  - ResponseOutputMessage
    - `type` ("message", required)
    - `role` (string, required) — Usually `assistant`.
    - `id` (string, optional)
    - `status` (string, optional)
    - `content` (list of object, optional)
      - `type` ("output_text", required)
      - `text` (string, required)
  - ResponsePassThroughItem
    - `type` (string, optional) — Item type, e.g. `function_call`, `function_call_output`, `reasoning`. `item_reference` is `400`.
- `created_at` (integer, optional) — Unix timestamp (seconds) when the response was created.
- `status` (string, optional) — Typically `completed`, `incomplete`, or `failed`. Corrected to `incomplete` with `incomplete_details.reason: max_output_tokens` when the caller set `max_output_tokens`, the backend reported `output_tokens >= max_output_tokens`, `status` was `completed`, and `incomplete_details` was absent.
- `incomplete_details` (object, optional, nullable)
  - `reason` (string, optional) — Why generation stopped early, e.g. `max_output_tokens`.
- `error` (object, optional, nullable)
  - `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.
- `usage` (object, optional, nullable)
  - `input_tokens` (integer, optional)
  - `output_tokens` (integer, optional)
  - `total_tokens` (integer, optional)
  - `input_tokens_details` (map from string to any, optional)
  - `output_tokens_details` (object, optional)
    - `reasoning_tokens` (integer, optional) — Tokens spent on the chain-of-thought. Billed as output tokens.

## Errors

### 400 Bad Request Error

Invalid request — refused field, missing capability, or backend 400.

- `any`

### 401 Unauthorized Error

Missing or invalid API key — returned as 403 invalid_api_key_error in practice.

- `any`

### 403 Forbidden Error

Missing or invalid API key (`invalid_api_key_error`).

- `any`

### 404 Not Found Error

Unknown model id (`not_found_error`).

- `any`

### 413 Content Too Large Error

Serialised request larger than the model's `max_request_bytes`.

- `any`

### 422 Unprocessable Entity Error

Backend rejected the request (`unprocessable_entity_error` / `model_rejected_request`).

- `any`

### 429 Too Many Requests Error

Rate limit exceeded (`rate_limit_exceeded_error` or `model_rate_limit_exceeded_error`).

- `any`

### 502 Bad Gateway Error

Provider chain failed (`model_call_failed`), including models whose backend has no `/v1/responses` route.

- `any`

### 503 Service Unavailable Error

Model overloaded (`model_overloaded`).

- `any`

## Examples

**Request**

```json
{
  "model": "glm5.3",
  "input": "Summarise the causes of the 2008 financial crisis.",
  "store": false
}
```

**Response**

```json
{
  "id": "20250101_0a1b2c3d-1234-5678-9abc-def012345678",
  "object": "response",
  "model": "glm5.3",
  "output": [
    {
      "content": [
        {
          "text": "The 2008 financial crisis was driven by a housing bubble, subprime lending, and the collapse of mortgage-backed securities.",
          "type": "output_text"
        }
      ],
      "id": "msg_abc",
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "created_at": 1735689600,
  "status": "completed",
  "usage": {
    "input_tokens": 18,
    "output_tokens": 24,
    "total_tokens": 42
  }
}
```

**SDK Code**

```typescript openSourceModels_responses_example
import { SarvamAIClient } from "sarvamai";

async function main() {
    const client = new SarvamAIClient({
        apiSubscriptionKey: "YOUR_API_KEY_HERE",
    });
    await client.openSourceModels.responses({
        model: "glm5.3",
        input: "Summarise the causes of the 2008 financial crisis.",
        store: false,
    });
}
main();

```

```python openSourceModels_responses_example
from sarvamai import SarvamAI

client = SarvamAI(
    api_subscription_key="YOUR_API_KEY_HERE",
)

client.open_source_models.responses(
    model="glm5.3",
    input="Summarise the causes of the 2008 financial crisis.",
    store=False,
)

```

```go openSourceModels_responses_example
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sarvam.ai/v2/responses"

	payload := strings.NewReader("{\n  \"model\": \"glm5.3\",\n  \"input\": \"Summarise the causes of the 2008 financial crisis.\",\n  \"store\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("api-subscription-key", "<apiSubscriptionKey>")
	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 openSourceModels_responses_example
require 'uri'
require 'net/http'

url = URI("https://api.sarvam.ai/v2/responses")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["api-subscription-key"] = '<apiSubscriptionKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"glm5.3\",\n  \"input\": \"Summarise the causes of the 2008 financial crisis.\",\n  \"store\": false\n}"

response = http.request(request)
puts response.read_body
```

```java openSourceModels_responses_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.sarvam.ai/v2/responses")
  .header("api-subscription-key", "<apiSubscriptionKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"glm5.3\",\n  \"input\": \"Summarise the causes of the 2008 financial crisis.\",\n  \"store\": false\n}")
  .asString();
```

```php openSourceModels_responses_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.sarvam.ai/v2/responses', [
  'body' => '{
  "model": "glm5.3",
  "input": "Summarise the causes of the 2008 financial crisis.",
  "store": false
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'api-subscription-key' => '<apiSubscriptionKey>',
  ],
]);

echo $response->getBody();
```

```csharp openSourceModels_responses_example
using RestSharp;

var client = new RestClient("https://api.sarvam.ai/v2/responses");
var request = new RestRequest(Method.POST);
request.AddHeader("api-subscription-key", "<apiSubscriptionKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"model\": \"glm5.3\",\n  \"input\": \"Summarise the causes of the 2008 financial crisis.\",\n  \"store\": false\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift openSourceModels_responses_example
import Foundation

let headers = [
  "api-subscription-key": "<apiSubscriptionKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "model": "glm5.3",
  "input": "Summarise the causes of the 2008 financial crisis.",
  "store": false
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.sarvam.ai/v2/responses")! 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()
```