Appearance

Typesense Search API ​

Overview ​

The search.post.ts endpoint provides a server-side Typesense search proxy. It validates user authentication, extracts workspace information, and performs multi-collection searches via Typesense.

Endpoint ​

Path: POST /api/typesense/search

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

Request Body ​

typescript
{
  request: {
    q?: string                    // Search query (default: '*')
    collections: string[]         // Collections to search (required)
    sort_by?: string             // Sort expression (format: "field:asc" or "field:desc")
    include_fields?: {            // Fields to include per collection
      [collectionName: string]: string[]
    }
    group_by?: string            // Group by field
    group_limit?: number         // Group limit
  }
  commonSearchParams: {
    query_by: string             // Fields to search (required)
    per_page: number            // Results per page (required)
    page: number                // Page number (required)
    sort_by?: string            // Default sort expression
  }
  workspace_id_filter: string   // Workspace ID to filter by (required)
  filterQuery?: {               // Additional filters per collection
    [collectionName: string]: string
  }
}

Response ​

typescript
{
  [collectionName: string]: {
    data: SearchResult           // Typesense search result
  }
}

SearchResult Structure ​

typescript
{
  hits: Array<{
    document: object            // Document data
    highlights?: object         // Highlighted fields
    // ... other Typesense fields
  }>
  found: number                 // Total results found
  page: number                  // Current page
  request_params: object        // Request parameters
  // ... other Typesense response fields
}

Features ​

Authentication & Authorization ​

  1. Token Validation: Extracts token from Authorization header
  2. User Verification: Verifies token with backend API
  3. Workspace Access: Validates user has access to workspace
  4. Instance Extraction: Extracts instance_id and workspace_unique_id
  • Supports searching multiple collections in a single request
  • Each collection can have different filters and include fields
  • Results returned as object keyed by collection name

Instance Filtering ​

Automatically applies instances_id filter to all searches:

typescript
// Filter format
filter = filter.length
  ? `${filter} && instances_id: ${instance_id}`
  : `instances_id: ${instance_id}`

Query Adjustment ​

Appends wildcard to query for prefix matching:

typescript
const adjustedQuery = `${q}*`

Error Handling ​

Missing Authorization ​

typescript
throw createError({
  statusCode: 401,
  statusMessage: 'Authorization header is required'
})

Invalid Token ​

typescript
throw createError({
  statusCode: 401,
  statusMessage: 'Unauthorized - Invalid token or insufficient permissions'
})

Missing Parameters ​

typescript
throw createError({
  statusCode: 400,
  statusMessage: 'Missing required parameters in the request.'
})

Invalid Collections ​

typescript
throw createError({
  statusCode: 400,
  statusMessage: 'Collection name is required in the request.'
})

Invalid Sort By ​

typescript
throw createError({
  statusCode: 400,
  statusMessage: 'Parameter `sort_by` is malformed. It should be in the format "field:asc" or "field:desc".'
})

Typesense Errors ​

typescript
// TypesenseConnectionError
throw createError({
  statusCode: 503,
  statusMessage: 'Typesense service unavailable'
})

// Other Typesense errors
throw createError({
  statusCode: error.statusCode || 500,
  statusMessage: error.message || 'An unexpected error occurred.'
})

Usage ​

typescript
const { $api } = useNuxtApp()

// Search multiple collections
const results = await $api('/api/typesense/search', {
  method: 'POST',
  body: {
    request: {
      q: 'logo',
      collections: ['assets', 'folders'],
      sort_by: 'created_at:desc',
      include_fields: {
        assets: ['id', 'name', 'url', 'file_type'],
        folders: ['id', 'name', 'description']
      }
    },
    commonSearchParams: {
      query_by: 'name,description',
      per_page: 20,
      page: 1
    },
    workspace_id_filter: workspaceId,
    filterQuery: {
      assets: 'file_type:image',
      folders: 'status:active'
    }
  }
})

// Access results
const assetResults = results.assets.data
const folderResults = results.folders.data

Request Flow ​

  1. Extract Token: Read Authorization header
  2. Verify User: Call backend API to verify token and get user data
  3. Extract Instance: Find matching workspace instance
  4. Validate Parameters: Check all required parameters
  5. Build Search Requests: Create Typesense search requests for each collection
  6. Apply Filters: Add instance filter and custom filters
  7. Execute Search: Call performMultiSearch from utils
  8. Format Results: Format results by collection name
  9. Return Response: Return formatted results

Security Considerations ​

  1. Server-Side API Key: Typesense API key never exposed to client
  2. Token Validation: All requests require valid authentication token
  3. Workspace Access: Validates user has access to requested workspace
  4. Instance Filtering: Automatically filters by instance to prevent data leakage
  5. Input Validation: Validates all input parameters