Search Files

POST /api/search

Search Files

cURL

curl --request POST \
  --url https://api.example.com/api/search/ \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "directory": "<string>",
  "filters": {},
  "limit": 123
}
'

200

{
  "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 query

Examples:

• “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)

Show result object

file · object

File metadata

Show file fields

file_path · string

Absolute path to the file

filename · string

File name

extension · string

File extension

created · string

ISO 8601 creation timestamp

modified · string

ISO 8601 modification timestamp

accessed · string

ISO 8601 last access timestamp

title · string | null

AI-generated title

summary · string | null

AI-generated summary

keywords · array | null

AI-generated keywords

relevance_score · number

Combined search relevance score (higher is better)

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.