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

# Search assets

`POST /api/v1/assets/search`

## Request

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

Full-text search across asset metadata and content. Supports plain text queries and structured **grammar syntax** (`field:value`) with boolean operators.

**Grammar syntax** — combine field filters with `AND`, `OR`, `NOT`:
- `tool:midjourney AND tag:approved` — Midjourney assets tagged "approved"
- `mime_type:image/png OR mime_type:image/webp` — PNG or WebP images
- `created:>2025-01-01 AND width:>1920` — recent high-res assets
- `prompt:"cyberpunk city" NOT status:Trashed` — prompt search excluding trash

Value syntax: quoted strings for exact match (`title:"hero banner"`), wildcards (`filename:hero*`), ranges for numeric/date fields (`width:>1920`, `created:2025-01..2025-12`).

See the `SearchGrammarReference` schema for the full list of ~50 grammar fields across core metadata, dates, dimensions, AI generation, ComfyUI, and lineage domains.

## Request body

- SearchAssetsRequest
  - `query` string: Search query text
  - `queryText` string: Legacy alias for query
  - `orderBy` 'newest' | 'oldest' | 'relevance' | 'similarity' | 'name-asc' | 'name-desc' | 'random' | 'generated-newest' | 'generated-oldest' | 'downloaded-newest' | 'downloaded-oldest': Sort order for results. generated-*/downloaded-* sort on the tri-temporal provenance dates (browse path only; clamped to newest when query text is present).
  - `mode` 'exact' | 'partial' | 'fuzzy' | 'fulltext' | 'boolean' | 'smart': Search matching mode
  - `fields` string[]: Fields to search within
  - `queryVector` number[]: Pre-computed embedding vector for semantic search
  - `similarToAssetH` string: Find assets similar to this asset hash
  - `embeddingConfigH` string: Embedding configuration hash for vector search
  - `filters` object: Key-value pairs for filtering (e.g., {"status": "Approved", "tags": ["logo"]})
  - `options` object: Advanced search options
    - `fuzzyThreshold` number
    - `highlightMatches` boolean
    - `includeRelevanceScore` boolean
    - `booleanMode` boolean
  - `limit` integer
  - `offset` integer
  - `includeScore` boolean
  - `randomSeed` number: Seed for consistent random ordering

## 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)