Appearance

Typesense Search API ​

Overview ​

server/api/typesense/search.post.ts is the portal's only route to Typesense. The browser never holds a Typesense key: it posts a search description here, the route checks that the caller's token can see the requested workspace, validates every ranking parameter, resolves the field set for each collection against the live schema, runs one Typesense multi-search, and replaces raw S3 keys in the hits with signed URLs before returning.

The route does not add any workspace or instance clause to filter_by. Scoping to the portal instance comes from the client: buildFiltersForCollection in useCommonSearch prefixes every collection filter with (instance_visibility:=<brand id> && instance_visibility:!=0). See Security Considerations.

Endpoint ​

Path: POST /api/typesense/search

File: server/api/typesense/search.post.ts

Called from: useSearchApi().searchAssets(body) (through $api with useApiBase: false), used by useSearch, useSearchBar, useFolderDetails and useCollageDetails.

Request Body ​

typescript
interface SearchRequestBody {
  request: {
    q?: string                                   // default "*"
    collections: string[]                        // required, subset of ALLOWED_COLLECTIONS
    sort_by?: string | { [collection: string]: string }
    include_fields?: { [collection: string]: string[] }
    group_by?: string
    group_limit?: number
  }
  commonSearchParams: {
    query_by: string | { [collection: string]: string }
    query_by_weights?: string | { [collection: string]: string | { [field: string]: string | number } }
    infix?: string | { [collection: string]: string | { [field: string]: string | number } }
    per_page: number
    page: number
    sort_by?: string                             // fallback when request.sort_by has nothing for a collection
    text_match_type?: 'max_score' | 'max_weight' | 'sum_score'
  }
  workspace_id_filter: string                    // workspace the token must be able to access
  filterQuery?: { [collection: string]: string } // Typesense filter_by per collection, used as sent
}

Only three collections can be searched. Anything else is rejected before Typesense is called:

CollectionHoldsPortal tab
digital_assetsAssetsAssets
dam_collectionsCollagesCollages
digital_assets_categoriesFoldersFolders

query_by, query_by_weights and infix are each accepted either as one value for every collection or as a per-collection record. Weights and infix may additionally be a positional comma string ("10,6,4,1") or a map keyed by field name ({ "search_name": 10, "tags": 6 }, the shape buildSearchFieldParams in shared/searchFields.ts sends). The map shape is preferred because it survives a field being dropped by the schema check.

Response ​

typescript
{
  [collectionName: string]: {
    data: SearchResult           // the Typesense result for that collection, in request order
  }
}

Before returning, signS3PathsInResults walks every hit (including grouped_hits) and swaps raw S3 keys for signed URLs. See Typesense Utils.

SearchResult Structure ​

typescript
{
  hits: Array<{
    document: object            // indexed document; S3 key fields replaced with signed URLs
    highlights?: object
    text_match?: number
  }>
  grouped_hits?: Array<{ hits: Array<...> }>   // present when group_by was sent
  found: number
  page: number
  request_params: object
}

Features ​

Authentication & Authorization ​

  1. Authorization header is required; without it the route returns 401 Authorization header is required.
  2. runtimeConfig.public.apiBaseUrl must be set, otherwise 500 API_BASE_URL environment variable is not configured.
  3. The token is sent to ${apiBaseUrl}user. The returned data.user.accessibleInstances must contain an entry whose workspace_id equals workspace_id_filter and that has a truthy instance_id.
  4. Any failure in step 3 (network error, empty list, no match) is logged as Token verification failed and returned as 401 Unauthorized - Invalid token or insufficient permissions.

Because the access check runs before parameter validation, a body with no workspace_id_filter fails with 401, not 400.

All collections in request.collections go to Typesense in a single multiSearch.perform call. Per collection the route builds:

ParameterValue
q"*" stays a wildcard; anything else is lowercased (String(q).toLowerCase())
query_by / query_by_weights / infixresolved by resolveRequestedSearchFields (see Search Fields)
filter_byfilterQuery[collection] or ""
sort_bysee sort resolution below
prefixtrue
num_typosSEARCH_NUM_TYPOS = 0
typo_tokens_threshold1
prioritize_exact_matchtrue
prioritize_token_positiontrue
include_fieldsinclude_fields[collection] when present
group_by / group_limitcopied when present
text_match_typecaller value, else SEARCH_TEXT_MATCH_TYPE = max_score
per_page / pagefrom commonSearchParams

Sort resolution per collection, first non-empty wins:

Instance Filtering ​

The route applies no instance or workspace filter of its own. The portal client builds it in useCommonSearch.buildFiltersForCollection:

typescript
const instanceId = useAppDataStore().brand?.id
const visibilityFilter = instanceId
  ? `(instance_visibility:=${instanceId} && instance_visibility:!=0)`
  : ''

That clause is joined with the collection's own filters and, on the Assets tab, with the asset-type filter, then sent as filterQuery[collection]. When brand.id is not set the visibility clause is empty.

Query Adjustment ​

The query is not wildcarded or tokenised. "*" passes through; every other value is lowercased and sent as typed. Prefix matching comes from prefix: true, substring matching from the per-field infix modes, and ranking order from the _eval relevance band that the client prepends to sort_by (useSearchApi.withRelevanceTier). With num_typos: 0, misspellings do not match.

Error Handling ​

All errors are re-thrown through createError with the original statusCode (default 500) and message. TypesenseConnectionError is logged as Typesense Connection Error:, others as Search Error:.

