> ## 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.

# Search

> A developer’s guide to AI-powered semantic search for querying ingested content.

Search finds the passages in your [uploaded content](https://docs.gloo.com/api-guides/upload-content.md) that best match a question. It uses AI-based, near-text [semantic search](https://docs.gloo.com/ai-learning-center/gloo-ai-101/data-and-memory.md#semantic-search): it matches on meaning, not only on exact words. Search queries content that Gloo has ingested and indexed for you. If you manage your own vector store and retrieval, use the [Embeddings API](https://docs.gloo.com/api-guides/embeddings.md) to create vectors.

For example, say you've uploaded articles and podcasts about keeping a marriage strong, and one podcast episode covers the guest's top five rules for a healthy marriage. A search for "secrets to a happy marriage" should still find that episode, even though the episode never says "secret" and the query never says "rule". That gives your users focused, relevant access to your content, based on what they ask.

## Making Requests

### Prerequisites

First, find which publisher's content you want to query.

1. **Find Your Tenant (Publisher Name):** Go to the [Organizations page](https://docs.gloo.com/studio/manage-publishers.md) in Studio and click "View Publishers". Your **Tenant** is the name of the publisher you're querying.
2. **Identify the Collection:** A collection is where we keep customer content. Set the `collection` field to `GlooProd`, the only collection you need.
3. **Get an API key:** Create one on the [API Keys page](https://docs.gloo.com/studio/manage-api-credentials.md) and send it as a Bearer token.

> [!WARNING]
>
> You will only have access to your own publisher's tenant through this endpoint. For multi-tenant collections such as `GlooProd`, a tenant must be specified; requests outside your tenant return a 403 "Forbidden" response.
>
> **Tenant names are normalized.** Spaces and whitespace 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 tenant string, call `GET /ai/v1/data/tenant/names` and use the value returned rather than constructing it yourself.

### Send a request

With your tenant name, you can query the search endpoint.

**Endpoint:** `POST /ai/v1/data/search`

```bash cURL theme={null}
curl 'https://platform.ai.gloo.com/ai/v1/data/search' -v \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${GLOO_API_KEY}" \
  -d '{"query":"How can I find true happiness?","collection":"GlooProd","tenant": "TestOrg","certainty":0.5,"limit":1}'
```

```python Python theme={null}
import os
import requests

response = requests.post(
    "https://platform.ai.gloo.com/ai/v1/data/search",
    headers={
        "Authorization": f"Bearer {os.environ['GLOO_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "query": "How can I find true happiness?",
        "collection": "GlooProd",
        "tenant": "TestOrg",
        "certainty": 0.5,
        "limit": 1,
    },
)

for result in response.json()["data"]:
    print(result["properties"]["item_title"], result["metadata"]["certainty"])
```

```typescript TypeScript theme={null}
const response = await fetch('https://platform.ai.gloo.com/ai/v1/data/search', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.GLOO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: 'How can I find true happiness?',
    collection: 'GlooProd',
    tenant: 'TestOrg',
    certainty: 0.5,
    limit: 1,
  }),
});

const { data } = await response.json();
for (const result of data) {
  console.log(result.properties.item_title, result.metadata.certainty);
}
```

For a step-by-step build, follow the [Search tutorial](https://docs.gloo.com/tutorials/search.md).

### Example Response

Each result in `data` is one snippet. This excerpt shows the fields you'll use most:

```json JSON theme={null}
{
  "data": [
    {
      "uuid": "12345678-abcd-1234-abcd-1234567890ab",
      "metadata": {
        "distance": 0.39595216512680054,
        "certainty": 0.8020238876342773
      },
      "properties": {
        "item_title": "Finding True Happiness",
        "publisher": "Test Org",
        "type": "Article",
        "publication_date": "2025-09-02",
        "author": ["Automated Ingestion"],
        "snippet": "# Finding True Happiness: A Christian Perspective  In a world obsessed with pursuing happiness...",
        "summaries": {
          "ai_simple": "True happiness comes from knowing we are God's children, not from things or success in the world."
        }
      },
      "collection": "GlooProd"
    }
  ],
  "intent": 1
}
```

* `metadata.certainty` and `metadata.distance` show how closely the snippet matches the meaning of your query.
* `properties.snippet` is the matching text. The other `properties` describe the item it came from: title, author, publisher, type, tags, URLs, and section (`h2_*`, `h3_*`) details.
* `properties` also carries AI-generated enrichment for the item: `summaries` (the same item summarized in several styles), `biblical_analysis` (Bible references, characters, concepts), and `general_analysis` (keywords, topics, personas, reading time, and more). Fields can be empty or `null` when the item has no value for them.

> [accordion] Full example response
>
> ```json JSON theme={null}
> {
>     "data": [
>         {
>             "uuid": "12345678-abcd-1234-abcd-1234567890ab",
>             "metadata": {
>                 "creation_time": "2025-09-02T23:49:49.338000Z",
>                 "last_update_time": "2025-09-02T23:50:36.348000Z",
>                 "distance": 0.39595216512680054,
>                 "certainty": 0.8020238876342773,
>                 "score": 0.0,
>                 "explain_score": "",
>                 "is_consistent": false,
>                 "rerank_score": null
>             },
>             "properties": {
>                 "pub_type": "technical",
>                 "item_file": "",
>                 "h3_subtitle": "",
>                 "item_tags": [
>                     "automated",
>                     "ingestion"
>                 ],
>                 "screen_cap": "",
>                 "h2_subtitle": "",
>                 "publisher_bw": null,
>                 "item_title": "Finding True Happiness",
>                 "publisher_hierarchy_fav": null,
>                 "publisher_hierarchy": null,
>                 "evergreen": true,
>                 "h2_id": "",
>                 "organization": null,
>                 "h3_image": "",
>                 "denomination": "",
>                 "producer_id": "",
>                 "time_start": "",
>                 "publisher": "Test Org",
>                 "publisher_logo": null,
>                 "h2_title": "",
>                 "h2_number": "",
>                 "publisher_hierarchy_bw": null,
>                 "duration": "",
>                 "h3_id": "",
>                 "pages": "",
>                 "publisher_hierarchy_logo": null,
>                 "filename": "Finding_True_Happiness_realtime",
>                 "h2_url": "",
>                 "time_end": "",
>                 "drm": null,
>                 "h3_title": "",
>                 "h3_url": "",
>                 "item_extra": "",
>                 "item_image": "",
>                 "item_id": "",
>                 "isbn": "",
>                 "h3_file": "",
>                 "hosted_url": "",
>                 "organization_id": "",
>                 "h3_number": "",
>                 "publisher_fav": null,
>                 "publication_date": "2025-09-02",
>                 "publisher_url": "",
>                 "h2_image": "",
>                 "publisher_id": "",
>                 "item_number": "",
>                 "h2_file": "",
>                 "item_subtitle": "",
>                 "h2_extra": "",
>                 "h3_summary": "",
>                 "h2_summary": "",
>                 "snippet": "# Finding True Happiness: A Christian Perspective  In a world obsessed with pursuing happiness through material success, relationships, and experiences, Christianity offers a radically different path to lasting joy. True happiness, from a biblical worldview, isn't found in circumstances but in our relationship with God and alignment with His purposes.  ## Joy Rooted in Identity  The foundation of Christian happiness begins with understanding our identity as beloved children of God. Romans 8:16 reminds us that \"The Spirit himself testifies with our spirit that we are God's children.\" This secure identity provides unshakeable joy that doesn't depend on external validation, achievements, or circumstances. When we truly grasp that we are unconditionally loved by the Creator of the universe, a deep contentment settles in our hearts.  ## The Beatitudes: God's Blueprint for Blessedness",
>                 "part": 0,
>                 "h3_extra": "",
>                 "item_url": "",
>                 "type": "Article",
>                 "start_index": 0,
>                 "publisher_hierarchy_url": null,
>                 "item_summary": "",
>                 "author": [
>                     "Automated Ingestion"
>                 ],
>                 "summaries": {
>                     "ai_phd_student": "This discourse analyzes the theological framework of eudaimonia within Christian doctrine, particularly examining the correlation between divine filial relationship and authentic happiness.",
>                     "ai_loving": "Beloved, discover the beautiful truth that your happiness is secured in being God's precious child, far beyond what this world can offer.",
>                     "ai_news_anchor": "In today's discussion, we explore the Christian perspective on happiness, highlighting how spiritual identity trumps material success in achieving lasting joy.",
>                     "ai_elegant": "An exploration of authentic happiness through the Christian paradigm, emphasizing the profound connection between divine identity and genuine joy.",
>                     "ai_simple": "True happiness comes from knowing we are God's children, not from things or success in the world.",
>                     "ai_casual": "Hey, this piece talks about how real happiness isn't about stuff or success, but about knowing you're God's child and finding joy in that relationship.",
>                     "ai_first_grader": "God loves us very much and that makes us happy. Being God's children is better than having toys or things to make us happy.",
>                     "ai_creative": "Journey into the heart of happiness through heaven's lens, where joy blooms not in earthly gardens but in the fertile soil of divine identity.",
>                     "ai_formal": "This text examines the theological perspective on authentic happiness, emphasizing its foundation in divine sonship rather than material or circumstantial factors.",
>                     "ai_biblical": "The text explores the Christian understanding of true happiness as rooted in our identity as God's children, contrasting worldly pursuits with spiritual joy found in relationship with God."
>                 },
>                 "biblical_analysis": {
>                     "ai_biblical_concepts": [
>                         "Divine adoption",
>                         "Spiritual identity",
>                         "Beatitudes",
>                         "Kingdom happiness"
>                     ],
>                     "ai_bible_characters": [
>                         "Jesus"
>                     ],
>                     "ai_bible_references": [
>                         "Romans 8:16"
>                     ],
>                     "ai_book_of_the_bible": "Romans",
>                     "ai_bible_phrases": [
>                         "we are God's children"
>                     ],
>                     "ai_bible_concepts": [
>                         "Identity in Christ",
>                         "Divine Sonship",
>                         "Joy",
>                         "Contentment"
>                     ],
>                     "ai_biblical_lesson": "True happiness is found in understanding and embracing our identity as children of God rather than pursuing worldly sources of satisfaction.",
>                     "ai_bible_verses": [
>                         "The Spirit himself testifies with our spirit that we are God's children"
>                     ]
>                 },
>                 "general_analysis": {
>                     "ai_profile_gender": "Not targeted to a specific gender",
>                     "ai_personas": [
>                         "Spiritual seekers",
>                         "Christians seeking growth",
>                         "People questioning happiness"
>                     ],
>                     "ai_keywords": [
>                         "happiness",
>                         "joy",
>                         "identity",
>                         "contentment",
>                         "Christianity"
>                     ],
>                     "ai_topic_classification": "Christian Spiritual Formation",
>                     "ai_reading_duration": 3.0,
>                     "ai_read_more_suggestion": [
>                         "Understanding the Beatitudes",
>                         "Identity in Christ",
>                         "Biblical Joy"
>                     ],
>                     "ai_famous_quotes": [],
>                     "ai_meta_description": "Explore the Christian perspective on finding true happiness through understanding your identity as God's child rather than worldly success.",
>                     "ai_scripture_parallels": [
>                         "Psalm 16:11 - Joy in God's presence",
>                         "Philippians 4:4 - Rejoicing in the Lord"
>                     ],
>                     "ai_user_activity": "Reading time: 3 minutes, Ideal for morning devotional",
>                     "ai_hashtags": [
>                         "ChristianJoy",
>                         "TrueHappiness",
>                         "IdentityInChrist",
>                         "BiblicalTruth"
>                     ],
>                     "ai_user_interests": [
>                         "Christianity",
>                         "Spiritual growth",
>                         "Personal development",
>                         "Biblical teaching"
>                     ],
>                     "ai_profile_alignment": [
>                         "Christian believers",
>                         "Spiritual seekers",
>                         "Personal development enthusiasts"
>                     ],
>                     "ai_why_bullets": [
>                         "Provides an alternative to materialistic views of happiness",
>                         "Offers lasting joy independent of circumstances",
>                         "Establishes secure identity foundation"
>                     ],
>                     "ai_interactive_callout": "Take a moment to reflect on what truly brings you lasting joy",
>                     "ai_user_retention_tip": "Subscribe to receive weekly devotionals on finding joy in Christ",
>                     "ai_complexity": 7.0,
>                     "ai_life_issues": [
>                         "identity",
>                         "happiness",
>                         "contentment",
>                         "purpose"
>                     ],
>                     "ai_mood_board": "Soft, warm colors, peaceful natural settings, uplifting imagery of light and hope",
>                     "ai_important_phrase": "True happiness isn't found in circumstances but in our relationship with God",
>                     "ai_search_snippet": "Discover how Christianity offers a unique perspective on finding lasting happiness through spiritual identity rather than material success.",
>                     "ai_subtitle": "Discovering Lasting Joy in Divine Identity",
>                     "ai_thriving": [
>                         "spiritual fulfillment",
>                         "emotional stability",
>                         "identity security"
>                     ],
>                     "ai_intent": "educational",
>                     "ai_sentiment": "positive",
>                     "ai_audio_snippet": "Gentle, contemplative background music with soft piano",
>                     "ai_title_variations": [
>                         "The Christian Path to Lasting Joy",
>                         "God's Blueprint for True Happiness",
>                         "Finding Joy in Divine Identity"
>                     ],
>                     "ai_poll_question": "What do you believe is the primary source of lasting happiness?",
>                     "ai_emotional_resonance": [
>                         "hope",
>                         "peace",
>                         "contentment",
>                         "security"
>                     ],
>                     "ai_next_steps": [
>                         "Reflect on your identity as God's child",
>                         "Study the Beatitudes",
>                         "Evaluate your sources of happiness"
>                     ],
>                     "ai_reader_impact": "Transformed perspective on happiness and personal identity",
>                     "ai_books_mentioned": [],
>                     "ai_music_recommendation": "Contemporary Christian worship music focusing on joy and identity",
>                     "ai_reader_motivation": "Seeking authentic, lasting joy beyond material success",
>                     "ai_readability": 8.0,
>                     "ai_sharing_probability": 0.7,
>                     "ai_engagement_score": 8.0,
>                     "ai_terminology_definitions": [
>                         "Beatitudes: Jesus teachings on true happiness and blessedness"
>                     ],
>                     "ai_google_search": [
>                         "Christian perspective on happiness",
>                         "finding true joy in God",
>                         "identity in Christ"
>                     ],
>                     "ai_conversion_potential": "High potential for newsletter signups and devotional subscriptions",
>                     "ai_sharing_message": "Find out why true happiness goes deeper than circumstances and success",
>                     "ai_tweet": "True happiness isn't found in what we have or do, but in who we are - beloved children of God.",
>                     "ai_song_lyric": "In Your presence there is fullness of joy",
>                     "ai_famous_people": [],
>                     "ai_search_engine_tags": [
>                         "Christian happiness",
>                         "biblical joy",
>                         "spiritual identity",
>                         "finding true contentment"
>                     ],
>                     "ai_ad_placement_opportunity": "Christian counseling services, spiritual growth resources",
>                     "ai_describing_words": [
>                         "radically",
>                         "different",
>                         "lasting",
>                         "unshakeable",
>                         "deep"
>                     ],
>                     "ai_reader_takeaway": "True happiness comes from understanding and embracing our identity as God's children",
>                     "ai_content_clusters": [
>                         "Christian Living",
>                         "Spiritual Growth",
>                         "Biblical Teaching",
>                         "Personal Development"
>                     ],
>                     "ai_title": "Finding True Happiness: A Christian Perspective",
>                     "ai_questions_answered": [
>                         "Where can true happiness be found?",
>                         "What is the Christian perspective on happiness?"
>                     ],
>                     "ai_comment_prompt": "How has your understanding of happiness changed through your spiritual journey?",
>                     "ai_standalone": "high",
>                     "ai_social_media_caption": "Discover the secret to lasting happiness through understanding your identity as God's beloved child.",
>                     "ai_key_statistics": [],
>                     "ai_quiz_question": "According to the text, what is the foundation of Christian happiness?",
>                     "ai_meta_keywords": [
>                         "Christian happiness",
>                         "spiritual joy",
>                         "identity in Christ",
>                         "biblical contentment"
>                     ],
>                     "ai_christian_topics": [
>                         "Identity in Christ",
>                         "Biblical Joy",
>                         "Divine Sonship",
>                         "Beatitudes"
>                     ],
>                     "ai_image_prompt": "A serene landscape with rays of sunlight breaking through clouds, symbolizing divine love and joy",
>                     "ai_feedback_request": "Has this article helped you understand the Christian perspective on happiness?",
>                     "ai_why_matter": "Understanding true happiness from a Christian perspective can transform how we approach life satisfaction and personal fulfillment.",
>                     "ai_flourishing": [
>                         "spiritual growth",
>                         "emotional wellbeing",
>                         "identity security"
>                     ],
>                     "ai_traffic_prediction": 0.8
>                 }
>             },
>             "references": null,
>             "vector": {},
>             "collection": "GlooProd"
>         }
>     ],
>     "intent": 1
> }
> ```

## Key options

| Field | Type | Default | What it does |
| :- | :- | :- | :- |
| `query` | string | — | Your question or search text. Matched on meaning, not only exact words. |
| `collection` | string | — | Where customer content is kept. Always `GlooProd`. |
| `tenant` | string | — | Your publisher (tenant) name, as returned by `GET /ai/v1/data/tenant/names`. |
| `certainty` | float (0-1) | `0.75` | Minimum relevance threshold. The [Search Playground](https://docs.gloo.com/studio/playground-search.md) defaults to `0.5`; if you get no results, add `"certainty": 0.5` to match it. |
| `limit` | integer | `10` | How many results to return. |

### How many records can I retrieve?

We recommend 10 to 100 results; request time rises non-linearly with larger result sets. Set the number with the `limit` field.

## Snippets and RAG

Use Search to see how your content shows up through Gloo AI and to bring it into your own applications. The API returns snippets: the same pieces Gloo AI's chat tools draw on.

A **snippet** is a section of a content item (a podcast episode, article or book) large enough to carry a meaningful piece of information on its own. Each snippet is one searchable unit of your content.

Sometimes an AI application needs to give the model extra context. With [Retrieval Augmented Generation](https://docs.gloo.com/ai-learning-center/gloo-ai-103/how-rag-actually-works.md), you add search results to the message you send the model, so its answer draws on your content and fits your users' questions.

See the [Search API reference](https://docs.gloo.com/api-reference/data/search-publisher-data.md) for every request field. The response fields vary by collection.

## Next steps

To turn search results into answers people can check, see [Building Trustworthy Grounded Applications](https://docs.gloo.com/best-practices/trustworthy-grounded-applications.md). Search quality starts at upload: see [Preparing Content for Ingestion](https://docs.gloo.com/best-practices/ingestion-pattern.md).

> [card] [Step-by-step tutorial](https://docs.gloo.com/tutorials/search.md)
>
> Build custom search with code in six languages.

> [card] [Search Playground](https://docs.gloo.com/studio/playground-search.md)
>
> Try queries in Studio before writing code.

> [card] [Grounded Responses](https://docs.gloo.com/api-guides/grounded-responses.md)
>
> Have the model answer from what Search finds.

> [card] [API Reference](https://docs.gloo.com/api-reference/data/search-publisher-data.md)
>
> Request and response details.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.