SAsailresearch
Responses API

Create a response

Changed on

Creates an OpenAI Responses API task. Accepted background requests return 202; foreground requests return 200 after completion. Foreground stream=true requests return OpenAI Responses Server-Sent Events.

post/responses

Request

  • Base URL
    https://api.sailresearch.com/v1
  • URL
    https://api.sailresearch.com/v1/responses
  • Auth
    HTTP bearer

Headers

Idempotency-Keystring

Identifies one submission within your organization and API key. Reuse the same value and request body when retrying; use a new value for new work. See Idempotency.

X-Sail-Completion-Window'asap' | 'balanced' | 'flex'

Completion window for this request, for clients that cannot set metadata.completion_window in the body. A window in the body takes precedence. See Completion windows.

Request body

modelstring required
raw_prompt_tokensinteger[]

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_tokensinteger nullable
temperaturenumber nullable
top_pnumber nullable
instructionsstring

Prepended to the input as a system message.

parallel_tool_callsboolean

Accepted for OpenAI compatibility. Models decide their own tool-call cadence, so this field has no effect.

includestring[]

Additional data to include. reasoning.encrypted_content is accepted for OpenAI-client compatibility, but reasoning items are returned without encrypted content.

backgroundboolean

When true, submits a background request using a supported balanced or flex window; defaults to false. See Background mode for restrictions and Default behavior for window selection.

prompt_cache_keystring

Optional routing hint for prompt-prefix cache locality. Requests with the same key are preferentially routed to maximize cache hit rates.

storeboolean

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'
streamboolean

When true on a foreground request, returns OpenAI Responses Server-Sent Events. background=true requests cannot be streamed.

userstring

Response

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

idstring required
object'response' required
created_atinteger required
status'queued' | 'in_progress' | 'failed' | 'completed' | 'incomplete' | 'cancelled' required
modelstring required
errorobject nullable
incomplete_detailsobject nullable
max_output_tokensinteger nullable
reasoningobject
storeboolean
temperaturenumber
top_pnumber
parallel_tool_callsboolean
toolsobject[]
userstring nullable
service_tier'asap' | 'balanced' | 'flex'

The completion window Sail selected for this request, including when no window was requested. The legacy request value standard is reported as balanced. Older stored responses may omit this field.

Changes

  • d63ac1749ae7Revision changes
    • breaking

      added to the request property allOf list

    • breaking

      the request property type changed from object to no type

    • breaking

      added to the ///////// response property oneOf list for the response status

    • breaking

      added to the ///////// response property oneOf list for the response status

    • breaking

      added to the ///// response property oneOf list for the response status

    • breaking

      added to the ///// response property oneOf list for the response status

    • breaking

      added subschema #2 to the response property oneOf list for the response status

    • breaking

      added subschema #2 to the response property oneOf list for the response status

    • breaking

      the response's property type changed from object to no type for status

    • breaking

      the response's property type changed from object to no type for status

    • breaking

      removed the required property / from the response with the status

    • breaking

      removed the required property / from the response with the status

    • breaking

      removed the required property / from the response with the status

    • breaking

      removed the required property / from the response with the status

    • breaking

      removed the required property / from the response with the status

    • breaking

      removed the required property / from the response with the status

    • breaking

      removed the required property / from the response with the status

    • breaking

      removed the required property / from the response with the status

    • breaking

      removed the required property / from the response with the status

    • breaking

      removed the required property / from the response with the status

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      added the new in_progress enum value to the response property for the response status

    • warning

      added the new in_progress enum value to the response property for the response status

    • warning

      added the new incomplete enum value to the response property for the response status

    • warning

      added the new incomplete enum value to the response property for the response status

    • warning

      added the new queued enum value to the response property for the response status

    • warning

      added the new queued enum value to the response property for the response status

    • info

      added the new optional header request parameter X-Sail-Completion-Window

    • info

      added the new max enum value to the request property /

    • info

      added to the ///////// request property oneOf list

    • info

      added to the ///// request property oneOf list

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      removed the pending enum value from the response property for the response status

    • info

      removed the pending enum value from the response property for the response status

    • info

      removed the running enum value from the response property for the response status

    • info

      removed the running enum value from the response property for the response status