---
title: "Create a response"
method: POST
path: "/v1/responses"
tags: ["Responses"]
---

# Create a response

`POST /v1/responses`

Generate an OpenAI-compatible Responses API object from text or structured input items, with optional tools and streaming events.

## Request body

- ResponsesRequest — Stateless gateway schema for OpenAI Responses API request body. Strict request surface: only parameters that map to the gateway's unified model.
  - `model` string, required — Model identifier to route the request to.
  - `input` union, required — Text or structured input items to the model.
    - string
    - union[]
      - union
        - InputMessage — Corresponds to `InputMessage`.
          - `type` 'message'
          - `role` 'user' | 'assistant' | 'system' | 'developer', required
          - `content` union
            - string
            - union[]
              - …
          - `name` string, nullable
        - InputFunctionCall — Corresponds to `RealtimeConversationItemFunctionCall` / `InputItem`.
          - `type` 'function_call', required
          - `call_id` string, required
          - `name` string, required
          - `arguments` string
        - InputFunctionCallOutput — Corresponds to `RealtimeConversationItemFunctionCallOutput` / `InputItem`.
          - `type` 'function_call_output', required
          - `call_id` string, required
          - `output` union
            - string
            - union[]
              - …
        - InputReasoningItem — Corresponds to `ReasoningItem`.
          - `type` 'reasoning', required
          - `id` string, nullable
          - `content` object[], nullable
          - `summary` object[], nullable
          - `encrypted_content` string, nullable
          - `status` 'in_progress' | 'completed' | 'incomplete', nullable
        - ItemReference — OpenAI Responses API `item_reference` input item.
          - `type` 'item_reference'
          - `id` string, required
  - `instructions` string, nullable — A system (or developer) message inserted into the model's context.
  - `max_output_tokens` integer, nullable
  - `temperature` number, nullable
  - `top_p` number, nullable
  - `presence_penalty` number, nullable
  - `frequency_penalty` number, nullable
  - `tools` union[], nullable
    - union
      - FunctionTool — Corresponds to `FunctionTool`.
        - `type` 'function'
        - `name` string, nullable — Function name exposed to the model.
        - `description` string, nullable
        - `parameters` object, nullable
        - `strict` boolean, nullable
        - `function` object, nullable
      - WebSearchTool — OpenAI Responses API web search tool (gateway subset). We only accept the identifying `type`. Presence enables internal `web_search_options` in the unified request config.
        - `type` 'web_search' | 'web_search_2025_08_26', required
        - `filters` object, nullable
        - `search_context_size` 'low' | 'medium' | 'high', nullable
        - `user_location` object, nullable
      - WebSearchPreviewTool
        - `type` 'web_search_preview' | 'web_search_preview_2025_03_11', required
        - `search_context_size` 'low' | 'medium' | 'high', nullable
        - `user_location` object, nullable
      - FileSearchTool
        - `type` 'file_search', required
        - `vector_store_ids` string[], required
        - `filters` unknown
        - `max_num_results` integer, nullable
        - `ranking_options` object, nullable
      - ComputerUseTool
        - `type` 'computer_use_preview', required
        - `display_height` union, required
          - integer
          - number
        - `display_width` union, required
          - integer
          - number
        - `environment` 'windows' | 'mac' | 'linux' | 'ubuntu' | 'browser', required
      - CodeInterpreterTool
        - `type` 'code_interpreter', required
        - `container` union, required
          - string
          - object
      - McpTool
        - `type` 'mcp', required
        - `server_label` string, required
        - `allowed_tools` unknown
        - `authorization` string, nullable
        - `connector_id` string, nullable
        - `headers` object, nullable
        - `require_approval` unknown
        - `server_description` string, nullable
        - `server_url` string, nullable
      - ImageGenerationTool
        - `type` 'image_generation', required
        - `background` 'transparent' | 'opaque' | 'auto', nullable
        - `input_fidelity` 'high' | 'low', nullable
        - `input_image_mask` object, nullable
        - `model` 'gpt-image-1' | 'gpt-image-1-mini', nullable
        - `moderation` 'auto' | 'low', nullable
        - `output_compression` union
          - integer
          - number
        - `output_format` 'png' | 'webp' | 'jpeg', nullable
        - `partial_images` union
          - integer
          - number
        - `quality` 'low' | 'medium' | 'high' | 'auto', nullable
        - `size` '1024x1024' | '1024x1536' | '1536x1024' | 'auto', nullable
      - LocalShellTool
        - `type` 'local_shell', required
      - ShellTool
        - `type` 'shell', required
      - ApplyPatchTool
        - `type` 'apply_patch', required
      - CustomTool
        - `type` 'custom', required
        - `name` string, required
        - `description` string, nullable
        - `format` object, nullable
  - `tool_choice` union
    - 'auto' | 'none' | 'required'
    - ToolChoiceFunction — Official Responses API tool_choice for forcing a function call: {"type":"function","name":"get_weather"}
      - `type` 'function', required
      - `name` string, required
    - ToolChoiceFunctionLegacy — Backwards-compatible chat-style tool_choice: {"type":"function","function":{"name":"get_weather"}}
      - `type` 'function', required
      - `function` object, required
    - ToolChoiceAllowedTools — Official Responses API allowed_tools: {"type":"allowed_tools","mode":"auto|required","tools":[{...}]}
      - `type` 'allowed_tools', required
      - `mode` 'auto' | 'required', nullable
      - `tools` ToolChoiceFunction[], required
        - `type` 'function', required
        - `name` string, required
  - `parallel_tool_calls` boolean, nullable
  - `truncation` 'auto' | 'disabled', nullable
  - `reasoning` ReasoningConfig — Corresponds to `Reasoning` schema. We keep this as the subset that maps to the gateway's unified `reasoning_effort` control.
    - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh', nullable
  - `text` ResponseTextConfig — Corresponds to CreateResponse `text` parameter.
    - `format` ResponseTextFormat — Corresponds to `ResponseFormatJsonSchema` or `ResponseFormatText`.
      - `type` 'text' | 'json_object' | 'json_schema', required
      - `name` string, nullable
      - `description` string, nullable
      - `schema` object, nullable
      - `strict` boolean, nullable
  - `stream` boolean — Return a Responses API SSE event stream instead of a single JSON response.

