HridaSpro Docs

Api Reference

Responses API

Create a model response with text, image, or file inputs.

API console
POST/v1/responses
Bash
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?"  }'
JSON
{  "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

ParameterTypeRequiredDescription
modelstringRequiredModel ID to use, provider-prefixed — e.g. gpt-oss-20b, anthropic/claude-sonnet-4.
inputstring or arrayRequiredText, 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.
backgroundboolean or nullOptionalWhether to run the model response in the background. Defaults to false.
conversationstring or objectOptionalThe conversation this response belongs to — a conversation ID, or { "id": "..." }.
includearrayOptionalAdditional output data to include in the response, e.g. reasoning encrypted content or file search results.
instructionsstringOptionalA system (or developer) message inserted as the first item of the context.
max_output_tokensintegerOptionalAn upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens.
metadatamapOptionalSet of up to 16 key-value pairs attached to the object, for storing structured information.
parallel_tool_callsbooleanOptionalWhether the model may make parallel tool calls. Defaults to true.
previous_response_idstringOptionalThe unique ID of the previous response to the model. Use this to create multi-turn conversations.
reasoningobjectOptionalConfiguration for reasoning models — e.g. { "effort": "medium", "summary": "auto" }.
response_formatobjectOptionalAn object specifying the format the model must output (JSON schema / JSON object).
service_tierstringOptionalService 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.
storeboolean or nullOptionalWhether to store the generated model response. Defaults to true.
streambooleanOptionalIf set to true, the model response is sent as server-sent events as it is generated. Defaults to false.
temperaturenumber or nullOptionalSampling temperature between 0 and 2. Defaults to 1.
tool_choicestring / objectOptionalControls which tool the model calls — "none", "auto" (default), "required", or a specific tool.
toolsarrayOptionalA list of tools the model may use — function tools, web search, file search, computer use, and more.
top_pnumber or nullOptionalNucleus sampling: the model considers the results of tokens with top_p probability mass. Defaults to 1.
truncationstring or nullOptionalThe truncation strategy for the response — "auto" (default) or "disabled".
userstringOptionalA unique identifier representing your end user, to help monitoring and abuse detection.

The response object

FieldTypeDescription
idstringUnique identifier for the response.
objectstringAlways response.
createdintegerUnix timestamp of when the response was created.
modelstringThe model used for the response.
statusstringThe status of the response — completed, failed, in_progress, or incomplete.
outputarrayThe list of output items — messages, tool calls, reasoning items, and more.
usageobjectToken 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.