Skip to main content
POST
/
api
/
search
Search Files
curl --request POST \
  --url https://api.example.com/api/search/ \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "directory": "<string>",
  "filters": {},
  "limit": 123
}
'
{
  "results": [
    {
      "file": {
        "file_path": "<string>",
        "filename": "<string>",
        "extension": "<string>",
        "created": "<string>",
        "modified": "<string>",
        "accessed": "<string>",
        "title": {},
        "summary": {},
        "keywords": {}
      },
      "relevance_score": 123
    }
  ]
}
Search indexed files using natural language queries with hybrid semantic and keyword search.

​
Request

​
query
string
required
Natural language search queryExamples:
  • “tax documents from 2023”
  • “python code with API calls”
  • “meeting notes about project roadmap”
​
directory
string
Optional directory path to scope the search to
​
filters
object
Optional key-value filters
​
limit
number
default:"50"
Maximum number of results to return

​
Request Example

cURL
curl -X POST http://localhost:60534/api/search/ \
  -H "Content-Type: application/json" \
  -d '{
    "query": "meeting notes",
    "limit": 10
  }'
Python
import requests

response = requests.post(
    'http://localhost:60534/api/search/',
    json={
        'query': 'meeting notes',
        'directory': '/Users/username/Documents',
        'limit': 10
    }
)

for result in response.json()['results']:
    print(f"{result['file']['filename']}: {result['relevance_score']}")

​
Response

​
results
array
Array of search results sorted by relevance score (descending)

​
Response Example

200 Success
{
  "results": [
    {
      "file": {
        "file_path": "/Users/username/Documents/Q4-planning.md",
        "filename": "Q4-planning.md",
        "extension": "md",
        "created": "2025-01-15T10:30:00",
        "modified": "2025-01-15T14:22:00",
        "accessed": "2025-01-15T14:22:00",
        "title": "Q4 Planning Meeting Notes",
        "summary": "Discussion of Q4 roadmap including feature priorities and timeline.",
        "keywords": ["planning", "Q4", "roadmap", "meeting"]
      },
      "relevance_score": 0.89
    }
  ]
}

​
Search Algorithm

CosmaSense uses a hybrid search combining:
  1. Semantic Search (Vector Similarity) - embeds query using e5-base-v2, calculates cosine similarity
  2. Keyword Search (FTS5) - SQLite full-text search with BM25 ranking
  3. Combined Score = semantic_score + keyword_score
Search is a POST request with a JSON body, not a GET with query parameters.