Skip to content
QuantCDN

Semantic Search Query

POST
/api/v3/organizations/{organisation}/ai/vector-db/collections/{collectionId}/query

Performs semantic search on a collection using vector similarity. Returns the most relevant documents based on meaning, not keyword matching. * * Three Search Modes: * * 1. Text Query - Provide query string, server generates embedding * - Query text is embedded using the collection’s embedding model * - Embeddings are cached for repeated queries * * 2. Vector Query - Provide pre-computed vector array * - Skip embedding generation (faster) * - Useful when you’ve already embedded the query elsewhere * - Vector dimension must match collection (e.g., 1024 for Titan v2) * * 3. Metadata List - Set listByMetadata: true with filter * - Skip semantic search entirely * - Return all documents matching the filter * - Supports cursor-based pagination for large datasets * - Results ordered by sortBy/sortOrder (default: created_at DESC) * * Filtering: * - filter.exact: Exact match on metadata fields (AND logic) * - filter.contains: Array contains filter for tags (ANY match) * - Filters can be combined with semantic search or used alone with listByMetadata * * Pagination (listByMetadata mode only): * - Use cursor from previous response’s nextCursor to get next page * - Uses keyset pagination for efficient traversal of large datasets * - Control sort with sortBy and sortOrder * * Use Cases: * - Find relevant documentation for user questions * - Power RAG (Retrieval Augmented Generation) in AI assistants * - Semantic search across knowledge bases * - List all artifacts by building/worker/tag

Authorizations

Parameters

Path Parameters

organisation
required
string

The organisation ID

collectionId
required
string format: uuid

The collection ID

Request Body required

object
query

Natural language search query (mutually exclusive with vector)

string
>= 3 characters <= 1000 characters 
How do I authenticate with the API?
vector

Pre-computed embedding vector (mutually exclusive with query). Array length must match collection dimension.

Array<number>
[
  0.0234,
  -0.0891,
  0.0456
]
limit

Maximum number of results to return

integer
default: 5 >= 1 <= 20
threshold

Minimum similarity score (0-1, higher = more relevant)

number format: float
default: 0.7 <= 1
includeEmbeddings

Include embedding vectors in response (for debugging)

boolean
filter

Filter results by metadata fields. Applied AFTER semantic search (or alone in listByMetadata mode). All conditions use AND logic.

object
exact

Exact match on metadata fields. Keys are metadata field names, values are expected values.

object
key
additional properties
any
{
  "buildingId": "building-123",
  "type": "research-report"
}
contains

Array contains filter for array metadata fields (like tags). Returns documents where the metadata array contains ANY of the specified values.

object
key
additional properties
Array<string>
{
  "tags": [
    "important",
    "reviewed"
  ]
}
listByMetadata

If true, skip semantic search and return all documents matching the filter. Requires filter. Supports cursor pagination.

boolean
cursor

Pagination cursor for listByMetadata mode. Use nextCursor from previous response. Opaque format - do not construct manually.

string
sortBy

Field to sort by in listByMetadata mode

string
default: created_at
Allowed values: created_at document_id
sortOrder

Sort direction in listByMetadata mode

string
default: desc
Allowed values: asc desc

Responses

200

Search completed successfully

object
results
Array<object>
object
documentId
string format: uuid
content

Document text content

string
similarity

Cosine similarity score (1.0 for metadata-only queries)

number format: float
<= 1
metadata
object
key
additional properties
any
embedding

Vector embedding (only if includeEmbeddings=true)

Array<number>
query

Original query text (null if vector or metadata search was used)

string
nullable
searchMode

Search mode used: text (query provided), vector (pre-computed), metadata (listByMetadata)

string
Allowed values: text vector metadata
filter

Filter that was applied (if any)

object
count

Number of results returned

integer
executionTimeMs

Query execution time in milliseconds

integer
collectionId
string format: uuid
hasMore

True if more results available (listByMetadata mode only)

boolean
nextCursor

Cursor for next page. Pass as cursor param to continue. Null when no more results. Only in listByMetadata mode.

string
nullable
pagination

Pagination info (listByMetadata mode only)

object
sortBy
string
Allowed values: created_at document_id
sortOrder
string
Allowed values: asc desc
limit
integer

400

Invalid request parameters

403

Access denied

404

Collection not found

500

Failed to perform search