Skip to main content
From time immemorial, well let’s say late 2022, we’ve all had the experience of AI models confidently responding to a question with nonsense or made-up facts. That’s a term known as “hallucinating”. It happens when models lack the knowledge needed and are incentivized to try and be helpful. At other times, their responses are simply vague and unhelpful. Want the concepts first? Read the Concepts guide. The good news? There’s a fix! This tutorial shows how to use Gloo AI’s Grounded Completions API with RAG (Retrieval-Augmented Generation) to give your AI the right context.
Key Problem: Without grounding, AI models may hallucinate answers about your organization, products, or services.The Solution: Grounded Completions uses RAG to retrieve relevant content from YOUR publisher before generating responses, turning generic AI into an accurate, source-backed assistant.

Prerequisites

You need:
  • A Gloo AI Studio account
  • Your API key from the API Keys page. Keep it on your server and out of source control; see API Key Security
  • A Publisher created with content uploaded in Gloo Studio
  • PHP 8.0 or later, if you follow the PHP examples
New to Publishers? Check out the Upload Files to Data Engine recipe to learn how to create a Publisher and upload your documents using Gloo AI APIs.

What you’ll build

A comparison of non-grounded and grounded answers that shows you how RAG grounding works, in four steps:
  1. Understand the hallucination problem (Step 1): A non-grounded request uses generic model knowledge and may hallucinate
  2. Ground on your publisher (Step 2): A grounded request uses your specific content, accurate and source-backed
  3. Compare side by side (Step 3): Run both approaches in one function
  4. Test your implementation (Step 4): Validate your setup with the Bezalel example, then adapt the code to your own content

Example: Bezalel Ministries

For this tutorial, we’ve cooked up a fictional organization called Bezalel Ministries. They’re a faith-based creative group who produce biblically-accurate artwork and educational resources. They’re delightful. We’ve created 5 sample documents covering everything from their hiring process to their educational programs and research methodology. Why a made-up org? It shows exactly how the API works without real-world baggage. Plus, Bezalel Ministries is more interesting than “Company X” or “Acme Corp”. What the comparison reveals:
  • Step 1 (Non-grounded): Generic hiring advice with no knowledge of Bezalel
  • Step 2 (Publisher grounded): Accurate details about Bezalel’s 3-phase selection journey from their actual docs

Working Code Sample

Follow along with complete working examples in all 6 languages (JavaScript, TypeScript, Python, PHP, Go, Java). Includes the 5 Bezalel sample content files.Setup and testing instructions are below.

Step 1: Understanding the Hallucination Problem

Without grounding, when you ask about specific organizational information, the model relies on general knowledge and may:
  • Provide generic answers that don’t match your reality
  • Make up plausible-sounding but incorrect information
  • Say “I don’t have information” even though you’ve uploaded relevant content
The Problem RAG Solves explains why models fill gaps with confident guesses, and how retrieval helps.
Grounding narrows this problem substantially, but it does not close it. A grounded answer can still contain a quotation or a resource title that appears in none of the retrieved sources. Production applications add a verification step between generation and display. See Building Trustworthy Grounded Applications.

The Non-Grounded Request

This is a standard Completions V2 call:
Claude Opus 5.5 is a reasoning model: its thinking and its answer share max_tokens. These examples set 8,192 so there’s room for both. See Set your output limit for reasoning models for sizing.
What you’ll see: A generic response about hiring processes, or possibly “I don’t have specific information about Bezalel Ministries.” The model doesn’t know about your organization because it wasn’t trained on your content.

Step 2: Grounding on Your Publisher

Now ground the request on YOUR specific content.

The Publisher Grounded Request

This adds two key changes from Step 1: the /grounded endpoint and the rag_publisher parameter:
What you’ll see: A detailed, accurate response about Bezalel’s specific 3-phase selection journey, pulled directly from their uploaded content. The sources_returned: true flag confirms RAG found and used relevant sources.
Why this query works: The Bezalel publisher contains a document titled “bezalel_hiring_process.txt” that describes their selection journey in detail. When you ground on this publisher, the RAG system retrieves this document before generating the response.For your own use case, design queries that match your uploaded content. If you upload product documentation, ask product questions. If you upload HR policies, ask HR questions.

Side-by-Side Comparison

Different content types require different query approaches:Key Pattern: Your queries should directly relate to the information in your uploaded documents.

Step 3: Comparing Side-by-Side

The clearest way to show RAG’s value is to compare both approaches in one function:

Example Output


Step 4: Test your implementation

This tutorial provides two testing paths:
  1. Quick Start (Recommended): Test the Bezalel example to validate your setup
  2. Your Own Content: Adapt the code to use your publisher and content

Phase 1: Quick Start with Bezalel Example

First, run the provided Bezalel example to validate your setup.
1

