curl https://spro.hridaai.com/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer spro-xxxxxxxxxxxxxxxx" \ -d '{ "model": "gpt-oss-20b", "input": "What is the capital of France?" }'{ "id": "resp_abc123", "object": "response", "created": 1756968000, "model": "gpt-oss-20b", "status": "completed", "output": [ { "type": "message", "id": "msg_abc123", "role": "assistant", "content": [ { "type": "output_text", "text": "The capital of France is Paris.", "annotations": [] } ] } ], "usage": { "input_tokens": 12, "output_tokens": 8, "total_tokens": 20 }}POST https://spro.hridaai.com/v1/responses
Creates a model response with text, image, or file inputs. The Responses API is the newer OpenAI interface — it supports reasoning models, tool use, and stateful conversations, and is fully supported through Spro.
Request body
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | Required | Model ID to use, provider-prefixed — e.g. gpt-oss-20b, anthropic/claude-sonnet-4. |
input | string or array | Required | Text, image, or file inputs to the model. A plain string is treated as a user message; an array contains message items with role (user, assistant, system, or developer) and content. |
background | boolean or null | Optional | Whether to run the model response in the background. Defaults to false. |
conversation | string or object | Optional | The conversation this response belongs to — a conversation ID, or { "id": "..." }. |
include | array | Optional | Additional output data to include in the response, e.g. reasoning encrypted content or file search results. |
instructions | string | Optional | A system (or developer) message inserted as the first item of the context. |
max_output_tokens | integer | Optional | An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens. |
metadata | map | Optional | Set of up to 16 key-value pairs attached to the object, for storing structured information. |
parallel_tool_calls | boolean | Optional | Whether the model may make parallel tool calls. Defaults to true. |
previous_response_id | string | Optional | The unique ID of the previous response to the model. Use this to create multi-turn conversations. |
reasoning | object | Optional | Configuration for reasoning models — e.g. { "effort": "medium", "summary": "auto" }. |
response_format | object | Optional | An object specifying the format the model must output (JSON schema / JSON object). |
service_tier | string | Optional | Service tier to run the request on: "flex" (lower price), "priority" or "ultrafast" (lower latency, higher price). Omit it for the standard tier. See Service Tiers. |
store | boolean or null | Optional | Whether to store the generated model response. Defaults to true. |
stream | boolean | Optional | If set to true, the model response is sent as server-sent events as it is generated. Defaults to false. |
temperature | number or null | Optional | Sampling temperature between 0 and 2. Defaults to 1. |
tool_choice | string / object | Optional | Controls which tool the model calls — "none", "auto" (default), "required", or a specific tool. |
tools | array | Optional | A list of tools the model may use — function tools, web search, file search, computer use, and more. |
top_p | number or null | Optional | Nucleus sampling: the model considers the results of tokens with top_p probability mass. Defaults to 1. |
truncation | string or null | Optional | The truncation strategy for the response — "auto" (default) or "disabled". |
user | string | Optional | A unique identifier representing your end user, to help monitoring and abuse detection. |
The response object
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the response. |
object | string | Always response. |
created | integer | Unix timestamp of when the response was created. |
model | string | The model used for the response. |
status | string | The status of the response — completed, failed, in_progress, or incomplete. |
output | array | The list of output items — messages, tool calls, reasoning items, and more. |
usage | object | Token counts — input_tokens, output_tokens, total_tokens. |
Streaming
With "stream": true, response events are sent as server-sent events as the response is generated — including response.created, incremental response.output_text.delta events, and response.completed:
event: response.output_text.deltadata: {"type":"response.output_text.delta","delta":"Quantum"}
event: response.output_text.deltadata: {"type":"response.output_text.delta","delta":" computing"}
event: response.completeddata: {"type":"response.completed","response":{ ... }}Guardrails
If a guardrail detects a violation in the request and its action is set to block, Spro returns a 403 Forbidden and the request never reaches the model:
{ "error": { "message": "Request blocked by guardrail: sensitive_information_disclosure", "type": "guardrail_block", "code": "GUARDRAIL_BLOCKED" }}With other actions, the request proceeds — the violation is logged (log, warn) or the content is masked in place (redact) before the model sees it.
