---
title: "Handle Search Request"
method: POST
path: "/query/document-search"
tags: ["public"]
---

# Handle Search Request

`POST /query/document-search`

Simple search endpoint, does not create a new message or records in the DB

## Request body

- DocumentSearchRequest
  - `chunks_above` integer, nullable
  - `chunks_below` integer, nullable
  - `full_doc` boolean
  - `message` string, required
  - `search_type` 'keyword' | 'semantic' | 'internet', required
  - `retrieval_options` RetrievalDetails, required
    - `chunks_above` integer, nullable
    - `chunks_below` integer, nullable
    - `full_doc` boolean
    - `run_search` 'always' | 'never' | 'auto'
    - `real_time` boolean
    - `filters` BaseFilters
      - `source_type` DocumentSource[], nullable
      - `document_set` string[], nullable
      - `time_cutoff` string, date-time, nullable
      - `tags` Tag[], nullable
        - `tag_key` string, required
        - `tag_value` string, required
    - `enable_auto_detect_filters` boolean, nullable
    - `offset` integer, nullable
    - `limit` integer, nullable
    - `dedupe_docs` boolean
  - `recency_bias_multiplier` number
  - `evaluation_type` 'agentic' | 'basic' | 'skip' | 'unspecified', required
  - `rerank_settings` RerankingDetails
    - `rerank_model_name` string, nullable, required
    - `rerank_api_url` string, nullable, required
    - `rerank_provider_type` 'cohere' | 'litellm' | 'bedrock', required
    - `rerank_api_key` string, nullable
    - `num_rerank` integer, required
    - `disable_rerank_for_streaming` boolean

## Response `200`

Successful Response

- DocumentSearchResponse
  - `top_documents` SavedSearchDocWithContent[], required
    - `document_id` string, required
    - `chunk_ind` integer, required
    - `semantic_identifier` string, required
    - `link` string, nullable
    - `blurb` string, required
    - `source_type` 'ingestion_api' | 'slack' | 'web' | 'google_drive' | 'gmail' | 'requesttracker' | 'github' | 'gitbook' | 'gitlab' | 'guru' | 'bookstack' | 'outline' | 'confluence' | 'jira' | 'slab' | 'productboard' | 'file' | 'coda' | 'notion' | 'zulip' | 'linear' | 'hubspot' | 'document360' | 'gong' | 'google_sites' | 'zendesk' | 'loopio' | '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' | 'mock_connector' | 'user_file', required
    - `boost` integer, required
    - `hidden` boolean, required
    - `metadata` object, required
    - `score` number, nullable
    - `is_relevant` boolean, nullable
    - `relevance_explanation` string, nullable
    - `match_highlights` string[], required
    - `updated_at` string, date-time, nullable
    - `primary_owners` string[], nullable
    - `secondary_owners` string[], nullable
    - `is_internet` boolean
    - `db_doc_id` integer, required
    - `content` string, required
  - `llm_indices` integer[], required
  - `pagination` DocumentSearchPagination, required
    - `offset` integer, required
    - `limit` integer, required
    - `returned_count` integer, required
    - `has_more` boolean, required
    - `next_offset` integer, nullable

## Other responses

- `422` — Validation Error

## Changes

- **2026-01-06** `2d941ea53eb3` — 3 breaking, 12 warning, 14 info
  - request property `retrieval_options/run_search` was restricted to a list of enum values
  - the `retrieval_options/run_search` request property type/format changed from ``/`` to `string`/``
  - response property `top_documents/items/score` list-of-types was widened by adding types `null` to media type `application/json` of response `200`
  - removed `#/components/schemas/OptionalSearchSetting` from the `retrieval_options/run_search` request property `allOf` list
  - …25 more
- **2025-08-21** `9321c45d93b5` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/onyx-dot-app/apis/onyx-api/changes/query/document-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/2d941ea53eb3/schema)