# Responses API

Use KosCompute's stateless OpenAI Responses-compatible endpoint.

`POST /v1/responses` accepts Responses-style input and returns Responses objects or canonical Responses SSE events. It uses KosCompute-hosted models and shares the router's admission, accounting, and Zero Data Retention behavior.

```bash
curl https://api.koscompute.com/v1/responses \
  -H "Authorization: Bearer $KOSCOMPUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen/qwen3.8-27b",
    "input": "Explain idempotency keys in two bullets.",
    "max_output_tokens": 220
  }'
```

## Input

`input` may be a string or an array of typed items. Supported items include message text, `function_call`, and `function_call_output`. Message content accepts strings or typed `input_text` and `output_text` parts. Media content is not enabled on this endpoint; use Chat Completions for vision.

## Stateless behavior

KosCompute does not retain Responses. `store:true` and a non-null `previous_response_id` return `400 unsupported_parameter`. Resend the conversation state required for the next turn. `prompt_cache_key`, hosted conversations, background mode, and hosted OpenAI tools are not advertised.

## Tools and structured text

Only local `function` tools are supported. Tool names and JSON Schemas are validated. `tool_choice` accepts `none`, `auto`, `required`, or a named function. A returned function call has a `call_id`; send a later `function_call_output` with that same ID.

Use `text.format.type:"json_object"` or `json_schema` on a model that advertises the matching feature. Hosted search, file, computer, image, and other provider tools are rejected rather than silently ignored.

## Reasoning

Use the `reasoning` object with supported fields such as `effort`, `max_tokens`, `enabled`, and `exclude`. Public reasoning text and summaries are not exposed; usage can include a reasoning-token count. The total `max_output_tokens` budget still includes reasoning.

## Streaming lifecycle

With `stream:true`, the normal lifecycle begins with `response.created` and `response.in_progress`, followed by output item/content delta events, and ends with `response.completed`. Tool arguments use function-call delta events. A failure after headers have been sent appears as a terminal stream error rather than a replacement HTTP status.