Set up

  1. Install dependencies for your language (see cookbook READMEs)
  2. Configure .env with your credentials:
  3. Create the Bezalel publisher in Gloo Studio:
    • Create a new publisher named “Bezalel” (exact name, case-sensitive)
    • Upload the 5 sample content files from the cookbook’s content/ directory
    • Wait for all documents to show “Completed” status before proceeding
2

Run the comparison

Each language implementation includes a ready-to-run comparison demo:
3

Check what to look for

When testing with ANY publisher (Bezalel or your own):✅ Step 1 (Non-grounded):
  • Generic response not specific to your content
  • Example: “A typical hiring process involves…” (for any hiring query)
✅ Step 2 (Publisher grounded):
  • Specific, accurate information from YOUR uploaded documents
  • sources_returned: true (if this is false, see troubleshooting)
  • Example: For Bezalel → “3-phase selection journey with calling alignment…”
  • Example: For your product docs → “The enterprise plan is $X/month and includes…”
If Step 2 fails or returns generic responses, see the Troubleshooting section.

Phase 2: Adapt to Your Own Content

Once the Bezalel example works, adapt it to your own use case.
1

Prepare your content

Before modifying code, ensure you have:
  1. Created a Publisher in Gloo Studio
  2. Uploaded relevant documents (PDFs, text files, Word docs, etc.)
    • Upload content that answers the questions your users will ask
    • Example: HR policies for HR questions, product docs for product questions
  3. Note your Publisher name (you’ll need this for the code)
Content Quality Matters: The more relevant and well-structured your content, the better your grounded responses will be. Each document should focus on a specific topic area.
2

Update the code

Modify two areas in the code:A. Update Environment VariablesIn your .env file:
B. Update QueriesDesign queries that match your uploaded content:
3

Run and validate

Run your modified code using the same commands from Phase 1.Interpreting Results:✅ Success indicators:
  • Step 2 shows sources_returned: true
  • Step 2 response contains specific information from your documents
  • Step 2 is noticeably more accurate than Step 1
⚠️ If Step 2 is generic or wrong:
  • Check that your publisher name matches exactly (case-sensitive)
  • Verify content is uploaded and indexed in Studio
  • Ensure your queries are relevant to your content
  • Try increasing sources_limit (change 3 to 5 or 10)
4

Refine your queries

If results aren’t accurate:
  1. Make queries more specific: “What is the pricing?” → “What is the enterprise plan pricing for annual subscriptions?”
  2. Match content structure: If your document is titled “Installation Guide,” ask installation questions
  3. Test incrementally: Start with one query, verify it works, then add more
  4. Check sources: If available in the API response, inspect which documents were retrieved
Iterative Testing: RAG quality improves with iteration. Test different queries, refine your content, and adjust sources_limit until you get optimal results.

Complete code

View Complete Code

Clone or browse the complete working examples for all 6 languages (JavaScript, TypeScript, Python, PHP, Go, Java) with setup instructions and Bezalel content files.

Troubleshooting

Solutions:
  • Verify publisher name is exact match (case-sensitive) to Studio
  • Confirm publisher exists at Gloo Studio
  • Check you’re using the correct account/credentials
Solutions:
  • Verify content is uploaded to the publisher you named in rag_publisher, and has finished indexing in Studio
  • For the full checklist (indexing status, query fit, sources_limit), see When Grounding Looks Wrong
Solutions:
  • Verify GLOO_API_KEY is correct
  • Get a fresh API key from the API Keys page
If Step 2 (publisher grounded) responses still seem generic:
  • Check sources_returned flag—should be true for Step 2
  • Verify you’re using the rag_publisher parameter
  • For content and query checks, see When Grounding Looks Wrong
If Step 2 returns sources_returned: false or generic responses:Check Publisher Name:
  • Publisher names are case-sensitive: “MyPublisher” ≠ “mypublisher”
  • Verify exact name in Gloo Studio
  • Check for typos in your code or .env file
Check your content and queries: indexing status, query-content mismatch, sources_limit, and content quality are covered in When Grounding Looks Wrong.

Take it further

Extend this recipe:
  • Add streaming for real-time responses
  • Implement conversation history
  • Extract and display source citations
  • Verify answers against their sources before displaying them
  • Handle edge cases (no sources found, publisher not found)
  • Add user feedback collection
Advanced features:
  • Adjust source limits: Use sources_limit to control how many documents are retrieved
  • Search without generation: Use the Search API for RAG without completion
  • Multi-turn conversations: Maintain context across multiple grounded queries
  • Hybrid approaches: Mix grounded and non-grounded based on query type

Next steps

To use your own content, follow Phase 2: Adapt to Your Own Content above to prepare and upload your content, update the code for your publisher, design effective queries, and validate and refine your results.

Build Trustworthy Grounded Applications

Verify answers against their sources before displaying them.

Upload Files Tutorial

Set up Publishers and upload documents.

Completions V2 API Guide

Complete API documentation.

How RAG Actually Works

The retrieve, augment, generate steps behind this tutorial.