CHORUS/docs/comprehensive/api/README.md

CHORUS API Overview

Introduction

The CHORUS API provides HTTP REST endpoints for interacting with the CHORUS autonomous agent system. The API exposes functionality for accessing distributed logs, system health monitoring, and setup/configuration management.

Architecture

The API layer consists of two primary components:

1. HTTPServer (api/http_server.go) - Core REST API server providing runtime access to system data
2. SetupManager (api/setup_manager.go) - Configuration and initial setup API for system initialization

Base Configuration

• Default Port: Configurable (typically 8080)
• Protocol: HTTP/1.1
• Content-Type: application/json
• CORS: Enabled for all origins (suitable for development; restrict in production)

Authentication

Current Status: No authentication required

The API currently operates without authentication. For production deployments, consider implementing:

• Bearer token authentication
• API key validation
• OAuth2/OIDC integration
• mTLS for service-to-service communication

Core Components

HTTPServer

The main API server handling runtime operations:

• Hypercore Log Access - Query distributed log entries with flexible filtering
• Health Monitoring - System health and status checks
• Statistics - Log and system statistics

SetupManager

Handles initial system configuration and discovery:

• System Detection - Hardware, network, and software environment discovery
• Repository Configuration - Git provider setup and validation
• Network Discovery - Automatic detection of cluster machines
• SSH Testing - Remote system access validation

API Endpoints

See HTTP Server Documentation for complete endpoint reference.

Quick Reference

Endpoint	Method	Purpose
/api/health	GET	Health check
/api/status	GET	Detailed system status
/api/hypercore/logs	GET	Query log entries
/api/hypercore/logs/recent	GET	Recent log entries
/api/hypercore/logs/since/{index}	GET	Logs since index
/api/hypercore/logs/stats	GET	Log statistics

Integration Points

Hypercore Log Integration

The API directly integrates with CHORUS's distributed Hypercore-inspired log system:

type HypercoreLog interface {
    Length() uint64
    GetRange(start, end uint64) ([]LogEntry, error)
    GetRecentEntries(limit int) ([]LogEntry, error)
    GetEntriesSince(index uint64) ([]LogEntry, error)
    GetStats() map[string]interface{}
}

Log Entry Types:

• Task coordination (announced, claimed, progress, completed, failed)
• Meta-discussion (plan proposed, objection raised, consensus reached)
• System events (peer joined/left, capability broadcast, network events)

PubSub Integration

The HTTPServer includes PubSub integration for real-time event broadcasting:

type PubSub interface {
    Publish(topic string, message interface{}) error
    Subscribe(topic string) (chan interface{}, error)
}

Topics:

• Task updates
• System events
• Peer connectivity changes
• Log replication events

Response Formats

Standard Success Response

{
  "entries": [...],
  "count": 50,
  "timestamp": 1727712345,
  "total": 1024
}

Standard Error Response

HTTP error status codes with plain text error messages:

HTTP/1.1 400 Bad Request
Invalid start parameter

HTTP/1.1 500 Internal Server Error
Failed to get log entries: database connection failed

CORS Configuration

The API implements permissive CORS for development:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization

Production Recommendation: Restrict Access-Control-Allow-Origin to specific trusted domains.

Timeouts

• Read Timeout: 15 seconds
• Write Timeout: 15 seconds
• Idle Timeout: 60 seconds

Error Handling

The API uses standard HTTP status codes:

• 200 OK - Successful request
• 400 Bad Request - Invalid parameters or malformed request
• 404 Not Found - Resource not found
• 500 Internal Server Error - Server-side error

Error responses include descriptive error messages in the response body.

Usage Examples

Health Check

curl http://localhost:8080/api/health

Query Recent Logs

curl http://localhost:8080/api/hypercore/logs/recent?limit=10

Get Log Statistics

curl http://localhost:8080/api/hypercore/logs/stats

Performance Considerations

• Pagination: Use limit parameters to avoid large result sets
• Caching: Consider implementing response caching for frequently accessed data
• Rate Limiting: Not currently implemented; add for production use
• Connection Pooling: Server handles concurrent connections efficiently

Future Enhancements

1. WebSocket Support - Real-time log streaming and event notifications
2. Authentication - Bearer token or API key authentication
3. Rate Limiting - Per-client rate limiting and quota management
4. GraphQL Endpoint - Flexible query interface for complex data requirements
5. Metrics Export - Prometheus-compatible metrics endpoint
6. API Versioning - Version prefix in URL path (e.g., /api/v1/, /api/v2/)

Related Documentation

• HTTP Server Details - Complete endpoint reference with request/response examples
• Hypercore Log System - Distributed log architecture
• Reasoning Engine - AI provider integration
• Architecture Overview - System architecture

Support

For issues or questions:

• Check existing GitHub issues
• Review inline code documentation
• Consult system architecture diagrams
• Contact the development team