---
title: "Search"
method: POST
path: "/search"
tags: ["public"]
---

# Search

`POST /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.

## Request body

- SearchRequest
  - `query` string, required — The query to search for.
  - `sources` DocumentSource[], nullable — Restrict results to these connector source types.
  - `document_sets` string[], nullable — Restrict results to documents in these document sets, by name.
  - `tags` Tag[], nullable — Restrict results to documents carrying all of these metadata tags.
    - `tag_key` string, required
    - `tag_value` string, required
  - `time_cutoff` string, date-time, nullable — ISO 8601 timestamp. Only documents updated on or after this moment are returned. Timestamps without a timezone are treated as UTC.
  - `persona_id` integer, nullable — 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, nullable — 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, nullable — Model to use from `provider`. Must be sent together with `provider`.
  - `skip_query_expansion` boolean — When true, the query is run as written instead of being rewritten and expanded first.
  - `message_history` ChatMinimalTextMessage[], nullable — Preceding conversation turns, used to interpret a query that depends on earlier context. Defaults to `query` on its own.
    - `message` string, required
    - `message_type` 'system' | 'user' | 'assistant' | 'tool_call_response' | 'user_reminder', required

## Response `200`

Successful Response

- SearchResponse
  - `results` SearchResult[], required
    - `citation_id` integer, nullable, required — 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` string, required — Document title.
    - `content` string, required — Full text of the matched section.
    - `link` string, nullable, required — Link to the source document, when the connector provides one.
    - `source_type` string, required — Connector source type the document came from.
    - `updated_at` string, nullable, required — When the document was last updated, when the connector provides it.

## Other responses

- `422` — Validation Error

## Changes

- **2026-09-02** `fcb09658bc37` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/onyx-dot-app/apis/onyx-api/changes/search/post.md)

---

[API](https://skmtc.dev/onyx-dot-app/apis/onyx-api.md) · [All operations](https://skmtc.dev/onyx-dot-app/apis/onyx-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/onyx-dot-app/onyx-api/revisions/fcb09658bc37/schema)