- Search API + Completions V2 (this tutorial): Full control over context, prompts, and formatting
- Grounded Completions: Single API call, simpler but less control
Compare Search + Completions V2 with Grounded Completions
Compare Search + Completions V2 with Grounded Completions
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:- 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
- Your Tenant (publisher) name from Organizations in Studio. Tenant names are normalized (spaces stripped) — see Search API at a glance below, or pull the exact string from
GET /ai/v1/data/tenant/names. - Content uploaded to the Data Engine (see Upload Files Tutorial)
- Authentication setup — Complete the Authentication Tutorial first
- PHP 8.0 or later, if you follow the PHP examples
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.
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
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.Response structure
Response structure
Each result in the Key fields:
data array contains:metadata.certainty— Relevance score (0-1, higher = more relevant)properties.snippet— Content chunk text, ideal for display or RAG contextproperties.summaries— AI-generated summaries in multiple stylesproperties.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.
Step 1: Basic Search
Start with an authenticated search request; everything that follows builds on it. Each implementation below displays results with titles, types, authors, and relevance scores.What you'll see
What you'll see
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.5matches the Playground default — adjust as needed- Request time increases non-linearly with larger
limitvalues
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
- Search — Query the Search API for relevant content
- Extract — Pull snippets from results
- Format — Build context for the LLM
- Generate — Call Completions V2 with the context
- Return — Deliver the response with source citations
2b. Implement search and generation
2c. Run the RAG example
What you'll see
What you'll see
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: trueis 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 configurationconfig— 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
GET /api/search?q=<query>&limit=<limit>— Basic searchPOST /api/search/rag— Search + RAG with Completions V2
Start the Proxy Server
Each language includes a proxy server. Start one:http://localhost:3000 in your browser.
Search Results
Enter a query and click Search to see results with titles, content types, and relevance scores:
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:
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
No Results Returned
No Results Returned
- Missing
certainty: Add"certainty": 0.5to your payload. The API defaults to0.75when 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
tenantname. - 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 fromGET /ai/v1/data/tenant/names.
403 Forbidden
403 Forbidden
- 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.
Slow Responses
Slow Responses
- Reduce the
limitparameter. Request time rises non-linearly with larger result sets. - Start with
limit=10and increase only as needed.
Authentication Errors
Authentication Errors
- 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.
Empty RAG Responses
Empty RAG Responses
- Verify search returns results before calling Completions V2.
- Pin a model with
model(for examplegloo-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.

