Responses API request shape

POST /v1/responses accepts the OpenAI Responses request body. The goal is bit-for-bit compatibility with stock OpenAI clients — anything you’d send to OpenAI’s /v1/responses you can send to Kindo’s, with the same semantics.

This page documents what Kindo recognizes and how each field is forwarded.

Required fields

Field	Type	Notes
`model`	string	A model ID from `GET /v1/models`, or a stored Kindo agent as `agent/<agent-id>` (see below).
`input`	string \| array of input items	Plain string for single-turn, or array for multi-message / tool round trips.

Agent models (`agent/<agent-id>`)

Passing model: "agent/<agent-id>" invokes one of your stored Kindo agents instead of a raw model. The agent supplies the model, system prompt, and tool set; your input is delivered to the run and your instructions compose with (append after) the agent’s own prompt. Because the agent’s configuration is pinned, request fields that would override it — tools, a non-"auto" tool_choice, conversation, previous_response_id, background, and sampling parameters such as temperature — are rejected with 400 unsupported_parameter naming the field. Agent invocations return immediately with status: "in_progress" and are polled or streamed.

See Invoke Kindo agents with the Responses API for the full walkthrough.

`input` array items

Each item is one of:

`type`	Required fields	Notes
`message`	`role`, `content`	`role` is `user`, `system`, `assistant`, or `developer`. `developer` is treated as a system-level instruction (matches OpenAI semantics).
`function_call`	`call_id`, `name`, `arguments`	Accepted for conversation-history round-tripping. Re-sending one does not re-execute it.
`function_call_output`	`call_id`, `output`	Returns a function tool’s result; pair it with the originating `function_call.call_id`.

Standard fields

Every field below is forwarded verbatim unless a row says otherwise. Behavior matches OpenAI’s published spec.

Field	Type	Forwarded?	Notes
`instructions`	string	Yes	System-level instructions. Flow through unmodified by default.
`tools`	array	Yes	Mix `function`, `mcp`, and any `kindo_*` tools. Unknown types are forwarded verbatim. `mcp` tools require the stateful path (`store: true` or `conversation`); stateless requests including them are rejected with `400 unsupported_tool_type`.
`tool_choice`	string \| object	Yes	`"auto"`, `"none"`, `"required"`, `{type: "function", name: "..."}`, or `{type: "allowed_tools", ...}`.
`stream`	boolean	—	Consumed by the route handler to switch into SSE mode (see Streaming).
`store`	boolean	Yes	When `true`, Kindo persists the response and returns a `conversation.id`. Default `false`.
`previous_response_id`	string	—	Continues the conversation that produced the referenced stored response (only responses created with `store: true` or `conversation` can be chained). Mutually exclusive with `conversation`. Unknown or inaccessible IDs → `404 previous_response_not_found`.
`conversation`	string	Yes	Existing Kindo-managed conversation ID to continue. Prior history is loaded server-side — send only the new turn in `input`. Mutually exclusive with `previous_response_id`.
`parallel_tool_calls`	boolean	Yes	Forwarded to the upstream model.
`prompt_cache_key`	string	Yes	Forwarded; used by upstream providers that support prompt caching.
`reasoning`	object	Yes	OpenAI reasoning controls (e.g. `effort`).
`text`	object	Yes	OpenAI text-output controls (e.g. `format`, `verbosity`).
`include`	array of strings	Yes	Request additional output items (e.g. encrypted reasoning content).
`truncation`	string	Yes	OpenAI truncation policy.
`background`	boolean	Yes*	OpenAI background-execution flag. *On the stateful path (`store: true` or `conversation` set), `background: true` is rejected with `400 unsupported_parameter` — background execution is not yet supported on Kindo-managed conversations. Omit it or use `stream: true`.
`service_tier`	string	Yes	OpenAI service-tier hint.
`max_output_tokens`	integer	Yes	Standard sampling control.
`temperature`	number	Yes	Standard sampling control.
`top_p`	number	Yes	Standard sampling control.
`n`	integer	Yes	Standard sampling control.
`stop`	string \| array	Yes	Standard sampling control.
`metadata`	object	Stored only	Echoed back in the response object. Not forwarded to the model layer.

Anything not listed above passes through Kindo’s schema verbatim, so new OpenAI-spec additions land at Kindo automatically when supported by the upstream model.

Stripped-on-ingress fields

Kindo strips these fields from the outgoing upstream request to prevent governance-metadata spoofing:

metadata
litellm_metadata
proxy_server_request

(metadata is stored and echoed back in the response; it is not forwarded to the model layer — see the row above.)

Response store pruning

When store: true, Kindo persists the response object so it can be fetched later via GET /v1/responses/{id}. Stored responses are not kept indefinitely — once a response is pruned (whether by retention policy expiry or explicit deletion), subsequent fetches by ID return 404 not_found with no error.code set. This is the same status the endpoint returns for IDs that never existed; the two cases are not distinguished in the response envelope.

If you need durable access to a response body, capture it from the original POST /v1/responses call rather than relying on the stored copy.

See the 404 row in the errors table for the matching error envelope.

Kindo extension fields

These are opt-in and documented in detail at Chat Actions extensions:

Field	Type	Notes
`kindo.system_prompt`	`"agent_default"` \| `"off"`	When `"agent_default"`, Kindo prepends its curated operational prompt to your `instructions`. Default `"off"`.
`tools[].type: "kindo_tools"`	sugar entry	Expands at request time to the current set of individual `kindo_<name>` entries.
`tools[].type: "kindo_<name>"`	individual hosted-tool entry	E.g. `kindo_shell`, `kindo_web_search`. See Chat Actions extensions for the full list.

The kindo block and kindo_* tool types are the only Kindo-specific additions to the request body. Everything else on this page is stock OpenAI Responses.

Worked example

{
  "model": "claude-sonnet-4-5-20250929",
  "input": [
    {
      "type": "message",
      "role": "developer",
      "content": "You are a concise security assistant."
    },
    { "type": "message", "role": "user", "content": "Summarize CVE-2024-3094." }
  ],
  "tools": [
    {
      "type": "function",
      "name": "lookup_cve",
      "description": "Fetch CVE metadata.",
      "parameters": {
        "type": "object",
        "properties": { "id": { "type": "string" } },
        "required": ["id"]
      }
    }
  ],
  "tool_choice": "auto",
  "store": true,
  "max_output_tokens": 512,
  "temperature": 0.2
}

This request is stock OpenAI Responses. Kindo accepts it identically to OpenAI’s /v1/responses, plus persists the response and returns a conversation.id because store: true is set.