docs/API.md

# API Documentation

## Overview

The Multi-Agent System provides a RESTful API for task execution, workflow management, and agent coordination.

Base URL: `http://localhost:8000`

## Authentication

Currently, the API is open. For production, implement JWT or API key authentication.

## Endpoints

### Health Check

#### GET `/health`
Check if the service is healthy.

**Response:**
```json
{
  "status": "healthy",
  "version": "0.1.0"
}
```

#### GET `/ready`
Check if the service is ready to accept requests.

**Response:**
```json
{
  "status": "ready",
  "version": "0.1.0"
}
```

### Tasks

#### POST `/tasks`
Create and execute a new task.

**Request Body:**
```json
{
  "task": "Analyze the latest market trends for tech stocks",
  "task_id": "optional-custom-id"
}
```

**Response:**
```json
{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "task": "Analyze the latest market trends for tech stocks",
  "status": "processing"
}
```

#### GET `/tasks/{task_id}`
Get the status and results of a task.

**Response:**
```json
{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "task": "Analyze the latest market trends for tech stocks",
  "status": "completed"
}
```

#### DELETE `/tasks/{task_id}`
Cancel a running task.

**Response:**
```json
{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "cancelled"
}
```

### Workflows

#### POST `/workflows/execute`
Execute a workflow with optional streaming.

**Request Body:**
```json
{
  "task": "Fetch weather data and create a report",
  "stream": false
}
```

**Response (Non-streaming):**
```json
{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "result": null
}
```

**Response (Streaming):**
Server-Sent Events (SSE) with real-time updates:
```
data: {"agent": "planner", "step": 1, "status": "planning"}
data: {"agent": "executor", "step": 1, "status": "executing", "action": "web_search"}
data: {"agent": "executor", "step": 2, "status": "executing", "result": "..."}
```

#### GET `/workflows/{task_id}/status`
Get the current status of a workflow.

**Response:**
```json
{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "running",
  "progress": 50,
  "current_agent": "executor"
}
```

## Error Handling

All errors follow this format:

```json
{
  "detail": "Error description",
  "status": 400
}
```

### Status Codes

- `200` - Success
- `201` - Created
- `400` - Bad Request
- `404` - Not Found
- `500` - Internal Server Error

## Rate Limiting

Currently not implemented. For production, consider adding:
- Request rate limits per API key
- Concurrent task limits
- Token usage tracking

## Examples

### Create and Execute Task

```bash
curl -X POST "http://localhost:8000/tasks" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Find information about Python 3.11 release notes"
  }'
```

### Stream Workflow Results

```bash
curl -X POST "http://localhost:8000/workflows/execute" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Summarize recent AI breakthroughs",
    "stream": true
  }'
```

### Check Task Status

```bash
curl "http://localhost:8000/tasks/550e8400-e29b-41d4-a716-446655440000"
```

## Python Client Example

```python
import requests

API_URL = "http://localhost:8000"

# Create task
response = requests.post(f"{API_URL}/tasks", json={
    "task": "Analyze competitor pricing strategies"
})
task_id = response.json()["task_id"]

# Get status
status_response = requests.get(f"{API_URL}/tasks/{task_id}")
print(status_response.json())

# Stream workflow
with requests.post(f"{API_URL}/workflows/execute", 
                   json={"task": "...", "stream": True}, 
                   stream=True) as response:
    for line in response.iter_lines():
        if line:
            print(line.decode('utf-8'))
```

## Interactive API Documentation

Visit `http://localhost:8000/docs` for Swagger UI with interactive testing.

Visit `http://localhost:8000/redoc` for ReDoc documentation.