> ## Documentation Index
> Fetch the complete documentation index at: https://docs.karta.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Responses

> Drive a Karta agent with the OpenAI Responses API shape, including previous_response_id continuation.

`POST /{org}/{agent}/v1/responses`

Speaks the OpenAI **Responses API** shape. Auth: a
[session token](/security/session-tokens) or a `kt_live_...` key.

## Request

<ParamField body="input" type="string | array" required>
  The user input - a string, or an array of input items.
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  `true` -> SSE; `false` -> a single response object.
</ParamField>

<ParamField body="previous_response_id" type="string">
  Continue from a prior response - the Responses-style way to keep context
  across turns. Maps to the underlying Karta session.
</ParamField>

<ParamField body="store" type="boolean">
  Whether to pin/persist the session.
</ParamField>

<ParamField body="model" type="string">
  Accepted for OpenAI-client compatibility but has no effect: it does not select
  the model. The model is configured per agent and org on the platform.
</ParamField>

## Unary response

```bash theme={null}
curl https://agent.karta.sh/my-org/my-app/v1/responses \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input": "What roasts do you have?"}'
```

```json theme={null}
{
  "id": "resp_4b2c...",
  "object": "response",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        { "type": "output_text", "text": "We've got Sunrise, Midnight, and Decaf Dusk. " }
      ]
    }
  ],
  "output_text": "We've got Sunrise, Midnight, and Decaf Dusk. ",
  "usage": { "input_tokens": 42, "output_tokens": 28, "total_tokens": 70 }
}
```

`output` is an array of message items; `output_text` is the text output
flattened for convenience. Pass the returned `id` as `previous_response_id` on
the next call to continue the conversation - a response echoes
`previous_response_id` only when the request supplied one.

## Streaming

```bash theme={null}
curl -N https://agent.karta.sh/my-org/my-app/v1/responses \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input": "What roasts do you have?", "stream": true}'
```

```text theme={null}
event: response.created
data: { "type": "response.created", "response": { "id": "resp_4b2c...", "status": "in_progress" } }

event: response.output_text.delta
data: { "type": "response.output_text.delta", "response_id": "resp_4b2c...", "delta": "We've got " }

event: response.output_text.delta
data: { "type": "response.output_text.delta", "response_id": "resp_4b2c...", "delta": "Sunrise, Midnight, ..." }

event: response.completed
data: { "type": "response.completed", "response": { "id": "resp_4b2c...", "status": "completed", "output_text": "...", "usage": { ... } } }
```

A failure mid-stream arrives as `response.failed`.

## Status codes

`200` (unary or stream), `401`, `402` (budget or instance cap), `403`
(`identity_mismatch`), `404` (unknown agent / cross-tenant / no active release),
`409` (release not materialized), `422` (BYOK rejected). See
[Errors](/api-reference/errors).