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

# Create a response

`POST /responses`

## Request

- Base URL: `https://api.openscale.so/v1`
- URL: `https://api.openscale.so/v1/responses`
- Auth: HTTP bearer

Create a response from a string or an array of input items (messages, tool call and tool output items, and `reasoning` items from an earlier turn). Function, custom, namespace, shell, local shell, apply patch and client tool search tools are supported, and `strict`, `tool_choice` (including `allowed_tools`) and `parallel_tool_calls: false` are enforced. Reasoning comes back as a `reasoning` item with `encrypted_content` you can send back unchanged, readable `reasoning_text` content, and a summary when `reasoning.summary` is set. Responses are stored for 30 days by default (`store`), so a later request can continue from one with `previous_response_id`, or keep its turns in a `conversation`; with `background: true` the response runs on its own and is retrieved later. See the Responses API compatibility table and Data retention in the introduction.

## Request body

- object
  - `model` 'deepseek/deepseek-v4.1-flash' | 'z-ai/glm-5.3-flash' | 'deepseek/deepseek-v4.1-flash-1017' | 'deepseek/deepseek-v4.1-flash-0910' | 'z-ai/glm-5.3-flash-0828' | 'deepseek/deepseek-v4.1-flash:fast' | 'deepseek/deepseek-v4.1-flash-1017:fast' | 'deepseek/deepseek-v4.1-flash-0910:fast', required
  - `input` union, required
    - string
    - object[]: Messages plus `function_call`, `function_call_output`, `custom_tool_call`, `custom_tool_call_output` and `reasoning` items.
      - `role` string
      - `content` union
        - string
        - object[]
          - `type` 'input_text' | 'input_image'
          - `text` string
          - `image_url` string
  - `instructions` string
  - `tools` object[]: `function` (with `strict`), `custom`, `namespace`, `shell`, `local_shell`, `apply_patch` and client `tool_search` tools. Web search is left out (see `x-openscale-ignored-tools`); other hosted tools are refused.
  - `tool_choice` unknown
  - `parallel_tool_calls` boolean
  - `text` object: Structured outputs: `{ "format": { "type": "json_schema", ... } }` or `json_object`. `json_object` works whether or not your prompt mentions JSON.
  - `max_output_tokens` integer
  - `temperature` number
  - `top_p` number
  - `stream` boolean
  - `metadata` object
  - `store` boolean: Store the response for 30 days, for `previous_response_id`, retrieval and `input_items`. `false` stores nothing. Always `false` when the account has zero data retention on.
  - `previous_response_id` string: Continue from a stored response: its input and output (and those of the responses before it) come before `input`. Its `instructions` do not carry over.
  - `conversation` union: A conversation id (or `{ "id": ... }`): its items come before `input`, and the input and output are added to it when the response finishes.
    - string
    - object
      - `id` string, required
  - `background` boolean: Run the response on its own: answered at once with a `queued` response; retrieve it, stream it, or cancel it by id.
  - `user` string
  - `reasoning` object: Reasoning control: `effort` (`none` to `xhigh`) and `summary` (`auto`, `concise` or `detailed` returns a readable summary).

## Response `200`

The response, or a typed SSE stream when `stream` is true.

- Response
  - `id` string, required
  - `object` 'response', required
  - `created_at` integer, required
  - `status` 'completed' | 'incomplete' | 'failed' | 'in_progress' | 'queued' | 'cancelled', required
  - `model` 'deepseek/deepseek-v4.1-flash' | 'z-ai/glm-5.3-flash' | 'deepseek/deepseek-v4.1-flash-1017' | 'deepseek/deepseek-v4.1-flash-0910' | 'z-ai/glm-5.3-flash-0828' | 'deepseek/deepseek-v4.1-flash:fast' | 'deepseek/deepseek-v4.1-flash-1017:fast' | 'deepseek/deepseek-v4.1-flash-0910:fast', required
  - `output` object[], required
    - `type` 'message'
    - `id` string
    - `role` 'assistant'
    - `status` 'completed'
    - `content` object[]
      - `type` 'output_text'
      - `text` string
      - `annotations` unknown[]
        - unknown
    - `phase` 'commentary' | 'final_answer': `commentary`: text written before a tool call in the same response. `final_answer`: the reply. Assistant messages sent back in `input` may keep it.
  - `usage` object, required
    - `input_tokens` integer
    - `input_tokens_details` object
      - `cached_tokens` integer: Input tokens billed at the cached rate.
    - `output_tokens` integer
    - `output_tokens_details` object
      - `reasoning_tokens` integer: Reasoning tokens, billed as output tokens.
    - `total_tokens` integer
  - `service_tier` 'default' | 'priority': The tier that served the response: `priority` in fast mode.

## Other responses

- `400`: Invalid request; `param` names the field. `previous_response_not_found` when the previous response is unknown, deleted or past its 30 days.
- `401`: Missing or invalid API key.
- `402`: Empty balance, or the key reached its spend limit.
- `404`: Unknown model id.
- `429`: Rate limit crossed or model at capacity.
- `502`: The model is temporarily unavailable.
- `504`: The model did not respond in time.

---

[API](https://skmtc.dev/openscale/apis/openscale-api.md) - [All operations](https://skmtc.dev/openscale/apis/openscale-api/llms.txt) - [OpenAPI document](https://skmtc.dev/openscale/apis/openscale-api/revisions/587e72b44932?raw)