> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Grounded Responses

> Ground Responses API answers in your own content — RAG retrieval with publisher scoping, source thresholds, and grounding signals, in the OpenAI-compatible Responses format.

The **Grounded Responses API** brings Retrieval-Augmented Generation (RAG) to the [Responses API](/api-guides/responses-v1). 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.

<Note>
  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](/api-guides/grounded-completions) on Completions V2. Grounded Responses is the grounding surface for the Responses API shape.
</Note>

## Endpoint

**URL:** `https://platform.ai.gloo.com/ai/v1/grounded/responses`

**Operation:** `POST`

```bash theme={null}
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](/studio/manage-api-credentials).

<Note>
  You must have already [uploaded content](/api-guides/upload-content) before grounding against your own publisher.
</Note>

## Request format

The request body is the [Responses API request](/api-guides/responses-v1#request-format) — `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](/studio/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](/api-guides/responses-v1#request-format).

### 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](/api-guides/responses-v1#response-format) — a typed `output[]` array plus `usage` — with one addition: a top-level `sources_returned` boolean indicating whether retrieved sources grounded the generation.

```json theme={null}
{
  "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](/api-guides/responses-v1#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):

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```python Python theme={null}
  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)
  ```

  ```typescript TypeScript theme={null}
  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);
  ```
</CodeGroup>

## Grounded Responses vs. Grounded Completions

Both endpoints run the same retrieval pipeline against the same publisher content. Choose by the API shape and features you need:

|                                         | Grounded Responses (v1)                    | [Grounded Completions](/api-guides/grounded-completions) (V2) |
| :-------------------------------------- | :----------------------------------------- | :------------------------------------------------------------ |
| Endpoint                                | `POST /ai/v1/grounded/responses`           | `POST /ai/v2/chat/completions/grounded`                       |
| Request/response shape                  | Responses API (`input` / typed `output[]`) | Chat Completions (`messages` / `choices[]`)                   |
| Model selection                         | Direct `model` only                        | `auto_routing`, `model_family`, or `model`                    |
| `rag_publisher`, `sources_limit`        | ✓                                          | ✓                                                             |
| `certainty_threshold`                   | ✓                                          | —                                                             |
| `tradition` personalization             | —                                          | ✓                                                             |
| Citation metadata (`include_citations`) | —                                          | ✓                                                             |
| Grounding signal                        | `sources_returned` / `X-Sources-Returned`  | `sources_returned` / `X-Sources-Returned`                     |

## Pricing

Grounded Responses is billed like the base Responses API — per token at the selected model's standard rates, with no separate charge for retrieval. Note that injected sources count as input tokens, so grounded requests naturally carry larger prompts than their ungrounded equivalents; `sources_limit` is your main lever over that cost. See [Responses API pricing](/api-guides/responses-v1#pricing-and-token-spend).

## Related Documentation

* [Responses API](/api-guides/responses-v1) — base request/response format, streaming events, multimodal
* [Grounded Completions](/api-guides/grounded-completions) — grounding on the chat-completions shape, with routing, `tradition`, and citations
* [Upload Content](/api-guides/upload-content) — get your publisher content into the platform
* [Search API](/api-guides/search) — standalone RAG queries without generation