## Response `200`

JSON response when stream=false, or Responses API Server-Sent Events when stream=true.

- ResponsesApiResponse
  - `id` string, required
  - `object` 'response'
  - `created_at` integer, required
  - `completed_at` integer, nullable
  - `status` string, required
  - `incomplete_details` object, nullable
  - `model` string, required
  - `previous_response_id` string, nullable
  - `instructions` string, nullable
  - `output` union[], required
    - union
      - ResponseMessageItem
        - `type` 'message'
        - `id` string, required
        - `status` string, nullable
        - `role` string, required
        - `content` ResponseOutputTextPart[], required
          - `type` 'output_text'
          - `text` string, required
          - `annotations` ResponseOutputTextAnnotation[]
            - `type` string, required
            - `start_index` integer, nullable
            - `end_index` integer, nullable
            - `url` string, nullable
            - `title` string, nullable
          - `logprobs` object[]
      - ResponseFunctionCallItem
        - `type` 'function_call'
        - `id` string, required
        - `call_id` string, nullable
        - `name` string, nullable
        - `arguments` string
        - `status` string, nullable
      - ResponseReasoningItem
        - `type` 'reasoning'
        - `id` string, required
        - `status` string, nullable
        - `summary` ResponseSummaryTextPart[], nullable
          - `type` 'summary_text'
          - `text` string, required
        - `content` ResponseReasoningTextPart[], nullable
          - `type` 'reasoning_text'
          - `text` string, required
        - `encrypted_content` string, nullable
      - ResponseImageGenerationCallItem
        - `type` 'image_generation_call'
        - `id` string, required
        - `result` string, required
        - `status` string, nullable
  - `error` ResponseErrorOutput
    - `code` string, nullable
    - `message` string, required
  - `tools` union[]
    - union
      - ResponseFunctionTool
        - `type` 'function'
        - `name` string, nullable
        - `description` string, nullable
        - `parameters` object, nullable
        - `strict` boolean, nullable
      - ResponseWebSearchTool
        - `type` 'web_search' | 'web_search_2025_08_26', required
        - `filters` object, nullable
        - `search_context_size` 'low' | 'medium' | 'high', nullable
        - `user_location` object, nullable
      - ResponseWebSearchPreviewTool
        - `type` 'web_search_preview' | 'web_search_preview_2025_03_11', required
        - `search_context_size` 'low' | 'medium' | 'high', nullable
        - `user_location` object, nullable
      - ResponseFileSearchTool
        - `type` 'file_search', required
        - `vector_store_ids` string[], required
        - `filters` unknown
        - `max_num_results` integer, nullable
        - `ranking_options` object, nullable
      - ResponseComputerUseTool
        - `type` 'computer_use_preview', required
        - `display_height` union, required
          - integer
          - number
        - `display_width` union, required
          - integer
          - number
        - `environment` 'windows' | 'mac' | 'linux' | 'ubuntu' | 'browser', required
      - ResponseCodeInterpreterTool
        - `type` 'code_interpreter', required
        - `container` union, required
          - string
          - object
      - ResponseMcpTool
        - `type` 'mcp', required
        - `server_label` string, required
        - `allowed_tools` unknown
        - `authorization` string, nullable
        - `connector_id` string, nullable
        - `headers` object, nullable
        - `require_approval` unknown
        - `server_description` string, nullable
        - `server_url` string, nullable
      - ResponseImageGenerationTool
        - `type` 'image_generation', required
        - `background` 'transparent' | 'opaque' | 'auto', nullable
        - `input_fidelity` 'high' | 'low', nullable
        - `input_image_mask` object, nullable
        - `model` 'gpt-image-1' | 'gpt-image-1-mini', nullable
        - `moderation` 'auto' | 'low', nullable
        - `output_compression` union
          - integer
          - number
        - `output_format` 'png' | 'webp' | 'jpeg', nullable
        - `partial_images` union
          - integer
          - number
        - `quality` 'low' | 'medium' | 'high' | 'auto', nullable
        - `size` '1024x1024' | '1024x1536' | '1536x1024' | 'auto', nullable
      - ResponseLocalShellTool
        - `type` 'local_shell', required
      - ResponseShellTool
        - `type` 'shell', required
      - ResponseApplyPatchTool
        - `type` 'apply_patch', required
      - ResponseCustomTool
        - `type` 'custom', required
        - `name` string, required
        - `description` string, nullable
        - `format` object, nullable
  - `tool_choice` union
    - string
    - ResponseFunctionToolChoice
      - `type` 'function'
      - `name` string, required
    - ResponseAllowedToolsChoice
      - `type` 'allowed_tools'
      - `mode` 'auto' | 'required'
      - `tools` ResponseFunctionToolChoice[], required
        - `type` 'function'
        - `name` string, required
  - `truncation` 'auto' | 'disabled', nullable
  - `parallel_tool_calls` boolean, nullable
  - `text` ResponseTextConfigOutput
    - `format` union
      - ResponseTextFormatText
        - `type` 'text'
      - ResponseTextFormatJsonObject
        - `type` 'json_object'
      - ResponseTextFormatJsonSchema
        - `type` 'json_schema'
        - `name` string, nullable
        - `description` string, nullable
        - `schema` object, nullable
        - `strict` boolean, nullable
    - `verbosity` 'low' | 'medium' | 'high', nullable
  - `top_p` number, nullable
  - `presence_penalty` number, nullable
  - `frequency_penalty` number, nullable
  - `top_logprobs` integer, nullable
  - `temperature` number, nullable
  - `reasoning` ResponseReasoningConfigOutput
    - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh', nullable
    - `summary` 'auto' | 'concise' | 'detailed', nullable
  - `usage` ResponseUsageOutput
    - `input_tokens` integer, required
    - `input_tokens_details` ResponseUsageInputTokensDetails, required
      - `cached_tokens` integer, required
    - `output_tokens` integer, required
    - `output_tokens_details` ResponseUsageOutputTokensDetails, required
      - `reasoning_tokens` integer, required
    - `total_tokens` integer, required
  - `max_output_tokens` integer, nullable
  - `max_tool_calls` integer, nullable
  - `store` boolean, nullable
  - `background` boolean, nullable
  - `service_tier` string, nullable
  - `metadata` union
    - object
    - object
  - `safety_identifier` string, nullable
  - `prompt_cache_key` string, nullable

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `402` — Insufficient credits
- `403` — Forbidden
- `410` — Model deprecated
- `422` — Validation error
- `429` — Rate limited
- `500` — Internal server error
- `503` — Upstream service error

---

[API](https://skmtc.net/naga/apis/nagaai-api.md) · [All operations](https://skmtc.net/naga/apis/nagaai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/naga/nagaai-api/revisions/8bfb4677a79e/schema)