Find passages or files with combined ranking

curl --request POST \
  --url https://api.qontext.ai/v1/search/hybrid \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "What is the refund policy?"
}
'

import requests

url = "https://api.qontext.ai/v1/search/hybrid"

payload = { "query": "What is the refund policy?" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({query: 'What is the refund policy?'})
};

fetch('https://api.qontext.ai/v1/search/hybrid', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "object": "list",
  "url": "/v1/search/hybrid",
  "hasMore": false,
  "nextCursor": null,
  "data": [
    {
      "kind": "passage",
      "text": "<string>",
      "file": {
        "object": "file",
        "id": "doc_9f2k1x8b3m7q0v",
        "path": "/support/policies/refunds.md",
        "name": "refunds.md",
        "parentId": "dir_4k1n8p2v5m7q0x",
        "parentPath": "/support/policies",
        "protected": true,
        "lastChangeId": "chg_7t4p2w9c1n6s8k",
        "createdAt": "2026-07-01T09:12:00.000Z",
        "updatedAt": "2026-08-01T14:03:00.000Z"
      },
      "sources": [
        {
          "integration": "Zendesk",
          "dataType": "Ticket",
          "sourceId": "4821"
        }
      ]
    }
  ]
}

{
  "type": "https://docs.qontext.ai/errors/invalid-request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "The request could not be accepted as sent.",
  "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b",
  "errors": [
    {
      "code": "out_of_range",
      "pointer": "/limit",
      "detail": "limit must not be greater than 1000"
    }
  ]
}

{
  "type": "https://docs.qontext.ai/errors/unauthenticated",
  "title": "Unauthenticated",
  "status": 401,
  "code": "unauthenticated",
  "detail": "The API key is missing or not valid.",
  "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b"
}

{
  "type": "https://docs.qontext.ai/errors/internal-error",
  "title": "Internal error",
  "status": 500,
  "code": "internal_error",
  "detail": "An unexpected error occurred.",
  "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b"
}

{
  "type": "https://docs.qontext.ai/errors/service-unavailable",
  "title": "Temporarily unavailable",
  "status": 503,
  "code": "service_unavailable",
  "detail": "This workspace is temporarily unavailable.",
  "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b"
}

Search passages or files by words and meaning

Combines word and vector passage rankings. An explicit mode selects passages or distinct files with full live text. Omit mode during the grace period to receive full files in the legacy format, including file.fileId and file.url. Mode will be required after the grace period. Expansion defaults to on. Disabling it searches the original query with both methods, without rewrites. With explicit mode, each result includes kind, text, and its readable file in file.id. The sources field lists connected external records when requested. Order shows rank, best match first, rather than confidence. Numerical scores are not returned. New or changed files may take a moment to become searchable.

POST

hybrid

Find passages or files with combined ranking

curl --request POST \
  --url https://api.qontext.ai/v1/search/hybrid \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "What is the refund policy?"
}
'

import requests

url = "https://api.qontext.ai/v1/search/hybrid"

payload = { "query": "What is the refund policy?" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({query: 'What is the refund policy?'})
};

fetch('https://api.qontext.ai/v1/search/hybrid', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "object": "list",
  "url": "/v1/search/hybrid",
  "hasMore": false,
  "nextCursor": null,
  "data": [
    {
      "kind": "passage",
      "text": "<string>",
      "file": {
        "object": "file",
        "id": "doc_9f2k1x8b3m7q0v",
        "path": "/support/policies/refunds.md",
        "name": "refunds.md",
        "parentId": "dir_4k1n8p2v5m7q0x",
        "parentPath": "/support/policies",
        "protected": true,
        "lastChangeId": "chg_7t4p2w9c1n6s8k",
        "createdAt": "2026-07-01T09:12:00.000Z",
        "updatedAt": "2026-08-01T14:03:00.000Z"
      },
      "sources": [
        {
          "integration": "Zendesk",
          "dataType": "Ticket",
          "sourceId": "4821"
        }
      ]
    }
  ]
}

{
  "type": "https://docs.qontext.ai/errors/invalid-request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "The request could not be accepted as sent.",
  "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b",
  "errors": [
    {
      "code": "out_of_range",
      "pointer": "/limit",
      "detail": "limit must not be greater than 1000"
    }
  ]
}

{
  "type": "https://docs.qontext.ai/errors/unauthenticated",
  "title": "Unauthenticated",
  "status": 401,
  "code": "unauthenticated",
  "detail": "The API key is missing or not valid.",
  "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b"
}

{
  "type": "https://docs.qontext.ai/errors/internal-error",
  "title": "Internal error",
  "status": 500,
  "code": "internal_error",
  "detail": "An unexpected error occurred.",
  "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b"
}

{
  "type": "https://docs.qontext.ai/errors/service-unavailable",
  "title": "Temporarily unavailable",
  "status": 503,
  "code": "service_unavailable",
  "detail": "This workspace is temporarily unavailable.",
  "requestId": "3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b"
}

Authorizations

Authorization

string

header

required

Workspace-scoped API key, sent as a bearer token. The recommended header. The workspace is implicit in the key and never appears in a URL.

Body

application/json

Option 1
Legacy full-file search

mode

enum<string>

required

Return ranked passages or distinct files with full text.

Available options:

passages,

files

query

string

required

What you are looking for. A few words or a whole question both work.

Example:

"What is the refund policy?"

limit

integer

default:10

Maximum passages in passages mode, or distinct files in files mode. Defaults to 10.

Required range: 1 <= x <= 500

includeSources

boolean

default:true

Include external records connected to each matched file as sources. The file reference is always present. Defaults to true.

expandQuery

boolean

default:true

Also search query rewrites. Defaults to true.

Response

Matching passages or full files, best match first. One page; there is no next.

Option 1
Option 2

object

enum<string>

required

Type discriminator. Always list.

Available options:

list

url

string

required

The search this page came from.

Example:

"/v1/search/hybrid"

hasMore

boolean

required

Always false. A search answers the best matches in one page and has no next page.

Example:

false

nextCursor

string | null

required

Always null. A search has no position to resume from, so there is no cursor to pass back.

Example:

null

data

object[]

required

Matching passages or full files, best match first.

Show child attributes

Get started

Using the API

Files

Folders

Search

Search passages or files by words and meaning

Authorizations

Body

Response