Query

The query endpoint performs semantic search against a vector table.

Semantic Search

POST /v1/vector-tables/{vector_table_id}/query

Request Body:

Field	Type	Required	Default	Description
query	string	Yes		Natural language search query
limit	integer	No	10	Number of results (1-100)
min_similarity_score	float	No	null	Minimum cosine similarity (0.0-1.0)
filters	object	No	null	Metadata filters

Example:

curl -X POST https://api.embedd.to/v1/vector-tables/{id}/query \
  -H "Authorization: Bearer sk_your_key" \
  -H "X-Environment-Id: env_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "machine learning for beginners",
    "limit": 5,
    "min_similarity_score": 0.7,
    "filters": {
      "category": {"eq": "education"},
      "price": {"lte": 50}
    }
  }'

Response (200):

{
  "results": [
    {
      "id": 42,
      "similarity_score": 0.91,
      "metadata": {
        "category": "education",
        "price": 29.99
      },
      "embedded_text": "Introduction to Machine Learning..."
    }
  ],
  "query": "machine learning for beginners",
  "model": "text-embedding-3-small",
  "total_results": 1
}

Filter Operators

Operator	Description	Example
eq	Equals	{"status": {"eq": "active"}}
neq	Not equals	{"status": {"neq": "archived"}}
gt	Greater than	{"price": {"gt": 10}}
gte	Greater than or equal	{"price": {"gte": 10}}
lt	Less than	{"price": {"lt": 100}}
lte	Less than or equal	{"price": {"lte": 100}}
in	In array	{"category": {"in": ["a", "b"]}}
nin	Not in array	{"category": {"nin": ["x"]}}
exists	Field exists	{"notes": {"exists": true}}

Multiple filters are combined with AND logic. Use $or for OR logic:

{
  "filters": {
    "category": {"eq": "electronics"},
    "price": {"gte": 10, "lte": 500},
    "in_stock": {"eq": true}
  }
}

How It Works

1. Your query text is embedded using the same model configured for the vector table
2. The resulting vector is compared against stored vectors using cosine similarity
3. Results are ranked by similarity score (highest first)
4. Metadata filters are applied to narrow results

The query endpoint requires the vector table to be in synced or backfilling status.

See Filters for the full filter reference including $or logic, shorthand equality, and provider notes.