Skip to main content
The Gloo Grounded Completions API is Completions V2 with Retrieval-Augmented Generation (RAG) added. Before the model answers, Gloo looks up relevant passages in content you’ve uploaded and gives them to the model, so its answer draws on your own sources. Use it when answers should come from specific content rather than only from the model’s training. Set rag_publisher to your publisher name and the API handles retrieval, grounding, and attribution. As on Completions V2, you get three model-selection options (direct model choice, model family selection, or opt-in auto-routing) plus tradition-based personalization and input guardrails, with responses informed by sources retrieved from your content.
Grounded completions (RAG) and model-family and auto-routing selection are Completions V2 features. For general, OpenAI-compatible model access, use Direct Responses with nothing added, or the guarded Responses API for Gloo’s guardrails and tradition; RAG grounding in the Responses format is available via Grounded Responses.

Prerequisites

You need:
  • A Gloo AI Studio account
  • Your API key from the API Keys page
  • Authentication setup - Complete the Authentication Tutorial first
  • Content uploaded to your publisher: upload your content before using grounded completions with your publisher
  • For the Python example: the requests library (pip install requests). The TypeScript example uses the built-in fetch (Node 18+).

Quick start

The grounded endpoint has its own base URL, https://platform.ai.gloo.com/ai/v2/grounded. Because OpenAI-compatible SDKs append /chat/completions, you can point an SDK client at that base URL when specifying a model. For requests that use auto_routing or model_family without a model, use a direct HTTP request instead because the SDK requires model client-side.
For a step-by-step build, follow the Grounded Completions tutorial: build a grounded chatbot with working code.

Why Grounded Completions?

Grounded completions keep answers tied to your content:
Grounding reduces fabrication; it does not verify that a given sentence appears in the retrieved sources. If your application serves quotations, titles, or attributions, check the answer against its sources before display. See Building Trustworthy Grounded Applications.

Request Parameters

The request takes the Completions V2 fields plus the RAG fields below: For every parameter, see the Grounded Completions API reference.

RAG Configuration

Using Your Own Content

Set the rag_publisher parameter to your publisher name to ground responses in your uploaded content:
The model only retrieves and references content from that publisher. Find your publisher name on the Publishers page in Studio. If you omit the rag_publisher parameter, the API falls back to GlooGrounded, a shared dataset assembled by Gloo. For best results, always specify your own publisher.

Source Limits

Control how many sources are retrieved and considered with the sources_limit parameter (1-10, default is 3):
More sources give broader context but increase processing time. 3 sources work well for most queries; complex theological questions may benefit from more. Each source is one chunk of content, so the chunk size your content was uploaded with also sets how much text each source adds.

Include Citations

Include citation metadata for sources used by RAG (defaults to false)
For streaming responses, citations are prepended to the response in this format:

Tradition-Based Personalization

Customize responses to align with specific theological perspectives using the tradition parameter:
Supported traditions:
  • "evangelical" - Evangelical Protestant perspective
  • "catholic" - Roman Catholic perspective
  • "mainline" - Mainline Protestant perspective
  • "not_faith_specific" - Neutral, non-faith-specific perspective (uses Gloo’s non-faith-specific prompt rather than a Christian tradition). Requires an explicit model and cannot be combined with auto_routing or model_family.
When specified, both RAG retrieval and generation adapt to the tradition, steering the language, concepts, and emphases of the answer.

Response Format

Non-Streaming Response

The response is a Completions V2 chat.completion object with grounding metadata added. An excerpt:
sources_returned tells you whether retrieved content grounded the answer. citations appears only when you set include_citations: true. With a reasoning_effort, message can also carry reasoning_content; see Reasoning.

Streaming Response

When stream: true, responses are sent as Server-Sent Events. Routing and RAG metadata is provided in HTTP headers: When include_citations: true is set and sources are found, a citations event is the first SSE chunk, before any model content (see Include Citations). With a reasoning_effort other than none, delta.reasoning_content chunks arrive before the answer. For every response field, see the Grounded Completions API reference. For streaming implementation guidance, see Completions V2.

Next steps

Step-by-step tutorial

Build a grounded chatbot with working code.

Building Trustworthy Grounded Applications

Verifying answers against sources, prompt contracts, multi-turn handling, and evaluation.

Grounded Responses

The same RAG grounding in the Responses API format.

API Reference

Every request and response field, with a live playground.
Also see: the Completions V2 API for core routing mechanisms and streaming details, the Search API for standalone RAG queries without generation, the Tool Use Guide for using function calling with grounded completions, Supported Models for model capabilities and context windows, and how to evaluate grounded answers.