API_ENDPOINTS.md

# Multi-Agent Content Generation System - API Endpoints

**Base URL:** `http://localhost:7860`  
**Port:** `7860` (all agents on single port)

---

## Health & Status

### Health Check
```
GET /health
```
Returns system health status and current run ID.

**Response:**
```json
{
  "status": "healthy",
  "run_id": "uuid",
  "port": 7860
}
```

### Root Endpoint
```
GET /
```
Returns API information and available endpoints.

---

## Pipeline Endpoints

### Execute Full Pipeline
```
POST /api/pipeline/execute
```
Execute the complete 7-stage content generation pipeline.

**Request Body:**
```json
{
  "user_brief": "string",
  "season_arc_document": "string",
  "character_bible": "string",
  "world_building_document": "string",
  "character_voice_guide": "string",
  "style_guide": "string",
  "continuity_log": "string",
  "hook_brief": "string (optional)"
}
```

**Response:**
```json
{
  "run_id": "uuid",
  "status": "success",
  "final_output": { ... },
  "hf_output_url": "https://huggingface.co/...",
  "hf_metadata_url": "https://huggingface.co/..."
}
```

### Get Pipeline Status
```
GET /api/pipeline/status/{run_id}
```
Get the status and state of a specific pipeline run.

**Response:**
```json
{
  "run_id": "uuid",
  "status": "completed|failed|running",
  "pipeline_state": { ... }
}
```

---

## Agent Endpoints

All agents run on port 7860 with dedicated endpoints.

### 1. Showrunner Agent
```
POST /api/agents/showrunner
```
Generate episode directive from user brief.

**Input:**
```json
{
  "user_brief": "string",
  "season_arc_document": "string",
  "character_bible": "string"
}
```

**Output:**
```json
{
  "episode_directive": "string",
  "story_premise": "string",
  "tone_brief": "string",
  "character_focus_notes": "string"
}
```

---

### 2. Story Editor Agent
```
POST /api/agents/story-editor
```
Generate episode outline from directive.

**Input:**
```json
{
  "episode_directive": "string",
  "series_continuity_log": "string",
  "character_list": ["Alex", "Jordan", "Casey", "Morgan"]
}
```

**Output:**
```json
{
  "episode_outline": "string",
  "act_structure": "string",
  "story_notes_for_writers": "string"
}
```

---

### 3. Cultural Consultant Agent
```
POST /api/agents/cultural-consultant
```
Review outline for cultural accuracy.

**Input:**
```json
{
  "episode_outline": "string",
  "world_building_document": "string",
  "character_list": ["Alex", "Jordan", "Casey", "Morgan"]
}
```

**Output:**
```json
{
  "cultural_accuracy_notes": "string",
  "flagged_inaccuracies": ["issue1", "issue2"],
  "approved_touchpoints": ["touchpoint1"],
  "reference_suggestions": ["suggestion1"]
}
```

---

### 4. Lead Writer Agent
```
POST /api/agents/lead-writer
```
Write episode script from outline and cultural notes.

**Input:**
```json
{
  "approved_outline": "string",
  "cultural_consultant_notes": "string",
  "character_voice_guide": "string",
  "character_list": ["Alex", "Jordan", "Casey", "Morgan"],
  "story_premise": "string"
}
```

**Output:**
```json
{
  "full_episode_first_draft": "string",
  "scene_descriptions": "string",
  "dialogue": "string",
  "stage_directions": "string"
}
```

---

### 5. Dialogue Specialist Agent
```
POST /api/agents/dialogue-specialist
```
Polish dialogue in the script.

**Input:**
```json
{
  "first_draft_script": "string (must not be empty)",
  "character_voice_guide": "string",
  "character_list": ["Alex", "Jordan", "Casey", "Morgan"],
  "dialect_slang_reference": "string"
}
```

**Output:**
```json
{
  "dialogue_polished_script": "string",
  "voice_consistency_notes": "string"
}
```

---

### 6. Comedy Writer Agent
```
POST /api/agents/comedy-writer
```
Add humor and punch-ups to the script.

**Input:**
```json
{
  "dialogue_polished_script": "string (must not be empty)",
  "hook_brief_from_showrunner": "string",
  "character_list": ["Alex", "Jordan", "Casey", "Morgan"],
  "tone_brief": "string"
}
```

**Output:**
```json
{
  "comedy_sharpened_script": "string",
  "punch_up_notes": "string",
  "hook_rewrite_for_opening": "string"
}
```

---

### 7. Proofreader Agent
```
POST /api/agents/proofreader
```
Final quality control on the script.

**Input:**
```json
{
  "comedy_sharpened_script": "string (must not be empty)",
  "style_guide": "string",
  "continuity_log": "string",
  "character_list": ["Alex", "Jordan", "Casey", "Morgan"]
}
```

**Output:**
```json
{
  "final_locked_script": "string",
  "qc_report": {
    "issues": [],
    "style_alignment": "string",
    "character_consistency": "string",
    "formatting_notes": "string",
    "recommendations": []
  },
  "continuity_log_update": "string"
}
```

---

## API Usage Examples

### Example 1: Execute Full Pipeline
```bash
curl -X POST http://localhost:7860/api/pipeline/execute \
  -H "Content-Type: application/json" \
  -d '{
    "user_brief": "A tech startup launches a new app",
    "season_arc_document": "Season 1: The Rise",
    "character_bible": "Alex (CEO), Jordan (CTO), Casey (Designer), Morgan (Marketer)",
    "world_building_document": "Modern Silicon Valley",
    "character_voice_guide": "Alex: sarcastic, Jordan: technical, Casey: perfectionist, Morgan: optimistic",
    "style_guide": "Fast-paced, comedic, tech satire",
    "continuity_log": "Episode 1: Team formation, Episode 2: First failure, Episode 3: Launch day"
  }'
```

### Example 2: Call Individual Agent
```bash
curl -X POST http://localhost:7860/api/agents/showrunner \
  -H "Content-Type: application/json" \
  -d '{
    "user_brief": "A tech startup launches a new app",
    "season_arc_document": "Season 1: The Rise",
    "character_bible": "Alex (CEO), Jordan (CTO), Casey (Designer), Morgan (Marketer)"
  }'
```

### Example 3: Check Pipeline Status
```bash
curl -X GET http://localhost:7860/api/pipeline/status/0e35979c-8240-4451-a693-6bed1516aa4d
```

---

## Error Handling

All endpoints return appropriate HTTP status codes:

- **200 OK** - Successful request
- **400 Bad Request** - Invalid input
- **404 Not Found** - Resource not found
- **500 Internal Server Error** - Server error

Error responses include a detail message:
```json
{
  "detail": "Error message explaining what went wrong"
}
```

---

## Documentation

- **Interactive API Docs:** `http://localhost:7860/docs` (Swagger UI)
- **Alternative Docs:** `http://localhost:7860/redoc` (ReDoc)

---

## Architecture

```
Port 7860 (Single Port)
├── /health
├── /
├── /api/pipeline/
│   ├── execute
│   └── status/{run_id}
└── /api/agents/
    ├── showrunner
    ├── story-editor
    ├── cultural-consultant
    ├── lead-writer
    ├── dialogue-specialist
    ├── comedy-writer
    └── proofreader
```

All agents communicate through the orchestrator and share state via the pipeline.