Search

This endpoint provides semantic search capabilities across your saved memories using state-of-the-art embeddings. It returns relevant content ranked by similarity.

POST /api/search

Request Body

{
  // The search query to find relevant content
  query: string,
  
  // Maximum number of results to return (1-50, default: 10)
  limit?: number,
  
  // Minimum similarity threshold (0-1, default: 0)
  threshold?: number
}

Field Descriptions

Field	Type	Required	Description
`query`	string	Yes	Search query text (minimum 1 character)
`limit`	number	No	Maximum number of results (1-50, default: 10)
`threshold`	number	No	Minimum similarity score (0-1, default: 0)

Response

The endpoint returns an array of search results, sorted by relevance:

{
  results: Array<{
    // Document identifiers
    id: string,
    uuid: string,
    
    // Content fields
    content: string,      // Full document content
    chunkContent: string, // Matching content chunk
    
    // Metadata
    createdAt: string,    // ISO timestamp
    
    // Relevance score (0-1)
    similarity: number    // Rounded to 4 decimal places
  }>
}

Error Responses

400 Bad Request

{
  "error": "Search query cannot be empty"
}

401 Unauthorized

{
  "error": "Unauthorized"
}

500 Internal Server Error

{
  "error": "Search failed",
  "details": "Error details (in development mode)"
}

Examples

Basic Search

{
  "query": "machine learning concepts"
}

Advanced Search with Filters

{
  "query": "python programming",
  "limit": 20,
  "threshold": 0.5
}

Response Example

{
  "results": [
    {
      "id": "doc-123",
      "uuid": "abc-456",
      "content": "Python is a versatile programming language...",
      "chunkContent": "...particularly useful for machine learning...",
      "createdAt": "2024-03-20T12:00:00Z",
      "similarity": 0.8754
    },
    {
      "id": "doc-124",
      "uuid": "def-789",
      "content": "Programming basics include...",
      "chunkContent": "...Python syntax is straightforward...",
      "createdAt": "2024-03-19T15:30:00Z",
      "similarity": 0.7123
    }
  ]
}

Notes

Authentication is required
Results are sorted by similarity score (descending)
Similarity scores are normalized between 0 and 1
Content is automatically chunked for better matching
Performance optimizations include:
- Vector indexing
- Similarity thresholding
- Result limiting
- Score normalization
The API uses the BGE base embeddings model for semantic understanding
Supports both exact and semantic matching
Results include both full content and relevant chunks

List