> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onyx.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Search
> Run Onyx's internal search and get back ranked document sections, with no LLM answer generated.
This is the same multi-stage retrieval pipeline the chat Search action uses: query expansion, hybrid retrieval, reranking and section merging. Results are ordered most relevant first and are always filtered by the calling user's document permissions.
**Required permission:** Search — Read (`read:search`), which `basic` includes, so any signed-in user has it.
A limited [Personal Access Token](/developers/overview#personal-access-tokens) needs the Search — Read scope.
This is the endpoint to reach for when you want Onyx's search results in your own application.
It runs the same retrieval pipeline as the Search action in chat and returns ranked document sections,
without spending an LLM call on writing an answer.
The endpoint behind the Onyx Search UI is [Handle Send Search
Message](/developers/api_reference/search/handle_send_search_message), which exposes keyword expansion,
LLM document selection and streaming instead.
Results are always filtered by the calling user's document permissions,
so the same query run by two users can return different documents. A search needs a vector database:
deployments running with `DISABLE_VECTOR_DB` set (Onyx Lite) answer with `501`.
## OpenAPI
````yaml POST /search
openapi: 3.1.0
info:
title: Onyx API
description: Onyx API for AI-powered enterprise search and chat
version: Development
servers:
- url: https://cloud.onyx.app/api
security: []
paths:
/search:
post:
tags:
- public
summary: Search
description: >-
Run Onyx's internal search and get back ranked document sections, with
no LLM answer generated.
This is the same multi-stage retrieval pipeline the chat Search action
uses: query expansion, hybrid retrieval, reranking and section merging.
Results are ordered most relevant first and are always filtered by the
calling user's document permissions.
operationId: search
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SearchRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
components:
schemas:
SearchRequest:
properties:
query:
type: string
maxLength: 2048
minLength: 1
title: Query
description: The query to search for.
sources:
anyOf:
- items:
$ref: '#/components/schemas/DocumentSource'
type: array
- type: 'null'
title: Sources
description: Restrict results to these connector source types.
document_sets:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Document Sets
description: Restrict results to documents in these document sets, by name.
tags:
anyOf:
- items:
$ref: '#/components/schemas/Tag'
type: array
- type: 'null'
title: Tags
description: Restrict results to documents carrying all of these metadata tags.
time_cutoff:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Time Cutoff
description: >-
ISO 8601 timestamp. Only documents updated on or after this moment
are returned. Timestamps without a timezone are treated as UTC.
persona_id:
anyOf:
- type: integer
- type: 'null'
title: Persona Id
description: >-
Search as this Agent: its document sets, attached documents and
search start date are applied on top of the other filters, and its
LLM is used unless `provider`/`model` say otherwise.
provider:
anyOf:
- type: string
- type: 'null'
title: Provider
description: >-
Name of the LLM provider to use for query expansion and section
selection. Must be sent together with `model`, and the caller must
have access to the provider.
model:
anyOf:
- type: string
- type: 'null'
title: Model
description: Model to use from `provider`. Must be sent together with `provider`.
skip_query_expansion:
type: boolean
title: Skip Query Expansion
default: false
description: >-
When true, the query is run as written instead of being rewritten
and expanded first.
message_history:
anyOf:
- items:
$ref: '#/components/schemas/ChatMinimalTextMessage'
type: array
- type: 'null'
title: Message History
description: >-
Preceding conversation turns, used to interpret a query that depends
on earlier context. Defaults to `query` on its own.
type: object
required:
- query
title: SearchRequest
SearchResponse:
properties:
results:
items:
$ref: '#/components/schemas/SearchResult'
type: array
title: Results
type: object
required:
- results
title: SearchResponse
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
DocumentSource:
type: string
enum:
- ingestion_api
- slack
- web
- google_drive
- gmail
- github
- gitbook
- gitlab
- guru
- bookstack
- outline
- confluence
- jira
- slab
- productboard
- file
- coda
- canvas
- notion
- zulip
- linear
- hubspot
- document360
- gong
- google_sites
- zendesk
- loopio
- box
- dropbox
- sharepoint
- teams
- salesforce
- discourse
- axero
- clickup
- mediawiki
- wikipedia
- asana
- s3
- r2
- google_cloud_storage
- oci_storage
- xenforo
- not_applicable
- discord
- freshdesk
- fireflies
- egnyte
- airtable
- highspot
- drupal_wiki
- imap
- bitbucket
- testrail
- braintrust
- lumapps
- mock_connector
- user_file
- craft_file
title: DocumentSource
Tag:
properties:
tag_key:
type: string
title: Tag Key
tag_value:
type: string
title: Tag Value
type: object
required:
- tag_key
- tag_value
title: Tag
ChatMinimalTextMessage:
properties:
message:
type: string
title: Message
message_type:
$ref: '#/components/schemas/MessageType'
type: object
required:
- message
- message_type
title: ChatMinimalTextMessage
SearchResult:
properties:
citation_id:
anyOf:
- type: integer
- type: 'null'
title: Citation Id
description: >-
1-based index of the source document. Several results share one
`citation_id` when the search returned multiple non-overlapping
sections of the same document.
title:
type: string
title: Title
description: Document title.
content:
type: string
title: Content
description: Full text of the matched section.
link:
anyOf:
- type: string
- type: 'null'
title: Link
description: Link to the source document, when the connector provides one.
source_type:
type: string
title: Source Type
description: Connector source type the document came from.
updated_at:
anyOf:
- type: string
- type: 'null'
title: Updated At
description: When the document was last updated, when the connector provides it.
type: object
required:
- citation_id
- title
- content
- link
- source_type
- updated_at
title: SearchResult
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
MessageType:
type: string
enum:
- system
- user
- assistant
- tool_call_response
- user_reminder
title: MessageType
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: Authorization header with Bearer token
````