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
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.cosmasense.tech/llms.txt

Use this file to discover all available pages before exploring further.

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.