Skip to main content
POST
Search
Required permission: Search — Read (read:search), which basic includes, so any signed-in user has it. A limited Personal Access Token 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, 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.

Authorizations

Authorization
string
header
required

Authorization header with Bearer token

Body

application/json
query
string
required

The query to search for.

Required string length: 1 - 2048
sources
enum<string>[] | null

Restrict results to these connector source types.

Available options:
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
document_sets
string[] | null

Restrict results to documents in these document sets, by name.

tags
Tag · object[] | null

Restrict results to documents carrying all of these metadata tags.

time_cutoff
string<date-time> | null

ISO 8601 timestamp. Only documents updated on or after this moment are returned. Timestamps without a timezone are treated as UTC.

persona_id
integer | null

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
string | null

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
string | null

Model to use from provider. Must be sent together with provider.

skip_query_expansion
boolean
default:false

When true, the query is run as written instead of being rewritten and expanded first.

message_history
ChatMinimalTextMessage · object[] | null

Preceding conversation turns, used to interpret a query that depends on earlier context. Defaults to query on its own.

Response

Successful Response

results
SearchResult · object[]
required