Skip to main content

​
Welcome

The CosmaSense backend exposes a RESTful API for managing file indexing and search operations. The backend runs on port 60534 by default. Base URL: http://localhost:60534 All endpoints are local-only and require no authentication. The backend is designed to run on your local machine and is not intended to be exposed to the internet.

​
Quick Start

Start the backend server: 
cosma serve
Test the connection: 
curl http://localhost:60534/api/health

​
Core Endpoints

Watch Directory

Add a directory to the watch list and start indexing

Search Files

Search indexed files using natural language queries

Get Watched Directories

List all directories currently being watched

Real-time Updates

Stream processing status updates via Server-Sent Events

​
Response Format

All API responses follow a consistent JSON format: 
{
  "status": "success",
  "data": { ... },
  "error": null
}
Error responses: 
{
  "status": "error",
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid directory path"
  }
}

​
Data Flow

​
Rate Limiting

The backend does not implement rate limiting as it’s designed for local use only. However, the TUI implements client-side throttling (0.5s) for search queries to reduce unnecessary API calls.

​
File Processing States

When files are being indexed, they go through several states:
StateDescription
pendingFile discovered, waiting to be processed
parsingExtracting content from file
summarizingAI generating summary and keywords
embeddingCreating vector embedding
completeSuccessfully indexed
failedError during processing
You can monitor these states in real-time using the /api/updates SSE endpoint.