> Keiro Labs API documentation - Responses
> Page: https://docs.keirolabs.ai/responses.html
> Markdown: https://docs.keirolabs.ai/responses.md
> Agent index: https://docs.keirolabs.ai/llms.txt
> API base URL: https://api.keirolabs.ai/v1
> Auth: send "Authorization: Bearer <api-key>" with a key created in the
> Keiro console (https://console.keirolabs.ai/api-keys). Use credentials saved by
> `keiro setup`, or resolve the key from a secret manager or an owner-only
> secret file and pass it to the client explicitly. Never read another
> provider's variable, and never put raw key material in environment
> variables, code, docs, or logs.

# Responses API

Use `POST /v1/responses` for typed input and output items, function-call
continuations, and the newest OpenAI-compatible response shape.

## Request

For a single text turn, `input` can be a string:

```json
{
  "model": "eb1-preview",
  "input": "Explain token buckets in one sentence."
}
```

For multimodal or multi-turn work, send an array of typed message, text, image,
function-call, and function-output items. Put stable application instructions
in `instructions`.

**Send a Responses request**

_Python_

```python
from getpass import getpass

from openai import OpenAI

client = OpenAI(
    base_url="https://api.keirolabs.ai/v1",
    api_key=getpass("Keiro API key: "),
)

response = client.responses.create(
    model="eb1-preview",
    input="Give three practical uses for structured outputs.",
)

print(response.output_text)
```

_JavaScript_

```javascript
import fs from "node:fs";
import OpenAI from "openai";

const keyPath = process.env.KEIRO_KEY_FILE;
if (!keyPath) {
  throw new Error("KEIRO_KEY_FILE must point to a protected secret file");
}

const client = new OpenAI({
  baseURL: "https://api.keirolabs.ai/v1",
  apiKey: fs.readFileSync(keyPath, "utf8").trim(),
});

const response = await client.responses.create({
  model: "eb1-preview",
  input: "Give three practical uses for structured outputs.",
});

console.log(response.output_text);
```

_curl_

```bash
printf 'Keiro API key: '
IFS= read -rs KEIRO_BEARER
printf '\n'

curl -sS https://api.keirolabs.ai/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "eb1-preview",
    "input": "Give three practical uses for structured outputs."
  }' \
  -H @- <<<"Authorization: Bearer $KEIRO_BEARER"
```

## Response

OpenAI-compatible SDKs expose `response.output_text` as a convenience. In raw
JSON, inspect `output` in order and read assistant `output_text` content parts.
The same array can contain function-call and other structured output items.

For tool continuation, resend the complete conversation items, including the
model's `function_call` and your matching `function_call_output`. Stateful
`previous_response_id` continuation is not a portable public eb1 contract.

## Supported controls

The current Responses surface supports documented input and instructions plus
controls including metadata, text response format, function tools and tool
choice, parallel tool calls, streaming, maximum output tokens, sampling and
stop controls, reasoning, user attribution, include controls, service tier,
prompt-cache key, truncation, and idempotency.

Strict validation rejects unknown fields. JSON mode and JSON Schema structured
output are not currently supported.

## Streaming

Set `stream` to `true` to receive typed server-sent events. Assemble text from
`response.output_text.delta`, process structured items by their output index,
and finish only after `response.completed` or `response.incomplete`.

The request's `reasoning` effort also selects the stream's documented time
entitlement — how long a run may take before it is stopped with a truthful
`response.incomplete`. See
[Streaming](streaming.md#stream-lifetime-and-time-entitlements) for the
per-effort table, and [Streaming](streaming.md) for the event taxonomy and
in-band errors.

**Stream a Responses request**

_Python_

```python
from getpass import getpass

from openai import OpenAI

client = OpenAI(
    base_url="https://api.keirolabs.ai/v1",
    api_key=getpass("Keiro API key: "),
)

stream = client.responses.create(
    model="eb1-preview",
    input="Write a short haiku about reliable APIs.",
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
```

_JavaScript_

```javascript
import fs from "node:fs";
import OpenAI from "openai";

const keyPath = process.env.KEIRO_KEY_FILE;
if (!keyPath) {
  throw new Error("KEIRO_KEY_FILE must point to a protected secret file");
}

const client = new OpenAI({
  baseURL: "https://api.keirolabs.ai/v1",
  apiKey: fs.readFileSync(keyPath, "utf8").trim(),
});

const stream = await client.responses.create({
  model: "eb1-preview",
  input: "Write a short haiku about reliable APIs.",
  stream: true,
});

for await (const event of stream) {
  if (event.type === "response.output_text.delta") {
    process.stdout.write(event.delta);
  }
}
```

_curl_

```bash
printf 'Keiro API key: '
IFS= read -rs KEIRO_BEARER
printf '\n'

curl -sS -N https://api.keirolabs.ai/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "eb1-preview",
    "input": "Write a short haiku about reliable APIs.",
    "stream": true
  }' \
  -H @- <<<"Authorization: Bearer $KEIRO_BEARER"
```

## Tools and images

- Responses function tools use flat `name` and `parameters` fields and return
  `function_call` output items; see [Tool calling](tool-calling.md).
- Images use `input_image` parts; see [Images and vision](images-vision.md).

## Related pages

- [API reference](api-reference.md)
- [Chat Completions](chat-completions.md)
- [Messages](messages.md)
- [Idempotency](idempotency.md)