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.

  • output can hold a reasoning item (with the reasoning text in summary), a message item, and function_call items, in that order.
  • status is incomplete, with incomplete_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 from x-request-id: req_53BJ.... Use the req_ 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.
  • instructions are not carried over. Send them again on each request.
  • Under zero retention, send the whole conversation in input instead.

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)