Skip to main content
The Responses API (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/guarded and call responses.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 tradition parameter 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 input array and typed output[] 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 opaque choices[].message.content string, 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
Responses v1 is deprecated. POST /ai/v1/responses is deprecated in favor of v2 but keeps working. It behaves like the direct endpoint (no guardrails, no output moderation), so the behavior-preserving migration is a URL change to POST /ai/v2/direct/responses. Errors on the direct endpoint follow the direct endpoint error contract; POST /ai/v1/responses keeps its existing error responses. For guardrails, values-aligned tradition responses, and output moderation, use POST /ai/v2/guarded/responses. That changes behavior: unsafe requests and replies are refused or replaced, and the guarded platform price applies. The two endpoints take the same request body. One exception: grounded responses (RAG with source attribution) remain served by the v1 family at POST /ai/v1/grounded/responses. See Endpoint types to choose.
Send your API key as a Bearer token, as on the rest of the platform. See Generate API Keys.

Request format

The Responses API uses input 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 and model_family are 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 has status: "incomplete". See Set your output limit for reasoning models.
  • reasoning: see Reasoning summaries.
For every parameter, see the Guarded Responses API reference.
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 message item in output[] carrying the static text. Your client needs no special handling.
  • Hard blocks. Requests that guardrails reject outright return the same 403 error 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 typed output[] 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:
Key event types to handle:
  • response.created: emitted once at the start of the response.
  • response.output_text.delta / response.output_text.done: incremental text tokens for a message item.
  • response.output_item.added / response.output_item.done: emitted for typed items in output[] (including function_call).
  • response.completed: emitted once when the response is finished. Its payload is the response’s top-level fields (id, object, status, usage and the request settings), not nested under a response key, and without output[]: 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 at max_output_tokens ends with response.incomplete instead, 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.
Streams can fail after the response has started; see Handling Streaming Failures for retry, continuation, and partial-output guidance.

Reasoning summaries

Set reasoning.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 a reasoning 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 id and a summary, never encrypted_content. Asking for include: ["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 every reasoning item you send before calling the model, including an item sent back exactly as this endpoint returned it, with no encrypted_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 include request for reasoning, are unchanged.
When your 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.
The fields and reasons are described in Direct Responses: Reasoning across turns. What to do: keep sending the full conversation in 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 OpenAI image_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

The guarded best practices apply here with the Responses field names: your task goes in instructions, your user’s text in input, and JSON comes back from a forced function_call. See Building with Guarded Endpoints, including the suggested replies example on this endpoint.

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 the model 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.