Sign in

v1

latestOpenAPI 3.0.3BSL2026-07-17133415718.8 KB
Chunk

Search

This route provides the primary search functionality for the API. It can be used to search for chunks by semantic similarity, full-text similarity, or a combination of both. Results' chunk_html values will be modified with <mark><b> or custom specified tags for sub-sentence highlighting.

post/api/chunk/search

Headers

TR-Datasetstring uuid required

The dataset id or tracking_id to use for the request. We assume you intend to use an id if the value is a valid uuid.

X-API-Version'V1' | 'V2'

The API version to use for this request. Defaults to V2 for orgs created after July 12, 2024 and V1 otherwise.

Request body

content_onlyboolean nullable

Set content_only to true to only returning the chunk_html of the chunks. This is useful for when you want to reduce amount of data over the wire for latency improvement (typically 10-50ms). Default is false.

get_total_pagesboolean nullable

Get total page count for the query accounting for the applied filters. Defaults to false, but can be set to true when the latency penalty is acceptable (typically 50-200ms).

{"stackTrail":"components:schemas:SearchChunksReqPayload:properties:metadata","oasType":"schema","type":"unknown","description":"Metadata is any metadata you want to associate w/ the event that is created from this request","nullable":true}
pageinteger nullable

Page of chunks to fetch. Page is 1-indexed.

page_sizeinteger nullable

Page size is the number of chunks to fetch. This can be used to fetch more than 10 chunks at a time.

remove_stop_wordsboolean nullable

If true, stop words (specified in server/src/stop-words.txt in the git repo) will be removed. Queries that are entirely stop words will be preserved.

score_thresholdnumber float nullable

Set score_threshold to a float to filter out chunks with a score below the threshold for cosine distance metric. For Manhattan Distance, Euclidean Distance, and Dot Product, it will filter out scores above the threshold distance. This threshold applies before weight and bias modifications. If not specified, this defaults to no threshold. A threshold of 0 will default to no threshold.

search_type'fulltext' | 'semantic' | 'hybrid' | 'bm25' required
slim_chunksboolean nullable

Set slim_chunks to true to avoid returning the content and chunk_html of the chunks. This is useful for when you want to reduce amount of data over the wire for latency improvement (typically 10-50ms). Default is false.

use_quote_negated_termsboolean nullable

If true, quoted and - prefixed words will be parsed from the queries and used as required and negated words respectively. Default is false.

user_idstring nullable

User ID is the id of the user who is making the request. This is used to track user interactions with the search results.

Example request

{
  "filters": {
    "must": [
      {
        "field": "num_value",
        "range": {
          "gt": 0,
          "gte": 0,
          "lt": 1,
          "lte": 1
        }
      }
    ],
    "must_not": [
      {
        "field": "metadata.key3",
        "match": [
          "value5",
          "value6"
        ]
      }
    ],
    "should": [
      {
        "field": "metadata.key1",
        "match": [
          "value1",
          "value2"
        ]
      }
    ]
  },
  "highlight_delimiters": [
    "?",
    ",",
    ".",
    "!"
  ],
  "highlight_results": true,
  "page": 1,
  "page_size": 10,
  "query": "Some search query",
  "score_threshold": 0.5,
  "search_type": "semantic",
  "use_weights": true
}

Response

Chunks with embedding vectors which are similar to those in the request body

OR

Example response

{
  "chunks": [
    {
      "chunk": {
        "chunk_html": "<p>Some HTML content</p>",
        "content": "Some content",
        "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
        "link": "https://example.com",
        "metadata": {
          "key1": "value1",
          "key2": "value2"
        },
        "time_stamp": "2021-01-01 00:00:00.000",
        "weight": 0.5
      },
      "highlights": [
        "highlight is two tokens: high, light",
        "whereas hello is only one token: hello"
      ],
      "score": 0.5
    }
  ]
}