POST
/
queries
/
top-snippets
Top Snippets
curl --request POST \
  --url https://api.zeroentropy.dev/v1/queries/top-snippets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "collection_name": "<string>",
  "query": "<string>",
  "k": 123,
  "reranker": "<string>",
  "filter": {},
  "precise_responses": false,
  "include_document_metadata": false
}'
{
  "results": [
    {
      "path": "<string>",
      "start_index": 123,
      "end_index": 123,
      "page_span": [
        123
      ],
      "content": "<string>",
      "score": 123
    }
  ],
  "document_results": [
    {
      "path": "<string>",
      "score": 123,
      "metadata": {},
      "file_url": "<string>"
    }
  ]
}

Authorizations

​
Authorization
string
header
required

The Authorization header must be provided in the format Bearer <your-api-key>.

You can get your API Key at the Dashboard!

Body

application/json
​
collection_name
string
required

The name of the collection.

​
query
string
required

The natural language query to search with. This cannot exceed 4096 characters (A single UTF-8 codepoint, is considered to be 1 character).

​
k
integer
required

The number of snippets to return. If there are not enough snippets matching your filters, then fewer may be returned. This number must be between 1 and 128, inclusive.

​
reranker
string | null

The reranker to use after initial retrieval. The default is null. You can find available model ids, along with more information, at /models/rerank.

​
filter
object | null

The query filter to apply. Please read Metadata Filtering for more information. If not provided, then all documents will be searched.

​
precise_responses
boolean
default:false

Enable precise responses. Precise responses will have higher latency, but provide much more precise snippets. When precise_responses is set to true, the responses will average 200 characters. If set to false, the responses will average 2000 characters. The default is false.

​
include_document_metadata
boolean
default:false

If true, the document_results returns will additionally contain document metadata. This is false by default, as returning metadata can add overhead if the amount of data to return is large.

Response

Successful Response

​
results
SnippetResponse · object[]
required

The array of snippets returned by this endpoint. Each snippet result refers to a particular document path, and index range. Note that all documents, regardless of filetype, are converted into UTF-8-encoded strings. The start_index and end_index of a snippet refer to the range of characters in that string, that have been matched by this snippet.

​
document_results
DocumentRetrievalResponse · object[]
required

The array of associated document information. Note how each snippet has an associated document path. After deduplicating the document paths, this array will contain document info for each document path that is referenced by at least one snippet result.