POST /ai/v2/guarded/responses) is the Responses format with Gloo’s guardrails. It pairs the OpenAI-compatible Responses request shape (one typed input/output[] format for text, vision, reasoning, tool use, and native image generation) with Gloo’s full safety and values pipeline: the same guardrails, values-aligned tradition responses, and output moderation that power Completions.
Choose this when Gloo should handle safety and values. If your app owns its safety, Direct Responses takes the same request body. If you already use Completions V2, it remains fully supported; see Moving from Completions to Responses.
Why the Responses API
- OpenAI-compatible. The request and response formats mirror the OpenAI Responses API, so existing tooling, SDKs, and mental models carry over. Point your base URL at
https://platform.ai.gloo.com/ai/v2/guardedand callresponses.create. - Guarded by default. Every request runs the same pipeline as
/ai/v2/guarded/chat/completions(guardrails, blocked-content handling, values-aligned answers, and output moderation) with no extra configuration. - Values-aligned. The
traditionparameter customizes responses to theological perspectives, exactly as on Completions. - Built for multimodal. Image input (vision) and image generation are first-class: the same endpoint that answers a text prompt can read an image or return a generated one, using the same
inputarray and typedoutput[]items. - Typed output items. Responses come back as an
output[]array of typed items (message,image_generation_call, reasoning, tool calls) instead of a single opaquechoices[].message.contentstring, so they’re easier to parse and extensible as new item types arrive.
Which API should I use?
For the full comparison across guarded, direct, grounded, and embeddings endpoints, see Endpoint types.
Endpoint
URL:https://platform.ai.gloo.com/ai/v2/guarded/responses
Operation: POST
Request format
The Responses API usesinput instead of messages, plus a few renamed fields:
The request body is the same as Direct Responses, plus
tradition. model and input are required. A few parameters need a note:
model: pinned-model only. Auto-routing andmodel_familyare Completions V2 features.tradition:"evangelical","catholic","mainline", or"not_faith_specific", or omit it for a general Christian perspective. Invalid values are ignored gracefully.max_output_tokens: on a reasoning model it holds the reasoning as well as the answer, so leave room for both. With no value, most reasoning models get their full output allowance (up to 65,536); Claude models and the Gemini Flash-Lite models use the model’s default, so set a value for long answers. A response that reached it hasstatus: "incomplete". See Set your output limit for reasoning models.reasoning: see Reasoning summaries.
Conversation state is managed client-side: send the full conversation in
input on every request (Conversations That Remember shows how). previous_response_id, conversation, store and background (OpenAI’s server-side conversation state) are not supported and have no effect, and a model’s reasoning is not carried from one request to the next. See Reasoning across turns.Guardrails and values
Requests dispatch through the same pipeline as Completions V2, so guardrail behavior is identical:- Values-aligned static responses. When guardrails intervene with a curated, tradition-appropriate answer, it comes back as a normal Responses payload: a
messageitem inoutput[]carrying the static text. Your client needs no special handling. - Hard blocks. Requests that guardrails reject outright return the same
403error as/ai/v2/guarded/chat/completions. - Output moderation. Model text output passes through Gloo’s moderation layer before it reaches you. Reasoning summaries are not moderated, and are still returned when moderation replaces the answer; see Reasoning.
Response format
Responses return a typedoutput[] array. Each item has a type; a normal text answer arrives as a message item.
Streaming
Set"stream": true to receive the response as Server-Sent Events. Each event has an event: line and a data: line carrying a typed JSON payload:
response.created: emitted once at the start of the response.response.output_text.delta/response.output_text.done: incremental text tokens for amessageitem.response.output_item.added/response.output_item.done: emitted for typed items inoutput[](includingfunction_call).response.completed: emitted once when the response is finished. Its payload is the response’s top-level fields (id,object,status,usageand the request settings), not nested under aresponsekey, and withoutoutput[]: build the answer from the events before it. Token usage is always included on streams; you don’t need to request it. An answer cut off atmax_output_tokensends withresponse.incompleteinstead, in the same shape.- Error events: surfaced as event types prefixed with
error.(e.g.error); treat any unknown event as terminal and close the stream.
Reasoning summaries
Setreasoning.effort to choose how much a reasoning model thinks, and reasoning.summary (auto, concise or detailed) to get a summary of its reasoning back as a reasoning item in output[]. The request has the same shape as on Direct Responses. On this endpoint, a Claude model’s reasoning item has an id that starts with reasoning_; OpenAI models return rs_ ids. For response and stream shapes, effort levels by model, and examples in every language, see Reasoning.
Reasoning across turns
Reasoning models can return areasoning item in output[] with a summary of how they reasoned. Gloo does not carry a model’s reasoning from one request to the next: each request is reasoned from the conversation you send in input.
- What comes back. Reasoning items carry an
idand asummary, neverencrypted_content. Asking forinclude: ["reasoning.encrypted_content"]is accepted and returns nothing. - Reasoning you send back. You can send output items back in
input, reasoning items included; the request is not rejected. This endpoint removes everyreasoningitem you send before calling the model, including an item sent back exactly as this endpoint returned it, with noencrypted_content. That has always been the case here; what is new is the report below, which lists every removed item. - Requests with no reasoning items, and no
includerequest for reasoning, are unchanged.
input contains at least one reasoning item, or you asked for include: ["reasoning.encrypted_content"], the response has a top-level reasoning_carryover object. Here a second turn sent the first turn’s output back as received, with its one reasoning item:
received counts the reasoning items in your input, carried is always 0, dropped lists each one with its id and a reason, and not_sealed is "unsupported_route" when you asked for reasoning.encrypted_content (otherwise null). On a stream, the counts arrive in the X-Gloo-Reasoning-Carryover header (for example received=1, carried=0, dropped=1) and the object arrives as a top-level field of the final response.completed or response.incomplete event’s data. No other event carries it, so a stream that fails before one of those two events ends without the object; the header still has the counts.
input each turn, and treat reasoning summaries as display text. If you used previous_response_id or conversation, send the earlier turns in input instead; neither parameter has an effect here, and neither do store or background.
Multimodal
Image input (vision), PDF input, image generation, and the OpenAIimage_generation tool (including image editing) work the same here as on Direct Responses: same request body, with this page’s URL. Every Claude, Gemini and Grok chat model reads images, as does every OpenAI GPT model except the open-weight GPT OSS models. See Direct Responses: Multimodal for examples, the models that can use the tool, the image models you can pick, and how images are billed.
For two worked examples (a fridge photo to a recipe, a screenshot to suggested replies), follow Understand Images with Claude; for choosing and switching models, image size and cost, see Images in Conversations.
Best practices
Pricing and token spend
The Responses API is priced at each model’s published rate plus 6.5% on every token segment, as on the other guarded endpoints and Grounded Completions. The 6.5% pays for guardrails, moderation and values alignment; there is no separate charge for/responses itself. See Direct Responses: Pricing and token spend for how token cost is calculated. Direct endpoints and Grounded Responses bill the model’s rate.
Track real spend in the Gloo Studio billing dashboard and API usage.
Supported models
The Responses API works across the full Gloo AI catalog (Anthropic, OpenAI, Google, and open-source families), including the multimodal and image-generation models. Use the Model ID as themodel field. The complete, live list (with capabilities and pricing) is on the Supported Models page.
Moving from Completions to Responses
Completions V2 (/ai/v2/guarded/chat/completions) is fully supported and backwards-compatible, and it remains the home of auto-routing, model_family selection, and grounded completions; if you need those, stay on Completions. Everything else can move to this endpoint today, keeping the same guarded pipeline and tradition.
The migration is mostly a rename: messages becomes input, the system message becomes instructions, max_tokens becomes max_output_tokens, and choices[].message.content becomes typed output[] items. For the full mapping, a side-by-side example, and the output-limit check for reasoning models, see Direct Responses: Moving from Completions to Responses, and send the request to POST /ai/v2/guarded/responses.
Coming from the retired Chat and Message API? The Chat migration guide covers moving to either endpoint.
Next steps
For model IDs, capabilities, and live pricing, see Supported Models. To reduce cost and latency with cached prompt prefixes, see Prompt Caching. For routing,model_family, and grounded completions, see Completions V2.
Step-by-step tutorial
Working examples in six languages.
Tool Use
Function calling.
Guarded Responses API reference
Every request and response field, with a live playground.