StatusstatusMessageCause
401Authorization header is requiredno Authorization header
500API_BASE_URL environment variable is not configuredmissing runtime config
401Unauthorized - Invalid token or insufficient permissionstoken check failed or workspace not in accessibleInstances
400Missing required parameters in the request.request, workspace_id_filter or commonSearchParams missing
400Collection name is required in the request.collections empty
400Collection "<name>" is not searchable.collection outside the allow-list
400Parameter `text_match_type` must be one of: max_score, max_weight, sum_score.bad ranking mode
400Invalid query_by for collection "<name>". ...not field(,field)* of [a-zA-Z0-9_]
400Invalid query_by_weights for collection "<name>". ...string not 1-3 digit integers, or map weight outside 0-127
400Invalid infix for collection "<name>". ...mode other than always, fallback, off
400Parameter `sort_by` is malformed. ...bad clause in commonSearchParams.sort_by or a single-collection sort_by
400Invalid sort_by format for collection "<name>". ...bad clause in a per-collection sort_by map
400Parameter `sort_by` must be a string or an object ...multi-collection sort_by that is an array or other type
503 / 500from performMultiSearchconnection failure or Typesense API error

Missing Authorization ​

Checked first, before the body is used. Returns 401 Authorization header is required.

Invalid Token ​

Returns 401 Unauthorized - Invalid token or insufficient permissions whenever ${apiBaseUrl}user fails, returns no accessibleInstances, or has no entry for workspace_id_filter.

Missing Parameters ​

Returns 400 Missing required parameters in the request. when request, workspace_id_filter or commonSearchParams is falsy (only reachable once the token check has passed).

Invalid Collections ​

collections missing or empty gives 400 Collection name is required in the request.. A name outside digital_assets, dam_collections, digital_assets_categories gives 400 Collection "<name>" is not searchable. (the first offending name is reported).

Invalid Sort By ​

Every sort_by string is checked by isValidSortBy:

  1. An optional leading _eval(...) band must pass isValidEvalTier: values inside backticks, only [A-Za-z0-9_()[\]:=|&, ] outside them, and only fields that appear in the tier definitions (search_name, tags, portal_custom_field_values).
  2. After the band is stripped, every comma-separated clause must match ^[a-zA-Z0-9_]+:(asc|desc)$.

A single-collection request must send sort_by as a string; an object there is rejected as malformed. A multi-collection request may send a string (applied to all) or a per-collection map.

Example accepted value for digital_assets and q = "brand":

text
_eval([ (search_name:=`brand` && tags:=`brand`):6, (search_name:=`brand`):5, (tags:=`brand` && portal_custom_field_values:=`brand`):4, (tags:=`brand`):3, (portal_custom_field_values:=`brand`):2 ]):desc,_text_match:desc,modified_at:desc

Typesense Errors ​

performMultiSearch throws TypesenseConnectionError (its status is 503) for ECONNREFUSED, ECONNRESET, ETIMEDOUT, connection or timeout messages, and HTTP 502/503/504; other Typesense failures become a plain Error with message Typesense Error: <message>. The route re-throws with err.statusCode || 500. TypesenseConnectionError sets status, not statusCode, so connection failures currently surface to the browser as 500 with the connection message.

Usage ​

typescript
const searchApi = useSearchApi()

const results = await searchApi.searchAssets({
  request: {
    q: 'brand',
    collections: ['digital_assets'],
    sort_by: '_text_match:desc,modified_at:desc',   // _eval band is prepended by searchAssets
  },
  filterQuery: {
    digital_assets: '(instance_visibility:=42 && instance_visibility:!=0)',
  },
  commonSearchParams: {
    ...buildSearchFieldParams(['digital_assets']),
    per_page: 50,
    page: 1,
    text_match_type: SEARCH_TEXT_MATCH_TYPE,
  },
  workspace_id_filter: 'WORKSPACE_ID',
})

const hits = results.digital_assets.data.hits

buildSearchFieldParams(['digital_assets']) produces:

json
{
  "query_by": { "digital_assets": "search_name,tags,portal_custom_field_values,description" },
  "query_by_weights": { "digital_assets": { "search_name": 10, "tags": 6, "portal_custom_field_values": 4, "description": 1 } },
  "infix": { "digital_assets": { "search_name": "always", "tags": "fallback", "portal_custom_field_values": "fallback", "description": "off" } }
}

Request Flow ​

  1. Read Authorization; 401 if absent.
  2. Verify the token against ${apiBaseUrl}user and match workspace_id_filter in accessibleInstances; 401 on any failure.
  3. Check request, workspace_id_filter, commonSearchParams; 400 if missing.
  4. Check collections against the allow-list; 400 on the first bad name.
  5. Validate text_match_type, then per collection query_by, query_by_weights, infix; then commonSearchParams.sort_by and request.sort_by.
  6. For each distinct collection, call resolveRequestedSearchFields (live schema, cached 10 minutes) to get query_by, weights and infix narrowed to indexed fields.
  7. Build one SearchRequest per collection (filter, resolved sort, fixed typo and prefix settings); rebuild the _eval band if it names an unindexed field.
  8. Run performMultiSearch.
  9. Key results by collection name and sign S3 paths.

Security Considerations ​

  1. The Typesense key stays on the server (getTypesenseClient() in utils.ts).
  2. Every request needs a token that can access workspace_id_filter.
  3. Only digital_assets, dam_collections and digital_assets_categories are searchable; digital_assets_tags is not reachable from the portal.
  4. query_by can only narrow the configured field set, never widen it; unknown fields are dropped and an empty result falls back to the full set. Weights are capped at 127.
  5. sort_by and the _eval band are shape-checked so caller text cannot inject arbitrary filter syntax into the sort.
  6. filterQuery is passed to Typesense unchanged and the route adds no instance clause. Instance scoping therefore depends on the client sending instance_visibility:=<brand id>.
  7. Raw S3 keys never leave the server: a key that fails to sign is replaced with ''.