Responses API

IronClaw exposes an OpenAI-compatible Responses API. Unlike a raw LLM passthrough, requests route through the full agent loop, so callers get tools, memory, safety, and server-side conversation state via a standard wire format.

POST /api/v1/responses
GET  /api/v1/responses/{id}

The legacy /v1/responses path is still accepted as an alias for clients pinned to it.

When to use this vs. the Chat Completions proxy

Endpoint	Behavior
`/api/v1/responses`	Routes through the agent. The model can call IronClaw tools (file, web, memory, MCP, extensions), retain conversation state via `previous_response_id`, and pause for caller-supplied tools.
`/v1/chat/completions`	Raw LLM proxy. No tools, no memory, no agent loop. Use it when you only need a model call.

If you want IronClaw’s capabilities behind an OpenAI-shaped wire contract, this is the endpoint.

Authentication

Every protected route requires a bearer token in the Authorization header:

Authorization: Bearer <token>

You have two options:

Instance token (single-user)
Per-user tokens (multi-user)

The bearer token provisioned during onboarding authenticates both the web interface and this API. It is written to webui-token in your IronClaw home:

cat ~/.ironclaw/reborn/webui-token

Supply your own instead by setting IRONCLAW_REBORN_WEBUI_TOKEN before starting serve.

export IRONCLAW_REBORN_WEBUI_TOKEN="your-secure-token"

This token carries operator privileges, including configuration changes. For anything beyond a single-user instance, use per-user tokens instead.

In a multi-user deployment, an admin creates each user through the admin surface, which mints that user’s API bearer exactly once:

curl -X POST https://your-host/api/webchat/v2/admin/users \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"alice@example.com","display_name":"Alice","role":"member"}'

role is required — one of owner, admin, or member. owner and admin clear the admin authorization boundary; member does not. email and display_name are optional.The token is top-level; the user’s identity is nested under user:

{
  "user": {
    "user_id": "...",
    "email": "alice@example.com",
    "status": "active",
    "role": "member",
    "created_at": "2026-07-27T18:00:00Z",
    "updated_at": "2026-07-27T18:00:00Z"
  },
  "api_token": "<shown ONCE>"
}

Store the api_token when it is returned; it cannot be retrieved again. These tokens are scoped to one user and carry user identity only — they do not inherit operator configuration privileges.Users signed in through Google or GitHub SSO receive an equivalent session bearer. See Web Interface.

A missing or wrong token returns 401. Chat send endpoints (including this one) are rate-limited to 30 requests per 60 seconds per user.

Quickstart

The simplest request, with no session state and no tools:

curl -X POST https://your-host/api/v1/responses \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "What time is it?"
  }'

Response:

{
  "id": "resp_<64hex>",
  "object": "response",
  "created_at": 1715846400,
  "model": "default",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "id": "item_...",
      "role": "assistant",
      "content": [
        { "type": "output_text", "text": "It is 14:23 UTC." }
      ]
    }
  ],
  "usage": { "input_tokens": 42, "output_tokens": 11, "total_tokens": 53 }
}

The OpenAI Python and TypeScript SDKs work as-is. Point base_url at https://your-host/api/v1 (or /v1 for the alias).

from openai import OpenAI

client = OpenAI(base_url="https://your-host/api/v1", api_key=TOKEN)
resp = client.responses.create(input="What time is it?")
print(resp.output_text)

Request fields

{
  "input": "...",
  "model": "default",
  "instructions": null,
  "previous_response_id": null,
  "stream": false,
  "tools": null,
  "x_context": null
}

Field	Required	Description
`input`	yes	A string, or an array of `message` / `function_call_output` items. See External tools for the array form.
`model`	no	Must be `"default"`. Per-request model override is not yet supported; configure providers via settings.
`instructions`	no	System/developer instructions. Injected ahead of `input` as an `<instructions>` block and stored as part of the persisted user message. See Per-request instructions for the IronClaw-specific replay caveat.
`previous_response_id`	no	The `id` from a prior response. Resumes the same thread; see Session continuity.
`stream`	no	`true` for SSE; `false` (default) for a single JSON response.
`tools`	no	Caller-supplied function tools. See External tools.
`x_context`	no	IronClaw extension. Structured JSON context (≤ 10 KB) prepended as `<user-context>`. The alias `context` is also accepted but may collide with future OpenAI fields. Prefer `x_context`.

