Skip to main content
This tutorial shows you how to build custom search functionality using the Gloo AI Search API. You’ll learn to authenticate, perform semantic search, work with rich results, and optionally combine search with Completions V2 for Retrieval Augmented Generation (RAG). Want the concepts first? Read the Concepts guide. The Search API gives you full control over search in your application, from the query to the UI, whether you’re building a knowledge base, a chatbot, or a content discovery experience. When to use this instead of Grounded Completions. Search results can serve as context for AI-generated responses. This is Retrieval Augmented Generation (RAG) — search for relevant content, then generate an answer grounded in that content. Gloo AI gives you two approaches:
  • Search API + Completions V2 (this tutorial): Full control over context, prompts, and formatting
  • Grounded Completions: Single API call, simpler but less control
Both retrieve identical content. The difference is who controls how that content is presented to the LLM. Both approaches use the same underlying search. Start with Grounded Completions if you want simplicity, then switch to Search + Completions V2 when you need more control.

What you’ll build

  • Step 1: a basic search script that returns titles, types, authors, and relevance scores
  • Step 2: a RAG flow that feeds search results to Completions V2 and returns an answer with sources
  • Optional: a browser frontend, served by a small proxy server, for trying both

Prerequisites

Before starting, ensure you have:

Working Code Sample

Follow along with complete working examples in all 6 languages (JavaScript, TypeScript, Python, PHP, Go, Java). Includes a proxy server and browser-based frontend for each language.Setup and testing instructions are below.
The code snippets in this tutorial are simplified and self-contained — designed for readability and easy copy-paste. The cookbook examples use a modular architecture plus production niceties. Both implement the same APIs and patterns.

Search API at a glance

The Search API provides AI-powered semantic search across your ingested content. Unlike keyword search, semantic search understands the meaning behind queries — so a search for “secrets to a happy marriage” will find content about “rules for keeping a marriage healthy” even without exact word matches. Endpoint: POST /ai/v1/data/search For the ideas behind it, see Embeddings (why semantic search matches meaning, not just keywords) and The Retrieval Step (how a query finds the closest matches, and how many results to keep).

Required Parameters

Tenant names are normalized. Spaces are stripped from the publisher name to form the tenant identifier — for example, Example Publisher Name becomes ExamplePublisherName. Passing the raw publisher name with spaces can cause a 400 "invalid tenant" error. To get the exact string, call GET /ai/v1/data/tenant/names and use the value returned.

Optional Parameters

The API’s default certainty is 0.75 when omitted, which is stricter than the Playground’s 0.5. If you’re getting no results, add "certainty": 0.5 to your request to match Playground behavior.
Each result in the data array contains:
Key fields:
  • metadata.certainty — Relevance score (0-1, higher = more relevant)
  • properties.snippet — Content chunk text, ideal for display or RAG context
  • properties.summaries — AI-generated summaries in multiple styles
  • properties.biblical_analysis — Bible references, concepts, and lessons (if applicable)

Test in the Playground first

Before writing code, test your queries in the Search Playground to verify your content is indexed and understand the response structure.
1

Open the Playground

Navigate to Playground in Gloo AI Studio
2

Select Search

Select the Search tab
3

Pick your publisher

Choose your publisher from the dropdown
4

Run a query

Enter a query and review the results. Try it now: Search for a topic covered in your uploaded content. The Playground displays each result with its title, snippet text, and AI-generated insights.

Start with an authenticated search request; everything that follows builds on it. Each implementation below displays results with titles, types, authors, and relevance scores.
A successful search returns results with titles, types, and relevance scores:

Key Points

  • Collection must always be "GlooProd"
  • Tenant scopes results to your publisher’s content only
  • certainty: 0.5 matches the Playground default — adjust as needed
  • Request time increases non-linearly with larger limit values

Run the Cookbook Example

The cookbook includes a ready-to-run basic search script for each language:

Step 2: Search + RAG with Completions V2

Now use search results as context for a Completions V2 answer.

2a. Plan the RAG workflow

  1. Search — Query the Search API for relevant content
  2. Extract — Pull snippets from results
  3. Format — Build context for the LLM
  4. Generate — Call Completions V2 with the context
  5. Return — Deliver the response with source citations
Steps 1-4 are the retrieve, augment and generate loop that How RAG Actually Works walks through. The Augmentation Step covers how to present retrieved snippets to the model.

2b. Implement search and generation

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.

2c. Run the RAG example

The RAG flow searches, extracts context, then generates an AI response grounded in your content:

2d. Tune the prompt and context

  • model: "gloo-anthropic-claude-opus-5.5" — Pins the model so answers stay consistent between calls. (auto_routing: true is an opt-in alternative, but the selected model can change between calls.)
  • System prompt — Customize to match your use case (tone, format, domain rules)
  • Context formatting — Source labels help the LLM cite correctly
  • Token budget — Keep context concise. 3-5 snippets of ~500 chars each works well

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, proxy servers, and a browser-based frontend.

What’s Included

Each language implementation provides:
  • auth — Shared API key configuration
  • config — Centralized configuration (URLs, env vars, RAG settings)
  • search_basic — Basic search (CLI script)
  • search_advanced — Advanced search + RAG helpers (CLI script)
  • server — Proxy server exposing REST endpoints for the frontend

Optional: try the browser frontend

The cookbook includes a browser-based frontend that connects to a proxy server, giving you a visual way to test both search and RAG. The proxy server keeps your credentials secure on the server side (see API Key Security).

Architecture

The proxy server exposes two endpoints:
  • GET /api/search?q=<query>&limit=<limit> — Basic search
  • POST /api/search/rag — Search + RAG with Completions V2

Start the Proxy Server

Each language includes a proxy server. Start one:
Then open http://localhost:3000 in your browser.

Search Results

Enter a query and click Search to see results with titles, content types, and relevance scores:
Search results showing content cards with titles, types, and relevance percentages

AI-Powered Answers (RAG)

Click Ask AI to send the same query through the RAG pipeline. The AI generates a response grounded in your search results, with sources listed:
AI response generated from search results with source citations
The frontend is language-agnostic — the same HTML/JS works with any language’s proxy server. This is one approach; customize for your branding and framework.

Troubleshooting

  • Missing certainty: Add "certainty": 0.5 to your payload. The API defaults to 0.75 when omitted, which may be too strict.
  • Content not indexed: Test in the Search Playground first. If results appear there but not via API, check your tenant name.
  • Wrong tenant: Results are scoped to your publisher. Verify the tenant name matches your publisher in Organizations. Tenant names are normalized — spaces are stripped (e.g. Example Publisher Name → ExamplePublisherName). If unsure, pull the exact string from GET /ai/v1/data/tenant/names.
  • You can only access your own publisher’s content. Other tenant names return 403.
  • A 403 may also mean your API key lacks the gateway permission for the search route (this is a separate permission from grounded completions). Contact support to provision access.
  • Verify your API key is correct and has not been revoked.
  • Reduce the limit parameter. Request time rises non-linearly with larger result sets.
  • Start with limit=10 and increase only as needed.
  • If your API key is rejected, verify it is correct and has not been revoked (see Authentication Tutorial).
  • Ensure you’re using Bearer {api_key} in the Authorization header.
  • Verify search returns results before calling Completions V2.
  • Pin a model with model (for example gloo-anthropic-claude-opus-5.5) so retries behave consistently.

Next steps

Grounded Completions

Simpler RAG approach — single API call with automatic context management.

Upload Files

Add more content to your Data Engine for richer search results.

Completions V2 API

Full control over LLM interactions with custom prompts and parameters.

Search API Reference

Complete endpoint documentation with request/response schemas.