Dashboard
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 · optionalFilter results by metadata fields
top_kinteger · optionalNumber 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
}

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 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
}