---
title: "Semantic/vector search"
method: POST
path: "/api/v1/assets/search-semantic"
tags: ["Assets"]
---

# Semantic/vector search

`POST /api/v1/assets/search-semantic`

## Request

- Base URL: `https://numonic.ai`
- URL: `https://numonic.ai/api/v1/assets/search-semantic`
- Auth: API key in header `x-api-key`

Search using **vector similarity** for natural language queries. Converts the query text into an embedding and finds the most visually or semantically similar assets.

Best for: "a dreamy watercolor landscape", "product photo on white background", "dark moody portrait". For structured filtering use `/assets/search` with grammar syntax, or `/assets/search-enhanced` for automatic routing.

## Request body

- SemanticSearchRequest
  - `query` string, required: Natural language search query
  - `limit` integer
  - `offset` integer
  - `filters` object
    - `status` 'active' | 'archived' | 'deleted'
    - `tags` string[]
    - `mime_types` string[]
  - `includeScore` boolean

## Response `200`

Semantic search results returned

- SearchResponse
  - `data` SearchResultItem[], required
    - `asset_h` string, nullable, required
    - `title` string, nullable, required
    - `description` string, nullable, required
    - `filename` string, nullable, required
    - `mime_type` string, nullable, required
    - `status` string, nullable, required
    - `created_at` string, nullable, required
    - `similarity_score` number, nullable, required: Vector similarity score (0-1, higher = more similar)
    - `relevance_score` number, nullable, required: Text relevance score from full-text search
    - `tags` string[], required
    - `thumbnail_url` string, nullable, required: Pre-signed thumbnail URL (expires in 5 minutes)
    - `original_width` number, nullable, required
    - `original_height` number, nullable, required
  - `pagination` object, required
    - `limit` integer, required
    - `offset` integer, required
    - `totalMatches` integer: Total matching assets (may be absent for some search modes)

---

[API](https://skmtc.dev/numonic/apis/numonic-api.md) · [All operations](https://skmtc.dev/numonic/apis/numonic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/numonic/apis/numonic-api/revisions/6c559bef1e35?raw)