Skip to content

API.md

Latest commit

 

History

History
430 lines (341 loc) · 6.68 KB

API.md

File metadata and controls

430 lines (341 loc) · 6.68 KB

API Reference

Complete REST API documentation for ATLES-ECHO.

Base URL

http://localhost:5001/api

Authentication

All API requests require an API key in the header:

X-API-Key: your-api-key-here

Endpoints

System

GET /system/health

Get system health status.

Response:

{
  "status": "healthy",
  "uptime": 3600,
  "version": "1.0.0",
  "components": {
    "embedding_engine": "healthy",
    "vector_db": "healthy",
    "knowledge_db": "healthy",
    "watchers": "healthy"
  }
}

GET /system/stats

Get system statistics.

Response:

{
  "statistics": {
    "total_embeddings": 1234,
    "total_knowledge_items": 5678,
    "database_size_mb": 45.2,
    "index_size_mb": 12.3,
    "avg_embedding_time_ms": 45.0,
    "avg_search_time_ms": 12.0
  },
  "performance": {
    "embeddings_per_second": 220.0,
    "searches_per_second": 150.0
  }
}

Embeddings

POST /embed

Generate embedding for text.

Request:

{
  "text": "Example text to embed",
  "normalize": true
}

Response:

{
  "embedding": [0.123, -0.456, ...],  // 768-dim vector
  "dimension": 768,
  "processing_time_ms": 42.5
}

POST /embed/batch

Generate embeddings for multiple texts.

Request:

{
  "texts": ["Text 1", "Text 2", "Text 3"],
  "normalize": true
}

Response:

{
  "embeddings": [[...], [...], [...]],
  "dimension": 768,
  "count": 3,
  "processing_time_ms": 125.3
}

Search

GET /search

Semantic search across all knowledge.

Parameters:

  • q (string, required): Search query
  • limit (int, optional): Number of results (default: 10)
  • threshold (float, optional): Similarity threshold 0-1 (default: 0.5)

Example:

GET /api/search?q=react%20component&limit=5&threshold=0.7

Response:

{
  "results": [
    {
      "id": "abc123",
      "content": "export const MyComponent...",
      "similarity": 0.89,
      "source_type": "file",
      "source_path": "/path/to/component.tsx",
      "created_at": "2025-11-30T12:34:56"
    }
  ],
  "query": "react component",
  "count": 5,
  "search_time_ms": 15.2
}

POST /similarity

Calculate similarity between two texts.

Request:

{
  "text1": "First text",
  "text2": "Second text"
}

Response:

{
  "similarity": 0.75,
  "processing_time_ms": 38.2
}

Knowledge

POST /knowledge/store

Manually store knowledge.

Request:

{
  "content": "Important note to remember",
  "source_type": "manual",
  "metadata": {
    "tags": ["important", "note"]
  }
}

Response:

{
  "id": "xyz789",
  "message": "Knowledge stored successfully"
}

GET /knowledge/context

Get contextual knowledge for a query.

Parameters:

  • query (string, required): Context query
  • max_results (int, optional): Maximum results (default: 5)

Example:

GET /api/knowledge/context?query=authentication&max_results=10

Response:

{
  "context": [
    {
      "content": "JWT authentication implementation...",
      "relevance": 0.92
    }
  ]
}

GET /knowledge/items

List knowledge items with pagination.

Parameters:

  • limit (int): Items per page (default: 50)
  • offset (int): Pagination offset (default: 0)
  • source_type (string, optional): Filter by source
  • hours (int): Last N hours (default: 24)

Example:

GET /api/knowledge/items?limit=20&offset=0&source_type=file

Response:

{
  "items": [...],
  "total": 123,
  "limit": 20,
  "offset": 0
}

Reports

POST /reports/generate

Generate a report.

Parameters:

  • report_type (string): Type of report (daily, activity)

Example:

POST /api/reports/generate?report_type=daily

Response:

{
  "status": "success",
  "report_file": "../reports/ECHO_Report_DailySummary_20251130_123456.md",
  "message": "Report generated successfully"
}

GET /reports/list

List all generated reports.

Response:

{
  "reports": [
    {
      "filename": "ECHO_Report_DailySummary_20251130_123456.md",
      "path": "../reports/ECHO_Report_DailySummary_20251130_123456.md",
      "size_kb": 12.5,
      "created": "2025-11-30T12:34:56"
    }
  ]
}

WebSocket API

Connection

const ws = new WebSocket('ws://localhost:5001/ws/events');

Events

ATLES-ECHO broadcasts events in real-time:

{
  "type": "file.modified",
  "data": {
    "path": "/path/to/file.py",
    "content_preview": "def main()..."
  },
  "timestamp": "2025-11-30T12:34:56"
}

Event Types:

  • file.created
  • file.modified
  • file.deleted
  • screen.captured
  • clipboard.captured
  • keystroke.captured
  • app.changed
  • knowledge.stored
  • idle.detected

Error Responses

400 Bad Request

{
  "detail": "Invalid request parameters"
}

401 Unauthorized

{
  "detail": "Invalid API key"
}

404 Not Found

{
  "detail": "Resource not found"
}

500 Internal Server Error

{
  "detail": "Internal server error"
}

Rate Limits

No rate limits for local deployment.

Examples

Python

import requests

API_KEY = "your-api-key"
BASE_URL = "http://localhost:5001/api"

headers = {"X-API-Key": API_KEY}

# Search
response = requests.get(
    f"{BASE_URL}/search",
    params={"q": "react component", "limit": 5},
    headers=headers
)
results = response.json()["results"]

# Store knowledge
response = requests.post(
    f"{BASE_URL}/knowledge/store",
    json={
        "content": "Important note",
        "source_type": "manual"
    },
    headers=headers
)

JavaScript

const API_KEY = 'your-api-key';
const BASE_URL = 'http://localhost:5001/api';

// Search
const searchResults = await fetch(
  `${BASE_URL}/search?q=react+component&limit=5`,
  {
    headers: {
      'X-API-Key': API_KEY
    }
  }
).then(r => r.json());

// Store knowledge
await fetch(`${BASE_URL}/knowledge/store`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': API_KEY
  },
  body: JSON.stringify({
    content: 'Important note',
    source_type: 'manual'
  })
});

cURL

# Search
curl -X GET "http://localhost:5001/api/search?q=react+component&limit=5" \
  -H "X-API-Key: your-api-key"

# Store knowledge
curl -X POST "http://localhost:5001/api/knowledge/store" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"content": "Important note", "source_type": "manual"}'

# Generate report
curl -X POST "http://localhost:5001/api/reports/generate?report_type=daily" \
  -H "X-API-Key: your-api-key"

See also: Architecture | Privacy