API reference
Responses
POST /v1/responses
GET /v1/responses/{id}
DELETE /v1/responses/{id}Compatible with the OpenAI Responses API for text, images, function tools and structured output. The official openai SDKs work with the Utmost base URL.
Each request runs through the same gateway as chat completions: routing, refusal retry, fallback, the hard-limit checks and metering all apply. It returns the same response headers.
Request
curl https://api.utmost.site/v1/responses \
-H "Authorization: Bearer $UTMOST_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "auto",
"instructions": "Answer in one paragraph.",
"input": "What is a TOCTOU race?"
}'| Parameter | Notes |
|---|---|
model |
Required. A model id or auto alias. |
input |
Required. A string, or an array of input items (below). |
instructions |
Sent to the model as a system message. |
tools |
Function tools only: {"type": "function", "name", "description", "parameters", "strict"}. Other tool types return invalid_request. |
tool_choice |
none, auto, required, or {"type": "function", "name": "..."} |
parallel_tool_calls |
|
max_output_tokens |
Lowered to the model's limit if larger. |
temperature, top_p, seed |
|
reasoning.effort |
none, minimal, low, medium, high. Dropped for models without reasoning support. |
text.format |
{"type": "text"}, {"type": "json_object"}, or {"type": "json_schema", "name", "schema", "strict"} |
stream |
See Streaming events. |
store |
See Storage. |
previous_response_id |
Continue from a stored response. |
metadata |
String values. Echoed back; kept only if the response is stored. |
user |
Other parameters are ignored.
Input items
| Item | Shape |
|---|---|
| Message | {"role": "user" | "assistant" | "system" | "developer", "content": "..." | [parts]}. type: "message" is optional. |
| Function call | {"type": "function_call", "call_id", "name", "arguments"} |
| Function call output | {"type": "function_call_output", "call_id", "output"} |
| Reasoning | {"type": "reasoning", ...}. Accepted and dropped: reasoning is not replayed to the model. |
Content parts: input_text, output_text, text, refusal, and input_image with an image_url. File ids are not supported. Any other part type returns invalid_request.
Response
{
"id": "resp_53BJIw1zw7C8VL735r7htC0p",
"object": "response",
"created_at": 1795066918,
"status": "completed",
"error": null,
"incomplete_details": null,
"model": "utmost/qwen3-30b-a3b",
"output": [
{
"type": "message",
"id": "msg_igROhYvqj8mCd4LYrv1F",
"status": "completed",
"role": "assistant",
"content": [{ "type": "output_text", "text": "A TOCTOU race happens when...", "annotations": [] }]
}
],
"output_text": "A TOCTOU race happens when...",
"previous_response_id": null,
"store": false,
"usage": {
"input_tokens": 14,
"input_tokens_details": { "cached_tokens": 0 },
"output_tokens": 61,
"output_tokens_details": { "reasoning_tokens": 0 },
"total_tokens": 75,
"cost_usd": 0.000020
}
}The response also echoes instructions, max_output_tokens, parallel_tool_calls, reasoning, temperature, text, tool_choice, tools, top_p and metadata.
outputcan hold areasoningitem (with the reasoning text insummary), amessageitem, andfunction_callitems, in that order.statusisincomplete, withincomplete_details.reason: "max_output_tokens", when the output hit the token limit.- The response id shares its suffix with the request id:
resp_53BJ...comes fromx-request-id: req_53BJ.... Use thereq_id for feedback.
Storage and zero retention
Organizations start with response storage off. That is our zero-retention default.
| Org setting | store omitted |
store: false |
store: true |
|---|---|---|---|
| Storage off (default) | Not stored | Not stored | Error: storage_disabled (400) |
| Storage on | Stored | Not stored | Stored |
Turn storage on in the dashboard's Settings. A stored response holds the full conversation up to and including that response. It is deleted after 30 days, or when you delete it.
previous_response_id
Continue a conversation without resending it:
curl https://api.utmost.site/v1/responses \
-H "Authorization: Bearer $UTMOST_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "auto", "previous_response_id": "resp_53BJIw1zw7C8VL735r7htC0p", "input": "Give an example in C."}'- It needs storage on. With storage off it returns
storage_disabled. - The earlier response must have been stored and be under 30 days old, or it returns
not_found. instructionsare not carried over. Send them again on each request.- Under zero retention, send the whole conversation in
inputinstead.
Retrieve and delete
curl https://api.utmost.site/v1/responses/resp_53BJIw1zw7C8VL735r7htC0p \
-H "Authorization: Bearer $UTMOST_API_KEY"
curl -X DELETE https://api.utmost.site/v1/responses/resp_53BJIw1zw7C8VL735r7htC0p \
-H "Authorization: Bearer $UTMOST_API_KEY"GET returns the stored response object. DELETE returns {"id": "resp_...", "object": "response", "deleted": true}. Both return not_found for responses that were never stored, have expired, or belong to another organization.
Function calling
{
"model": "auto",
"input": "What's the weather in Paris?",
"tools": [{
"type": "function",
"name": "get_weather",
"parameters": { "type": "object", "properties": { "city": { "type": "string" } }, "required": ["city"] }
}]
}The model's call comes back as an output item:
{ "type": "function_call", "id": "fc_...", "call_id": "call_a5fc...", "name": "get_weather", "arguments": "{\"city\":\"Paris\"}", "status": "completed" }Send the result back with the call and its output in input:
{
"model": "auto",
"input": [
{ "role": "user", "content": "What's the weather in Paris?" },
{ "type": "function_call", "call_id": "call_a5fc...", "name": "get_weather", "arguments": "{\"city\":\"Paris\"}" },
{ "type": "function_call_output", "call_id": "call_a5fc...", "output": "{\"temp_c\": 14}" }
],
"tools": [ ... ]
}Streaming events
With "stream": true, events arrive in this order:
| Event | When |
|---|---|
response.created |
First |
response.in_progress |
Second |
response.output_item.added |
A reasoning, message or function-call item starts |
response.output_item.done |
For reasoning items, right after added; reasoning has no deltas |
response.content_part.added |
The message's text part starts |
response.output_text.delta |
Text |
response.function_call_arguments.delta |
Function-call arguments |
response.output_text.done |
Full text |
response.content_part.done |
|
response.output_item.done |
The message item, then each function-call item |
response.function_call_arguments.done |
Before each function call's output_item.done |
response.completed or response.incomplete |
Last. Holds the full response with usage and cost_usd. |
error |
Instead of the last event, if the stream fails |
Each data payload has type and sequence_number. See Streaming for the error format.
Python
import os
from openai import OpenAI
client = OpenAI(api_key=os.environ["UTMOST_API_KEY"], base_url="https://api.utmost.site/v1")
resp = client.responses.create(model="auto", input="What is a TOCTOU race?", store=False)
print(resp.output_text)