vecstoreDocs

Documents

Search Documents

Search your database using text or images. Vecstore performs semantic search across text-to-text, image-to-image, and text-to-image, returning the most relevant documents ranked by similarity.

POST/databases/{id}/search

Path Parameters

idstringrequired
The database ID

Request Body

For text search, send your search query as a string. Works for both text-to-text and text-to-image search. Optionally filter results by metadata.

contentstringrequired
Text query to search for
metadataobject
Filter results by metadata fields. Supports equality and $in operator
top_kinteger
Maximum number of results across all pages, up to 1000. Defaults to 10
pageinteger
Page number for pagination
per_pageinteger
Number of results per page, up to 100. Defaults to top_k
min_scorenumber
Only return results with a score at or above this value, between 0 and 1. Applied before pagination
Example request
{
  "content": "kitchen faucet repair",
  "metadata": {
    "category": "home-repair"
  },
  "top_k": 10,
  "page": 1,
  "per_page": 5,
  "min_score": 0.3
}

Response

Returns paginated search results with similarity scores.

resultsarray
Array of search result objects
pageinteger
Current page number
per_pageinteger
Results per page
estimated_totalinteger
Estimated number of results. Equals top_k while more pages remain, and the exact count on the last page. Omitted for metadata-only searches
totalinteger
Exact number of matching documents. Metadata-only searches only
has_moreboolean
Whether another page of results exists
search_timestring
Time spent running the database query (e.g. "4ms"). Excludes embedding generation
embedding_msfloat · optional
Time spent generating the query embedding, in milliseconds. Omitted for metadata-only searches

Search result object

vector_idstring
Document ID
contentstring | null
Document content
metadataobject | null
Document metadata
scorefloat
Similarity score (higher is better)
Example response
{
  "results": [
    {
      "vector_id": "4de5bed5-e483-4bd7-9760-a54ec07aefd9",
      "content": "How to fix a leaky kitchen faucet",
      "metadata": {
        "category": "home-repair"
      },
      "score": 0.92
    },
    {
      "vector_id": "7f8e9a0b-1c2d-3e4f-5a6b-7c8d9e0f1a2b",
      "content": "Replacing a kitchen sink tap",
      "metadata": {
        "category": "plumbing"
      },
      "score": 0.87
    }
  ],
  "page": 1,
  "per_page": 5,
  "estimated_total": 10,
  "has_more": true,
  "search_time": "4ms",
  "embedding_ms": 9.8
}

Pagination

top_k caps how many results you can page through, and per_page sets how many come back per request. Each request only retrieves the results up to its page, so the first page of a top_k of 1000 is as fast as a top_k of 10; later pages cost more. Show a "next page" control while has_more is true, and use estimated_total for an approximate result count.

Example: 10 results per page, up to 100
{
  "content": "running shoes",
  "top_k": 100,
  "page": 1,
  "per_page": 10
}

Metadata Filters

The metadata object filters results by stored fields. Use equality for a single value or the $in operator to match any of a list. Equality and $in can be combined in one request.

Equality
Match documents where the field equals the given value, e.g. { "category": "shoes" }
$in
Match documents where the field equals any value in the array. Values are coerced to text, so works for stored strings, numbers, and booleans. Max 1000 values; empty arrays are rejected
Example: $in operator
"metadata": {
  "product_id": { "$in": [213, 910, 522] }
}
Example: equality + $in
"metadata": {
  "category": "shoes",
  "product_id": { "$in": [1, 2, 3] }
}

Metadata keys must match [a-zA-Z0-9_-]{1,64}. Invalid keys are rejected.

Find Similar

To find documents similar to one already in the database, send its vector_id in place of content, image, or image_url. The stored embedding is reused, so no embedding is generated and the search returns faster. The source document is left out of the results. Works for both text and image databases, and can be combined with a metadata filter. Returns 404 if no document has that vector_id.

Example request
{
  "vector_id": "4de5bed5-e483-4bd7-9760-a54ec07aefd9",
  "top_k": 10
}

Metadata-Only Search FREE

Omit content, image, image_url, and vector_id to filter documents by metadata alone. No embedding is generated and no vector search runs, so the request is free — no credit is charged. The response is the usual paginated result set, with every score set to 0.0 and an exact total in place of estimated_total.

Example: equality filter
{
  "metadata": {
    "product_id": 321,
    "type": "variant"
  },
  "page": 1,
  "per_page": 20
}
Example: $in filter
{
  "metadata": {
    "product_id": { "$in": [321, 123] }
  }
}

Filtering by Score

Set min_score to drop weak matches instead of always getting top_k results. Results scoring below it are removed before pagination, so fewer than top_k results may come back; has_more turns false once they run out. It has no effect on metadata-only searches.

Text → image
Scores are calibrated from 0 to 1. Around 0.3 removes most unrelated images
Image → image
Scores are cosine similarity. Around 0.6 keeps visually similar images
Text → text
Scores combine semantic and keyword ranking, with 1.0 for a result ranked first by both