POST

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.

Endpoint

POST /databases/ {id} /search

Path Parameters

idstring · requiredThe 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.

contentstring · requiredText query to search for

metadataobject · optional Filter results by metadata fields. Supports equality and $in operator

top_kinteger · optional Number of nearest neighbors to retrieve from vector search

pageinteger · optionalPage number for pagination

per_pageinteger · optionalNumber of results per page

Example Request

{
  "content": "kitchen faucet repair",
  "metadata": {
    "category": "home-repair"
  },
  "top_k": 10,
  "page": 1,
  "per_page": 5
}

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.

Metadata-Only Search

FREE

Omit content , image , and image_url 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 .

Example: equality filter

{
  "metadata": {
    "product_id": 321,
    "type": "variant"
  },
  "page": 1,
  "per_page": 20
}

Example: $in filter

{
  "metadata": {
    "product_id": { "$in": [321, 123] }
  }
}

Response

Returns paginated search results with similarity scores.

resultsarrayArray of search result objects

pageintegerCurrent page number

per_pageintegerResults per page

totalintegerTotal number of matching documents

search_timestring Time taken to perform the search (e.g. "102ms")

Search Result Object

vector_idstringDocument ID

contentstring | nullDocument content

metadataobject | nullDocument metadata

scorefloatSimilarity 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,
  "total": 42,
  "search_time": "102ms"
}