These fields are rejected with 400 so callers know they were ignored rather than silently dropped:

tool_choice (no per-request tool surface to enforce against)
temperature (configure via settings)
max_output_tokens (not yet wired)
Any model other than "default"

Session continuity

Each response embeds its thread UUID in the id. Pass the previous id back as previous_response_id to continue the same conversation:

{
  "input": "What did I just ask?",
  "previous_response_id": "resp_abc...xyz"
}

IronClaw replays the thread’s history from the conversation store and runs the new turn against it. There is no client-side state to manage. Threads are user-scoped, so a token belonging to a different user cannot resume someone else’s thread (the lookup returns 404). Each POST mints a fresh response_uuid, so two turns on the same thread produce different ids.

Retrieving a past response

curl https://your-host/api/v1/responses/$ID \
  -H "Authorization: Bearer $TOKEN"

Returns the output items reconstructed from the stored conversation. Token usage is not retained per-message; the usage field on a retrieved response is zero.

Streaming

Set "stream": true to receive Server-Sent Events:

curl -N -X POST https://your-host/api/v1/responses \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input":"Summarize the news.","stream":true}'

Events follow the OpenAI Responses streaming format. The SSE event: field matches the JSON type:

`event:`	`type`	Payload
`response.created`	`response.created`	Initial in-progress shell.
`response.output_item.added`	`response.output_item.added`	A new `message` or `function_call` item began.
`response.output_text.delta`	`response.output_text.delta`	Token delta inside an `output_text` content block.
`response.output_item.done`	`response.output_item.done`	An item is finalised.
`response.completed`	`response.completed`	Terminal success.
`response.failed`	`response.failed`	Terminal failure (turn-level error).

A keepalive frame fires every 15 seconds to prevent intermediate proxies from closing idle connections. The non-streaming path has a 120-second turn timeout. Long-running tool work (sandbox jobs, multi-step agentic flows) should use stream: true so the connection stays responsive.

External tools

You can register your own function tools per request. The agent treats them as first-class actions alongside built-in tools and pauses execution when it wants to call one. Your client executes the call and feeds the result back on the next request. This is a function-calling round-trip, not a prompt-level convention. The wire shape matches the OpenAI Responses API spec.

Define tools

{
  "input": "What is the weather in NYC?",
  "tools": [
    {
      "type": "function",
      "name": "lookup_weather",
      "description": "Return the current weather for a city.",
      "parameters": {
        "type": "object",
        "properties": {
          "city": { "type": "string", "description": "City name" }
        },
        "required": ["city"]
      }
    }
  ]
}

Constraints (validated up-front, 400 on violation):

Only type: "function" is accepted. web_search, file_search, code_interpreter, etc. are rejected. IronClaw routes those through its own registry, not caller-provided definitions.
Names: ^[A-Za-z0-9_-]{1,64}$, unique within the request.
Names must not shadow a registered IronClaw action (built-in tool, extension tool, or an agent capability like mission_*, skill_*, memory_*). Shadowing is rejected to prevent confused-deputy behavior.
The entire tools[] payload caps at 16 KiB of canonical JSON.

The round trip

When the model calls one of your tools, the response completes with a function_call output item and the thread sits in Waiting:

{
  "id": "resp_...",
  "status": "completed",
  "output": [
    {
      "type": "function_call",
      "id": "item_...",
      "call_id": "call_ext_lookup_1",
      "name": "lookup_weather",
      "arguments": "{\"city\":\"NYC\"}"
    }
  ]
}

The model may emit prose before the call. Any pre-call text is flushed as a leading message item so you see both pieces in order. Execute the call locally, then POST a follow-up with a function_call_output item. Include previous_response_id so the resume targets the same thread:

{
  "previous_response_id": "resp_...",
  "input": [
    {
      "type": "function_call_output",
      "call_id": "call_ext_lookup_1",
      "output": "{\"temp_f\":72,\"conditions\":\"sunny\"}"
    }
  ],
  "tools": [ /* same tools array */ ]
}

