Responses API

Responses API compatibility

POST /v1/responses follows the OpenAI Responses API: the same request fields, output items, streaming events, error shapes and stored state, so OpenAI SDKs (responses.create, responses.stream, responses.parse, responses.retrieve, conversations) and the Agents SDKs work by changing the base URL. As on OpenAI, responses are stored by default, so you can continue a conversation with previous_response_id or a conversation, run a response in the background and retrieve it later. Send store: false to store nothing and send the whole conversation as input each turn instead. What is stored, for how long, and how to turn storage off for your account: see Data retention below.

Tool rules are guaranteed. When a request sets strict: true on a function tool, uses tool_choice (required, a named tool or allowed_tools) or sets parallel_tool_calls: false, OpenScale checks every tool call before you see it: arguments match the JSON schema (types, required, additionalProperties: false, enum, format, pattern), only allowed tools are called, and at most one call comes back when parallel calls are off. A reply that breaks a rule is stopped and retried, and never returned; if no valid reply arrives within three attempts the request fails with 500 and code: tool_call_validation_failed (in a stream: an error event, then response.failed). Failed attempts are not billed. Streams with tool rules send reasoning as it is generated, and text and tool calls once they have been checked. A strict: true schema must follow the Structured Outputs rules (every object sets additionalProperties: false and lists all properties in required; no allOf, not or if), or the request is refused with 400 naming the parameter. Function tools without strict are not checked and read back as strict: false.

Every refusal uses the OpenAI error shape {"error": {"message", "type", "param", "code"}} with param set to the field at fault.

Endpoints

• Count input tokens: POST https://api.openscale.so/v1/responses/input_tokens
• Create a response: POST https://api.openscale.so/v1/responses
• Retrieve a response: GET https://api.openscale.so/v1/responses/{response_id}
• Delete a response: DELETE https://api.openscale.so/v1/responses/{response_id}
• Cancel a background response: POST https://api.openscale.so/v1/responses/{response_id}/cancel
• List input items: GET https://api.openscale.so/v1/responses/{response_id}/input_items
• Compact a conversation: POST https://api.openscale.so/v1/responses/compact

Count input tokens

POST https://api.openscale.so/v1/responses/input_tokens

Count the input tokens a Responses request would use, without running the model. Takes the same body as Create a response and counts it with the model tokenizer: exact for text and tools, estimated for images and for models whose tokenizer we do not carry. Free.

Example request

curl https://api.openscale.so/v1/responses/input_tokens \
  -H "Authorization: Bearer $OPENSCALE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "deepseek/deepseek-v4.1-flash",
  "input": "Hello from OpenScale"
}'

Response

200: The input token count.

Errors

Create a response

POST https://api.openscale.so/v1/responses

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

Example request

curl https://api.openscale.so/v1/responses \
  -H "Authorization: Bearer $OPENSCALE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "deepseek/deepseek-v4.1-flash",
  "input": "Hello from OpenScale",
  "store": false
}'

Response

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

{
  "id": "resp_example",
  "object": "response",
  "created_at": 1790078324,
  "status": "completed",
  "model": "deepseek/deepseek-v4.1-flash",
  "output": [
    {
      "type": "message",
      "id": "msg_example",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Hello!",
          "annotations": []
        }
      ],
      "phase": "final_answer"
    }
  ],
  "usage": {
    "input_tokens": 5,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 2,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 7
  }
}

With stream: true: Typed events: response.created, response.in_progress, response.output_item.added and .done, response.content_part.added and .done, response.output_text.delta and .done, response.reasoning_summary_part and response.reasoning_summary_text events, response.function_call_arguments.delta and .done, response.custom_tool_call_input.done, and response.completed, response.incomplete or response.failed.

Errors

Retrieve a response

GET https://api.openscale.so/v1/responses/{response_id}

A stored response, as it was returned (status queued or in_progress while a background response runs). With stream=true (background responses only), its stream events from the start, or after starting_after, then each new one as it happens.

Path parameters

Query parameters

Example request

curl https://api.openscale.so/v1/responses/$RESPONSE_ID \
  -H "Authorization: Bearer $OPENSCALE_API_KEY"

Response

200: The response, or its events when stream is true.

Errors

Delete a response

DELETE https://api.openscale.so/v1/responses/{response_id}

Delete a stored response, its input and its output at once. A running background response is cancelled.

Path parameters

Example request

curl -X DELETE https://api.openscale.so/v1/responses/$RESPONSE_ID \
  -H "Authorization: Bearer $OPENSCALE_API_KEY"

Response

200: Deleted.

{
  "id": "resp_example",
  "object": "response.deleted",
  "deleted": true
}

Errors

Cancel a background response

POST https://api.openscale.so/v1/responses/{response_id}/cancel

Stop a queued or running background response; it ends with status cancelled and is not billed for unfinished work. Cancelling again, or cancelling a finished response, returns it unchanged.

Path parameters

Example request

curl -X POST https://api.openscale.so/v1/responses/$RESPONSE_ID/cancel \
  -H "Authorization: Bearer $OPENSCALE_API_KEY"

Response

200: The response.

Errors

List input items

GET https://api.openscale.so/v1/responses/{response_id}/input_items

The input items of a stored response, each with its id. Paged with limit (1 to 100, default 20), order (desc by default) and after (an item id).

Path parameters

Query parameters

Example request

curl https://api.openscale.so/v1/responses/$RESPONSE_ID/input_items \
  -H "Authorization: Bearer $OPENSCALE_API_KEY"

Response

200: A list of items.

Errors

Compact a conversation

POST https://api.openscale.so/v1/responses/compact

Summarize a conversation so it can continue in fewer tokens. Takes model and the conversation as input (and/or previous_response_id, plus instructions). The output keeps your user messages and ends with a compaction item that stands for everything else; send the output, followed by new items, as the next input. Nothing is stored. Billed like a response.

Request body

Example request

curl https://api.openscale.so/v1/responses/compact \
  -H "Authorization: Bearer $OPENSCALE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "deepseek/deepseek-v4.1-flash",
  "input": [
    {
      "role": "user",
      "content": "My locker number is 7731."
    },
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Noted."
        }
      ]
    }
  ]
}'

Response

200: The compacted conversation.

Errors

More of the API reference

• API reference: base URLs, authentication and a first request.
• Chat Completions: POST /v1/chat/completions: the OpenAI Chat Completions format, streamed or not, with reasoning and tools.
• Conversations: Keep the turns of a Responses conversation on our side and continue it by id.
• Prompts: Save instructions, messages and settings once, then use them by id in the Responses API.
• Anthropic Messages: POST /anthropic/v1/messages: the Anthropic Messages format, for Claude Code and Anthropic SDKs.
• Models and pricing: Model ids, prices per 1M tokens, context windows, output limits, versions and the live catalog endpoint.
• Batch: Upload a JSONL file of chat completions, create a batch and collect the results when it finishes.
• Errors: The error shape, every status code and code, and which ones to retry.
• Rate limits: Requests and tokens per minute, how a 429 tells you when to retry, and how to get more.
• Data retention: What is stored, for how long, how to delete it, and zero data retention.
• Interactive reference: try every endpoint in the browser.
• OpenAPI document: the whole API as OpenAPI 3.1.