> ## 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
> Searches publisher data in a specific collection and tenant using a query string.
**This is a semantic search endpoint.** It searches by meaning, not by exact
keyword or prefix matching. Write queries as natural language questions or
phrases for best results.
## Before You Start
This endpoint uses AI-powered **semantic search** to find content based on the
*meaning* of your query — not exact text matching. For example, a query like
"secrets to a happy marriage" will return content about "rules for keeping a
marriage healthy," even though none of the exact words overlap.
**This is not a keyword or prefix search.** Queries like `"happ"` or
`"happiness AND marriage"` will not behave as expected. Use complete,
natural-language phrases instead.
Understand how semantic search works, how to tune the certainty threshold,
and how to combine search with RAG.
Working code examples in 6 languages — JavaScript, TypeScript, Python, PHP,
Go, and Java.
Common errors: invalid collection, missing or invalid tenant, certainty threshold issues, empty query string.
### Tips for Effective Queries
* **Use natural language** — "How can I find true happiness?" works better than
"happiness find true"
* **Adjust certainty** — The default threshold is `0.75`, which is strict. If
you're getting few or no results, try lowering it to `0.5`
* **Results are ranked by semantic distance** — not keyword frequency. The
`certainty` and `distance` fields in the response indicate how closely each
result matches your query's meaning
## OpenAPI
````yaml post /ai/v1/data/search
openapi: 3.1.0
info:
title: AI API
description: |-
Optimized for high-speed inference and scalability by Gloo AI
[Swagger UI](./docs) | [ReDoc UI](./redoc)
version: 1.0.0
servers:
- url: https://platform.ai.gloo.com
security:
- bearerAuth: []
tags:
- name: Content Controls
- name: Data Engine
- name: Ingestion & Enrichment
- name: answers
- name: chat
- name: completions
- name: content
- name: core
- name: data
- name: get-models
- name: ingestion
- name: sotc
paths:
/ai/v1/data/search:
post:
tags:
- data
summary: Search publisher data
description: >-
Searches publisher data in a specific collection and tenant using a
query string.
operationId: search
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SearchPublisherDataRequestBody'
example:
query: How can I find true happiness?
collection: GlooProd
tenant: TestOrg
certainty: 0.5
limit: 1
required: true
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
title: Response Search
properties:
data:
items:
additionalProperties: true
type: object
type: array
intent:
type: integer
required:
- data
- intent
example:
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
explain_score: ''
is_consistent: false
rerank_score: null
properties:
item_title: Finding True Happiness
publisher: Test Org
publication_date: '2025-09-02'
snippet: '# Finding True Happiness: A Christian Perspective'
type: Article
item_id: 12345678-abcd-1234-abcd-1234567890aa
references: null
vector: {}
collection: GlooProd
intent: 1
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
Invalid Tenant:
summary: Invalid tenant for collection
value:
detail: >-
Unable to search tenant, InvalidTenant, in collection,
GlooProd. Please provide a valid tenant. See
https://docs.gloo.com/api-guides/search#making-requests
for information on providing a valid tenant.
Invalid Collection:
summary: Collection does not exist
value:
detail: >-
Invalid Collection. Please see
https://docs.gloo.com/api-guides/search#making-requests
for information on providing a valid collection.
Empty Tenant for Multi-Tenant Collection:
summary: Tenant required for multi-tenant collection
value:
detail: >-
Unable to search multi-tenant collection, GlooProd. Please
provide a valid tenant. See
https://docs.gloo.com/api-guides/search#making-requests
for information on providing a valid tenant.
'401':
description: Unauthorized - Missing Authorization header
content:
application/json:
schema:
additionalProperties: true
type: object
example:
error: Missing Authorization
code: unauthorized_missing_authorization
'403':
description: >-
Forbidden - Insufficient permissions or caller is not authorized to
search the requested data
content:
application/json:
schema:
additionalProperties: true
type: object
examples:
Forbidden:
summary: Insufficient permissions
value:
error: Forbidden - insufficient permissions
code: forbidden
Empty Collection:
summary: Collection is empty
value:
detail:
- type: string_too_short
loc:
- body
- collection
msg: String should have at least 1 character
input: ''
ctx:
min_length: 1
Empty Query:
summary: Query is empty
value:
detail:
- type: string_too_short
loc:
- body
- query
msg: String should have at least 1 character
input: ''
ctx:
min_length: 1
Invalid Limit:
summary: Limit below minimum
value:
detail:
- type: greater_than_equal
loc:
- body
- limit
msg: Input should be greater than or equal to 1
input: -1
ctx:
ge: 1
'422':
description: Validation Error
content:
application/json:
schema:
additionalProperties: true
type: object
example:
detail: Forbidden
'500':
description: Internal Server Error - Search failed
content:
application/json:
schema:
additionalProperties: true
type: object
example:
detail: Search failed
components:
schemas:
SearchPublisherDataRequestBody:
properties:
query:
type: string
minLength: 1
title: Query
description: Search query.
collection:
type: string
minLength: 1
title: Collection
description: Collection to search in.
tenant:
type: string
title: Tenant
description: >-
Optional tenant to search in. Required only when the selected
collection is multi-tenant; invalid when the selected collection is
not multi-tenant.
certainty:
type: number
minimum: 0
maximum: 1
title: Certainty
description: The minimum certainty threshold for snippets.
default: 0.75
limit:
type: integer
minimum: 1
title: Limit
description: Maximum number of results to return.
default: 10
type: object
required:
- query
- collection
title: SearchPublisherDataRequestBody
Error:
type: object
properties:
detail:
type: string
description: A human-readable description of the error.
title: Error
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Bearer authentication header of the form Bearer ``, where
`` is your [auth token](/studio/manage-api-credentials).
````