Grounded Responses

The Grounded Responses API brings Retrieval-Augmented Generation (RAG) to the Responses API. Send a standard Responses API request to the grounded endpoint, and the platform retrieves relevant passages from your uploaded content, injects them as context before generation, and tells you whether the answer was grounded — all in the same OpenAI-compatible request and response shape you already use.

If your integration is built on the chat-completions format, or you need intelligent auto-routing, tradition (values-aligned) responses, or citation metadata, use Grounded Completions on Completions V2. Grounded Responses is the grounding surface for the Responses API shape.

Endpoint

URL: https://platform.ai.gloo.com/ai/v1/grounded/responses Operation: POST

curl -X POST 'https://platform.ai.gloo.com/ai/v1/grounded/responses' \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gloo-anthropic-claude-sonnet-4.6",
    "input": [
      { "role": "user", "content": "What resources do you have on family counseling?" }
    ],
    "rag_publisher": "YourPublisherName",
    "sources_limit": 3
  }'

Authentication is identical to the rest of the platform — a Bearer access token from your Client ID / Client Secret. See Manage API Credentials.

You must have already uploaded content before grounding against your own publisher.

Request format

The request body is the Responses API request — model, input, instructions, stream, tools, and so on, unchanged — extended with three grounding parameters:

Parameter	Type	Required?	Description
`rag_publisher`	string	No	Publisher whose content grounds the response. Defaults to GlooGrounded, a shared dataset assembled by Gloo. Set it to your publisher name (see Manage Publishers) to ground in your own content. An empty value disables retrieval entirely.
`sources_limit`	integer	No	Number of sources to retrieve and inject (1–10, default: 3). More sources give broader context but increase prompt size and latency.
`certainty_threshold`	float	No	Minimum similarity (0.0–1.0) a passage must reach to be used as a source. Omit to use the platform default. Higher values keep only closely-matching sources; if nothing clears the bar, the request proceeds ungrounded (see below).

Everything else works exactly as on POST /ai/v1/responses: direct model selection via model, string or typed-array input, instructions, max_output_tokens, tools, streaming, and the rest of the request parameters.

When no sources are found

Grounding never fails the request. If retrieval returns nothing — the publisher has no matching content, or no passage clears certainty_threshold — the model is given an explicit note that no publisher sources were retrieved, generation proceeds, and the response reports sources_returned: false. Check that flag (or the streaming header) whenever your product needs to distinguish grounded answers from ungrounded ones.

Response format

The response is standard Responses API output — a typed output[] array plus usage — with one addition: a top-level sources_returned boolean indicating whether retrieved sources grounded the generation.

{
  "id": "resp_...",
  "object": "response",
  "model": "gloo-anthropic-claude-sonnet-4.6",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        { "type": "output_text", "text": "Based on your uploaded resources, here are three approaches to family counseling..." }
      ]
    }
  ],
  "usage": { "input_tokens": 1874, "output_tokens": 312, "total_tokens": 2186 },
  "sources_returned": true
}

Streaming

Set "stream": true to receive the same Server-Sent Events as the base Responses API (response.created, response.output_text.delta, response.completed, …) — see Responses API streaming for the event reference. Because the grounding outcome is known before the stream starts, it is delivered as an HTTP response header instead of a body field:

Header	Description
`X-Sources-Returned`	Whether retrieved sources grounded the response: `True` or `False`

Code examples

The official OpenAI SDKs work by pointing the base URL at the grounded prefix — responses.create then posts to /ai/v1/grounded/responses. The SDKs forward the grounding parameters to the API even though they aren’t in the SDK types: in Python pass them via extra_body; in TypeScript include them top-level with a cast (the Node SDK has no extra_body — it would be sent as a literal field):

curl -X POST 'https://platform.ai.gloo.com/ai/v1/grounded/responses' \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gloo-anthropic-claude-sonnet-4.6",
    "instructions": "Answer using the retrieved publisher sources where possible.",
    "input": [
      { "role": "user", "content": "What are practical ways to build stronger community in a local church?" }
    ],
    "rag_publisher": "YourPublisherName",
    "sources_limit": 5,
    "certainty_threshold": 0.75
  }'

from openai import OpenAI

client = OpenAI(
    api_key="your-gloo-access-token",
    base_url="https://platform.ai.gloo.com/ai/v1/grounded"
)

response = client.responses.create(
    model="gloo-anthropic-claude-sonnet-4.6",
    input=[
        {
            "role": "user",
            "content": "What are practical ways to build stronger community in a local church?"
        }
    ],
    extra_body={
        "rag_publisher": "YourPublisherName",
        "sources_limit": 5,
        "certainty_threshold": 0.75
    }
)

print(response.output_text)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'your-gloo-access-token',
  baseURL: 'https://platform.ai.gloo.com/ai/v1/grounded',
});

const response = await client.responses.create({
  model: 'gloo-anthropic-claude-sonnet-4.6',
  input: [
    {
      role: 'user',
      content:
        'What are practical ways to build stronger community in a local church?',
    },
  ],
  // Gloo grounding parameters — forwarded as-is; the cast is needed
  // because they are not in the OpenAI SDK's types
  rag_publisher: 'YourPublisherName',
  sources_limit: 5,
  certainty_threshold: 0.75,
} as OpenAI.Responses.ResponseCreateParamsNonStreaming);

console.log(response.output_text);