OpenAI · Responses
Generates a model response using the OpenAI Responses API shape.#
/v1/responsesOpenAI Responses API endpoint, the wire protocol the newest agentic clients speak (Codex-class tools configure wire_api = "responses" and a base_url pointing here).
Served in this version: string and item-array input (messages with input_text, input_image by data URL, http(s) URL or uploaded file_id, input_file by file_id or file_data with document text folded into context, function_call, function_call_output, reasoning passthrough), previous_response_id chaining against stored responses (instructions are not inherited, matching the upstream contract), instructions, flat function tools with tool_choice, the file_search tool against this server's vector stores, structured output through text.format (json_object and json_schema are enforced with grammar-constrained decoding), reasoning output items with real reasoning text on thinking models, usage with a reasoning-token breakdown, and response storage: store defaults to true, GET retrieves, DELETE removes, and GET //input_items lists a stored response's input.
LM-Kit extensions, with the same semantics as chat completions: 'agent' adopts a server-defined agent (prompt, skill, server tools, memory, knowledge sources, model pin; explicit request fields win), 'skill', 'server_tools', 'memory' and 'memory_store' state those assets directly, and 'user' keeps memory per end user. An agent grounded in knowledge sources reports its verdict as 'grounding'.
Streaming follows the documented event scaffold with a monotonic sequence_number: response.created, response.in_progress, response.output_item.added, response.content_part.added, response.output_text.delta*, response.output_text.done, response.content_part.done, response.output_item.done, response.completed.
background: true answers at once with the stored response in status 'queued' and generates it on the server: poll GET /v1/responses/ until its status is completed, failed, incomplete or cancelled, and cancel it with POST /v1/responses//cancel. A background response is always stored, and is not streamed.
Not served yet, refused by name rather than silently misinterpreted: conversation objects, background streaming, hosted tool types other than file_search, and item_reference.
Request body
application/json ·
| Property | Type | Description |
|---|---|---|
model | string | Model identifier. Empty selects the server's default chat model. |
input | one of object · | |
instructions | string | A system (developer) message inserted at the start of the model's context. |
tools | [] | Tools the model may call. Function tools use the Responses API's flat format: type, name, description, parameters, strict. |
tool_choice | object | How the model chooses tools: "auto", "none", "required", or {"type":"function","name":...}. |
parallel_tool_calls | boolean | Whether the model may emit several tool calls in one turn. |
text | Output text configuration; text.format carries the structured-output contract (json_schema is enforced with grammar-constrained decoding). | |
reasoning | Reasoning configuration for thinking models: effort (none/minimal/low/medium/high/xhigh/max) and summary. | |
store | boolean | Whether to persist the response for later retrieval via GET /v1/responses/. Defaults to true. |
previous_response_id | string | Chains this request onto a stored response: its effective input and output are replayed ahead of the new input. Instructions are not inherited, and neither is an agent: state it again on every request. |
conversation | one of object · | |
background | boolean | True answers at once with the stored response in status queued and generates it on the server; poll GET /v1/responses/. Always stored, never streamed. |
include | string[] | Extra payload includes. Unknown values are accepted and ignored. |
truncation | string | Context overflow policy: "disabled" (default) or "auto". |
max_output_tokens | object (int32) | Upper bound on generated tokens, reasoning included. |
temperature | object (double) | Sampling temperature. 0 selects greedy decoding. |
top_p | object (double) | Nucleus sampling threshold. |
metadata | object | Caller-defined key/value pairs echoed back and stored with the response. |
stream | boolean | When true, the response streams as named server-sent events. |
user | string | A unique identifier representing your end-user. LM-Kit keeps agent memory per end user within the API key's owner. |
agent | string | LM-Kit extension. Name of a server-defined agent: a reusable bundle (system prompt, skill, server tools, memory intent, knowledge sources, model pin) this response adopts, exactly as chat completions adopt it. The bundle supplies defaults; any field the request states explicitly wins, and 'instructions' follow the agent's prompt. An unknown name is a named 400. |
agent_revision | object | LM-Kit extension. The revision of the agent this request runs: a published revision number, pinned so later publications do not change its behavior, or "draft" to preview the agent's draft (operators only). Absent runs the live revision. The response names the revision it ran. |
simulate_tools | boolean | LM-Kit extension. true previews the exchange without side effects: server tools that only read run for real, every tool that writes, sends or cannot be undone is answered with a simulated result and never executed, and agent memory is recalled but never taught. |
skill | string | LM-Kit extension. Name of a server skill pinned for this response: its instructions ride the system turn, built server-side. |
skill_inputs | object | LM-Kit extension. Answers to the pinned skill's activation questions, keyed by each question's slug; unanswered questions fall back to their declared defaults. |
server_tools | string[] | LM-Kit extension. Server-executed built-in tools the model may use, by name (e.g. web_search, calc_arithmetic): the server runs each call and the response continues with its result. Only tools the server's Tools policy and the API key's grants allow actually run. |
memory | string | LM-Kit extension. Agent-memory id: facts extracted from this response persist on the server under this id, and facts stored earlier under it are recalled as hidden context. The id is private to the API key's owner (and to the end user named by 'user'). Requires the server's Memory feature; when it is off the response proceeds without memory. |
memory_store | string | LM-Kit extension. Name of the memory STORE the memory id lives under, a server-defined policy bundle. Absent uses the agent's store when an agent rides the request, else the default store. |
Responses
| Status | Type | Description |
|---|---|---|
| 200 | OK | |
| 400 | Bad Request | |
| 404 | Not Found | |
| 500 | application/json | Internal Server Error |
curl -X POST "$LMKIT_ONE_URL/v1/responses" \
-H "Authorization: Bearer $LMKIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "string",
"instructions": "string",
"tools": [
{
"type": "string",
"name": "string",
"description": "string",
"strict": false
}
],
"tool_choice": {}
}'Retrieves a stored response.#
/v1/responses/{responseId}Parameters
| Name | In | Type | Description |
|---|---|---|---|
responseIdrequired | path | string | The response identifier (resp_...). |
Responses
| Status | Type | Description |
|---|---|---|
| 200 | OK | |
| 404 | Not Found |
curl -X GET "$LMKIT_ONE_URL/v1/responses/$RESPONSEID" \
-H "Authorization: Bearer $LMKIT_API_KEY"Deletes a stored response.#
/v1/responses/{responseId}Parameters
| Name | In | Type | Description |
|---|---|---|---|
responseIdrequired | path | string | The response identifier (resp_...). |
Responses
| Status | Type | Description |
|---|---|---|
| 200 | application/json | OK |
| 404 | Not Found |
curl -X DELETE "$LMKIT_ONE_URL/v1/responses/$RESPONSEID" \
-H "Authorization: Bearer $LMKIT_API_KEY"Cancels a background response.#
/v1/responses/{responseId}/cancelStops a response started with background: true, on whichever node generates it, and returns it with status 'cancelled'. A response that already ended is returned as it is; a response that was not started in the background cannot be cancelled.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
responseIdrequired | path | string | The response identifier (resp_...). |
Responses
| Status | Type | Description |
|---|---|---|
| 200 | OK | |
| 400 | Bad Request | |
| 404 | Not Found |
curl -X POST "$LMKIT_ONE_URL/v1/responses/$RESPONSEID/cancel" \
-H "Authorization: Bearer $LMKIT_API_KEY"Lists the input items of a stored response.#
/v1/responses/{responseId}/input_itemsReturns the effective input the stored response was generated from (a chained prelude already expanded), newest first by default. 'order' (asc|desc), 'after' (item id cursor) and 'limit' (1-100, default 20) page the list.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
responseIdrequired | path | string | The response identifier (resp_...). |
order | query | string | Sort order by insertion position: asc or desc (default). |
after | query | string | Item id cursor: return items after this one. |
limit | query | object (int32) | Page size, 1-100 (default 20). |
Responses
| Status | Type | Description |
|---|---|---|
| 200 | application/json | OK |
| 404 | Not Found |
curl -X GET "$LMKIT_ONE_URL/v1/responses/$RESPONSEID/input_items" \
-H "Authorization: Bearer $LMKIT_API_KEY"