--- title: "Create response" method: POST path: "/responses" tags: ["responses-api"] --- # Create response `POST /responses` Creates a model response for the given input. This endpoint implements the Open Responses compatible API, providing enhanced capabilities including: - **Reasoning models** with controllable effort via `reasoning` parameter - **Stateful conversations** via `previous_response_id` for maintaining context across turns - **Flexible input** - accepts either a string or array of messages - **Text output configuration** via `text` parameter for structured outputs - **Context window management** via `truncation` parameter Set `stream: true` to receive partial responses as server-sent events. [Open Responses API Reference →](https://www.openresponses.org/reference) ## Request body - ResponseRequest — Request body for creating a response. - `frequency_penalty` number, float, nullable — Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far. - `include` string, nullable — Include encrypted reasoning content for rehydration on subsequent requests. - `input` union, required — Input for response requests - can be a single string or array of messages. - string — A single string input. - ChatMessage[] — An array of messages (chat-style conversation). - `content` string, nullable — The content of the message. - `name` string, nullable — The name of the author (for function/tool messages). - `role` string, required — The role of the message author (system, user, assistant, tool, function). - `tool_call_id` string, nullable — The ID of the tool call this message is responding to. - `tool_calls` ToolCall[], nullable — Tool calls made by the assistant. - `function` FunctionCall, required — A function call within a tool call. - `arguments` string, required — The arguments to pass to the function, as a JSON string. - `name` string, required — The name of the function to call. - `id` string, required — The ID of the tool call. - `type` string, required — The type of tool (currently only "function"). - `instructions` string, nullable — System instructions for the model. - `max_output_tokens` integer, nullable — The maximum number of tokens to generate in the response. - `metadata` unknown - `modalities` string[], nullable — Output types that you would like the model to generate (e.g., ["text"], ["text", "audio"]). - `model` string, required — ID of the model to use. - `parallel_tool_calls` boolean, nullable — Whether to enable parallel function calling during tool use. - `presence_penalty` number, float, nullable — Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far. - `previous_response_id` string, nullable — The ID of a previous response to continue from (for stateful conversations). - `reasoning` unknown - `reasoning_effort` string, nullable — Constrains effort on reasoning. Supported values: "none", "minimal", "low", "medium", "high", "xhigh". - `stop` string[], nullable — Up to 4 sequences where the API will stop generating further tokens. - `store` boolean, nullable — Whether to store this response for future reference. - `stream` boolean, nullable — If set, partial message deltas will be sent as server-sent events. - `stream_options` unknown - `temperature` number, float, nullable — What sampling temperature to use, between 0 and 2. - `text` unknown - `tool_choice` unknown - `tools` Tool[], nullable — A list of tools the model may call. - `function` FunctionDefinition, required — Definition of a function that can be called by the model. - `description` string, nullable — A description of what the function does. - `name` string, required — The name of the function. - `parameters` unknown - `type` string, required — The type of tool (currently only "function"). - `top_p` number, float, nullable — An alternative to sampling with temperature, called nucleus sampling. - `truncation` string, nullable — How to handle context window overflow ("auto" or "disabled"). - `user` string, nullable — A unique identifier representing your end-user. ## Response `200` Response generated successfully. When streaming, returns a series of SSE events. - ResponseObject — Response from creating a response. - `completed_at` integer, required — The Unix timestamp of when the response was completed. - `created_at` integer, required — The Unix timestamp of when the response was created. - `id` string, required — A unique identifier for the response. - `metadata` unknown - `model` string, required — The model used for generating the response. - `object` string, required — The object type, always "response". - `output` ResponseItem[], required — The output items generated by the model. - `content` string, nullable — The content of the message (for message-type items). - `role` string, nullable — The role of the message (for message-type items). - `tool_calls` ToolCall[], nullable — Tool calls made by the model (for message-type items with tool calls). - `function` FunctionCall, required — A function call within a tool call. - `arguments` string, required — The arguments to pass to the function, as a JSON string. - `name` string, required — The name of the function to call. - `id` string, required — The ID of the tool call. - `type` string, required — The type of tool (currently only "function"). - `type` string, required — The type of item (e.g., "message", "function_call"). - `status` string, required — The status of the response. Can be "completed", "incomplete", "cancelled", or "failed". - `temperature` number, float, required — The temperature used for sampling (echoed from request). - `top_p` number, float, required — The nucleus sampling parameter used (echoed from request). - `usage` Usage, required — Token usage statistics. - `completion_tokens` integer, required — Number of tokens in the generated completion. - `prompt_tokens` integer, required — Number of tokens in the prompt. - `total_tokens` integer, required — Total number of tokens used in the request. ## Other responses - `400` — Invalid request — check that your input is properly formatted and all required fields are present. - `401` — Invalid or missing API key. Ensure your `Authorization` header is set to `Bearer YOUR_API_KEY`. - `402` — Insufficient credits. Top up your account to continue making requests. - `403` — Your API key does not have access to the requested model. - `404` — The specified model does not exist. Use `GET /models` to list available models. - `429` — Rate limit exceeded. Back off and retry after a short delay. - `500` — An unexpected error occurred. Retry the request or contact support if the issue persists. --- [API](https://skmtc.dev/doubleword/apis/doubleword-api.md) · [All operations](https://skmtc.dev/doubleword/apis/doubleword-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/doubleword/doubleword-api/revisions/6617202865d8/schema)