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](./http-server.md) 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:

```go
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:

```go
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

```json
{
  "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

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

### Query Recent Logs

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

### Get Log Statistics

```bash
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](./http-server.md) - Complete endpoint reference with request/response examples
- [Hypercore Log System](../internal/logging.md) - Distributed log architecture
- [Reasoning Engine](../packages/reasoning.md) - AI provider integration
- [Architecture Overview](../architecture/system-overview.md) - System architecture

## Support

For issues or questions:
- Check existing GitHub issues
- Review inline code documentation
- Consult system architecture diagrams
- Contact the development team