The agent resumes, the LLM sees your tool result, and the final answer comes back as a normal message output item. Pass the same tools[] on the resume request. The catalog is per-thread; passing the definitions keeps the tool available for any follow-up calls the model makes.

Resume validation

The resume request must satisfy the bridge:

A function_call_output item without a live external-tool gate on this thread returns 400.
A function_call_output item whose call_id does not match the pending gate returns 400.
A function_call_output item with an empty call_id or missing output returns 400.
If the thread is paused on an unrelated gate (OAuth, approval, pairing), resolve that first.

You can interleave a fresh user message with the tool output by adding a message item. Both will be visible to the agent:

{
  "input": [
    { "type": "function_call_output", "call_id": "...", "output": "..." },
    { "type": "message", "role": "user", "content": "Also, what about tomorrow?" }
  ]
}

Multi-call batching

The engine pauses on the first external tool call in an assistant turn. If the model wants to invoke tool_a and tool_b together, only tool_a surfaces on the first response. After you resume, tool_b is emitted on the next turn. This is a known limitation; OpenAI-style “post all results together” is a follow-up.

Streaming flow

With stream: true, the external-tool flow looks like:

response.created
Optional response.output_text.delta events for any leading prose.
response.output_item.added with the function_call item.
response.output_item.done with the same item.
response.completed.

The stream closes after response.completed. Send the resume as a fresh POST with previous_response_id.

Structured context (`x_context`)

For integrations that need to pass structured state alongside the user message (notification approval, webhook payload, environment hints), use x_context:

{
  "input": "Process the latest webhook.",
  "x_context": {
    "webhook": { "source": "stripe", "event": "invoice.paid", "amount_cents": 4200 }
  }
}

The handler renders it as a <user-context> block ahead of the user message. Total serialized size caps at 10 KB. Pass a flat {key: {object}} structure; deeper nesting is serialized as raw JSON. x_context is an IronClaw extension and is not part of the OpenAI Responses API spec.

Per-request instructions

Use instructions to inject a one-turn system/developer message:

{
  "input": "Summarize this.",
  "instructions": "Respond in three bullet points, no preamble."
}

IronClaw caveat — diverges from the OpenAI spec. The OpenAI Responses API contract is that instructions apply only to the current turn and are not carried by previous_response_id. IronClaw currently prepends the <instructions> block into the user message and persists it as part of the conversation, so it is visible on later turns when history is replayed. Until the handler stores instructions out-of-band, treat them as sticky for the thread and re-send (or override) them explicitly on each turn that needs different behaviour. The agent’s persistent identity files (AGENTS.md, SOUL.md, USER.md, IDENTITY.md) come from workspace memory and are not affected by this field.

Errors

Errors from the Responses handler use the OpenAI envelope:

{
  "error": {
    "message": "function_call_output items must include a non-empty `call_id` field",
    "type": "invalid_request_error",
    "code": null
  }
}

Common codes:

Status	`type`	When
`400`	`invalid_request_error`	Schema, validation, shadowed tool name, missing pending gate, unsupported field.
`429`	`rate_limit_error`	More than 30 requests in 60 seconds for this user.
`503`	`server_error`	Agent loop not started, database unavailable, or connection cap reached.

A turn that completes but fails mid-flight (the model errored, a required tool raised) returns 200 with "status": "failed" and a populated error field. Inspect status before reading output. Two cases do not use the JSON envelope and need separate handling:

401 Unauthorized comes from the gateway auth middleware before the request reaches the handler, and the body is a plain-text string (Invalid or missing auth token). Same for 403 (Forbidden for OIDC domain violations) and the 503 (Database unavailable) emitted by the middleware when the token store is down.
GET /api/v1/responses/{id} returns 404 (still JSON-enveloped) when the response id is unknown or the thread does not belong to the authenticated user. POST with a foreign previous_response_id does not return 404; the handler only decodes the UUID and dispatches into the agent, where the cross-user resume surfaces as a turn-level failure rather than an HTTP error. Treat cross-user resume as undefined and avoid relying on the response shape.

The Responses API does not support interactive approvals or authentication gates in the response stream. If the agent hits a tool that requires user approval (e.g. shell with a destructive command) or an extension OAuth flow, the turn fails with a clear error directing you to resolve the gate via the web UI or a different channel.

