---
title: "Enhanced search with grammar"
method: POST
path: "/api/v1/assets/search-enhanced"
tags: ["Assets"]
---

# Enhanced search with grammar

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

## Request

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

Search using structured **grammar queries** with automatic query routing. The enhanced endpoint analyzes the query and routes it to the optimal search strategy:

- **Grammar** (`tool:midjourney AND tag:hero`) — structured field:value filters, routed to SQL
- **Semantic** (`a dreamy landscape at sunset`) — natural language, routed to vector similarity
- **Hybrid** (`cyberpunk tool:midjourney`) — combines semantic + grammar filters
- **Simple** (`hero banner`) — basic text matching

This endpoint is recommended for most use cases — it handles query classification automatically. Use `/assets/search` for explicit control or `/assets/search-semantic` for pure vector search.

See the `SearchGrammarReference` schema for all available grammar fields.

## Request body

- EnhancedSearchRequest
  - `query` string
  - `mode` 'exact' | 'partial' | 'fuzzy' | 'fulltext' | 'boolean' | 'smart'
  - `fields` string[]
  - `options` object
    - `fuzzyThreshold` number
    - `highlightMatches` boolean
    - `includeRelevanceScore` boolean
    - `booleanMode` boolean
    - `caseSensitive` boolean
  - `limit` integer
  - `offset` integer
  - `queryText` string

## Response `200`

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)