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

# Create a response

`POST /responses`

Creates an OpenAI Responses API task. Returns 202 when background=true, otherwise returns 200 after completion. Foreground stream=true requests return OpenAI Responses Server-Sent Events.

## Headers

- `Idempotency-Key` string

## Request body

- CreateResponseRequest
  - `model` string, required
  - `input` union, required — Text input, plus image input (input_image) on multimodal models. Audio, files, and item references are not currently supported.
    - string
    - ResponseInputMessage[]
      - `role` 'system' | 'user' | 'assistant' | 'tool' | 'function', required
      - `content` union, required
        - string
        - union[]
          - union
            - ResponseInputTextPart
              - …
            - ResponseInputImagePart — Image content part. Image input is supported only on multimodal models; see the Models page.
              - …
      - `name` string
      - `tool_calls` object[]
      - `tool_call_id` string
      - `function_call` object
    - ResponseInputObject
      - `messages` ResponseInputMessage[], required
        - `role` 'system' | 'user' | 'assistant' | 'tool' | 'function', required
        - `content` union, required
          - string
          - union[]
            - union
              - …
        - `name` string
        - `tool_calls` object[]
        - `tool_call_id` string
        - `function_call` object
  - `raw_prompt_tokens` integer[] — Sail extension: pre-tokenized prompt as an array of token ids, forwarded to the model verbatim (no chat templating or tokenization). When set, `input` is still required but ignored — pass a placeholder string.
  - `max_output_tokens` integer, nullable
  - `temperature` number, nullable
  - `top_p` number, nullable
  - `text` ResponseTextConfiguration
    - `format` union, required
      - ResponseTextFormat
        - `type` 'text', required
      - ResponseJsonSchemaFormat
        - `type` 'json_schema', required
        - `name` string, required
        - `description` string
        - `schema` object
        - `strict` boolean
  - `reasoning` ResponseReasoningConfiguration
    - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
    - `generate_summary` 'auto' | 'concise' | 'detailed'
  - `instructions` string — Prepended to the input as a system message.
  - `parallel_tool_calls` boolean — Accepted for OpenAI compatibility. Models decide their own tool-call cadence, so this field has no effect.
  - `include` string[] — Additional data to include. reasoning.encrypted_content is accepted for OpenAI-client compatibility, but reasoning items are returned without encrypted content.
  - `background` boolean
  - `prompt_cache_key` string — Optional routing hint for prompt-prefix cache locality. Requests with the same key are preferentially routed to maximize cache hit rates.
  - `store` boolean — Accepted for OpenAI compatibility. false does not change Sail's normal temporary request/response storage for processing, retries, polling, and idempotency; Customer Data remains governed by Sail's DPA retention and deletion terms.
  - `truncation` 'disabled'
  - `stream` boolean — When true on a foreground request, returns OpenAI Responses Server-Sent Events. background=true requests cannot be streamed.
  - `user` string
  - `metadata` RequestMetadata — Optional string metadata. completion_window controls scheduling; completion_webhook/webhook_token configure completion webhooks.
    - `completion_window` 'asap' | 'priority' | 'standard' | 'flex' — [Completion window](/completion-windows) (i.e. latency tier) for the request. Support matrix is available on the [Pricing](/pricing) page. When omitted, defaults to `standard` if that window is supported for the model; otherwise `flex` for async requests when the model supports it, and `asap` in all other cases. See [default behavior](/completion-windows#default-behavior).
    - `completion_webhook` string, uri
    - `webhook_token` string

## Response `200`

Response completed and returned synchronously. When stream=true, returns Server-Sent Events.

- ResponseObject
  - `id` string, required
  - `object` 'response', required
  - `created_at` integer, required
  - `status` 'pending' | 'running' | 'failed' | 'completed' | 'cancelled', required
  - `model` string, required
  - `input` union — Text input, plus image input (input_image) on multimodal models. Audio, files, and item references are not currently supported.
    - string
    - ResponseInputMessage[]
      - `role` 'system' | 'user' | 'assistant' | 'tool' | 'function', required
      - `content` union, required
        - string
        - union[]
          - union
            - ResponseInputTextPart
              - …
            - ResponseInputImagePart — Image content part. Image input is supported only on multimodal models; see the Models page.
              - …
      - `name` string
      - `tool_calls` object[]
      - `tool_call_id` string
      - `function_call` object
    - ResponseInputObject
      - `messages` ResponseInputMessage[], required
        - `role` 'system' | 'user' | 'assistant' | 'tool' | 'function', required
        - `content` union, required
          - string
          - union[]
            - union
              - …
        - `name` string
        - `tool_calls` object[]
        - `tool_call_id` string
        - `function_call` object
  - `output` union
    - string
    - object[]
    - object
  - `error` object, nullable
  - `incomplete_details` object, nullable
  - `max_output_tokens` integer, nullable
  - `reasoning` object
  - `text` ResponseTextConfiguration
    - `format` union, required
      - ResponseTextFormat
        - `type` 'text', required
      - ResponseJsonSchemaFormat
        - `type` 'json_schema', required
        - `name` string, required
        - `description` string
        - `schema` object
        - `strict` boolean
  - `store` boolean
  - `temperature` number
  - `top_p` number
  - `parallel_tool_calls` boolean
  - `tool_choice` union
    - string
    - object
  - `tools` object[]
  - `truncation` union
    - string
    - object
  - `usage` ResponseUsage, required
    - `input_tokens` integer, required
    - `input_tokens_details` ResponseUsageDetails, required
      - `cached_tokens` integer, required
      - `reasoning_tokens` integer, required
    - `output_tokens` integer, required
    - `output_tokens_details` ResponseUsageDetails, required
      - `cached_tokens` integer, required
      - `reasoning_tokens` integer, required
    - `total_tokens` integer, required
    - `prompt_tokens` integer
    - `completion_tokens` integer
  - `user` string, nullable
  - `metadata` object, required

## Other responses

- `202` — Response accepted for asynchronous processing.
- `400` — Invalid request or unsupported feature.
- `401` — Authentication error.
- `500` — Server error.
- `502` — Upstream proxy error.
- `504` — Timed out waiting for completion.

---

[API](https://skmtc.dev/sailresearch/apis/sail-api.md) · [All operations](https://skmtc.dev/sailresearch/apis/sail-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/sailresearch/sail-api/revisions/c2a783d507f9/schema)