SDK usage

The OpenAI SDKs are the easiest way to use this endpoint. Point them at IronClaw and they “just work”:

from openai import OpenAI

client = OpenAI(
    base_url="https://your-host/api/v1",
    api_key="<your-bearer-token>",
)

# Basic
resp = client.responses.create(input="Hello.")
print(resp.output_text)

# With session continuity
follow_up = client.responses.create(
    input="What did I just say?",
    previous_response_id=resp.id,
)

# With caller tools
import json

resp = client.responses.create(
    input="What is the weather in NYC?",
    tools=[
        {
            "type": "function",
            "name": "lookup_weather",
            "description": "Return current weather.",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        }
    ],
)

# Inspect the function_call item, run it locally, resume.
call = next(item for item in resp.output if item.type == "function_call")
result = {"temp_f": 72, "conditions": "sunny"}  # your code

final = client.responses.create(
    previous_response_id=resp.id,
    input=[
        {
            "type": "function_call_output",
            "call_id": call.call_id,
            "output": json.dumps(result),
        }
    ],
    tools=[ ... ],  # same definitions
)
print(final.output_text)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://your-host/api/v1",
  apiKey: process.env.IRONCLAW_TOKEN,
});

const resp = await client.responses.create({
  input: "What is the weather in NYC?",
  tools: [
    {
      type: "function",
      name: "lookup_weather",
      description: "Return current weather.",
      parameters: {
        type: "object",
        properties: { city: { type: "string" } },
        required: ["city"],
      },
    },
  ],
});

const call = resp.output.find((it) => it.type === "function_call");
if (call) {
  const result = { temp_f: 72, conditions: "sunny" };
  const final = await client.responses.create({
    previous_response_id: resp.id,
    input: [
      {
        type: "function_call_output",
        call_id: call.call_id,
        output: JSON.stringify(result),
      },
    ],
    tools: [ /* same definitions */ ],
  });
  console.log(final.output_text);
}

Limits and quirks

Rate limit: 30 requests per 60 seconds per user (shared with /api/chat/send).
Body size: 14 MiB request limit at the gateway.
Turn timeout (non-streaming): 120 seconds. Use stream: true for long-running work.
Tool batching: one external-tool call per round trip. The engine resumes the next call on the next turn.
Approvals and auth gates: not surfaced over the Responses API. Resolve them via the web UI before retrying.
tool_choice, temperature, max_output_tokens: not yet supported. Requests carrying these fields are rejected so callers see they were not honoured.
model: must be "default". Provider and model selection is server-side via settings.
Token usage on retrieval: GET /api/v1/responses/{id} returns reconstructed output items but usage is zero because per-message token counts are not persisted.

Inference Providers — configure the model that backs "default".
Configuration — configuration file layout, profiles, and environment overrides.
Sandboxed Tools — how IronClaw’s built-in tools execute when the agent calls them.
MCP — connect Model Context Protocol servers to extend the agent’s tool surface server-side instead of supplying caller tools per-request.

Using IronClaw

Capabilities

Channels

API

Extensions (Tools)

Tutorials

When to use this vs. the Chat Completions proxy

Authentication

Quickstart

Request fields

Session continuity

Retrieving a past response

Streaming

External tools

Define tools

The round trip

Resume validation

Multi-call batching

Streaming flow

Structured context (`x_context`)

Per-request instructions

Errors

SDK usage

Limits and quirks

​When to use this vs. the Chat Completions proxy

​Authentication

​Quickstart

​Request fields

​Session continuity

​Retrieving a past response

​Streaming

​External tools

​Define tools

​The round trip

​Resume validation

​Multi-call batching

​Streaming flow

​Structured context (x_context)

​Per-request instructions

​Errors

​SDK usage

​Limits and quirks

​Related

When to use this vs. the Chat Completions proxy

Authentication

Quickstart

Request fields

Session continuity

Retrieving a past response

Streaming

External tools

Define tools

The round trip

Resume validation

Multi-call batching

Streaming flow

Structured context (`x_context`)

Per-request instructions

Errors

SDK usage

Limits and quirks

Related