# Magic Wand UI — API Contract for Daedalus

**From:** Socrates 🧠  
**To:** Daedalus 🎨  
**Date:** 2026-04-22  
**Status:** Backend Ready — Frontend Integration Needed

---

## Overview

The 5-stage LocalAI content generation pipeline is live and authenticated. This document specifies how the Magic Wand UI should integrate with the backend.

---

## Base URL

```
https://notes.hoffdesk.com/admin/content
```

**Authentication:** All endpoints require `?token=hoffdesk-admin-2025` query param OR `X-Admin-Token: hoffdesk-admin-2025` header.

---

## Endpoints

### 1. Health Check
**GET** `/health`

Returns Gaming PC availability and model status.

**Response:**
```json
{
  "gaming_pc": {"available": true, "reason": "Ollama responding"},
  "models": {
    "strategy": "llama3.1:8b",
    "structure": "qwen2.5-coder:7b",
    "draft": "phi4:14b",
    "seo": "llama3.1:8b"
  },
  "pipeline_ready": true
}
```

---

### 2. Start Generation (Magic Wand Action)
**POST** `/generate?token=hoffdesk-admin-2025`

**Request Body:**
```json
{
  "topic": "Building a home AI assistant",
  "content_type": "how_i_solved",
  "outline": null,
  "context": "Optional additional context"
}
```

**Content Types:**
- `"how_i_solved"` — Problem → Solution narrative
- `"deep_dive"` — Technical exploration
- `"news_roundup"` — Curated updates
- `"opinion"` — Hot take with evidence

**Response:**
```json
{
  "job_id": "gen_20260422_015819_623397",
  "status": "queued",
  "estimated_seconds": 90
}
```

---

### 3. Poll for Progress
**GET** `/jobs/{job_id}?token=hoffdesk-admin-2025`

**Response (in progress):**
```json
{
  "job_id": "gen_20260422_015819_623397",
  "status": "strategy",
  "stage_number": 1,
  "total_stages": 5,
  "progress_percent": 10,
  "current_stage_name": "Generating content brief...",
  "estimated_seconds_remaining": 5,
  "started_at": "2026-04-22T01:58:19",
  "completed_at": null,
  "error": null,
  "result": null
}
```

**Response (completed):**
```json
{
  "job_id": "gen_20260422_015819_623397",
  "status": "completed",
  "stage_number": 5,
  "total_stages": 5,
  "progress_percent": 100,
  "current_stage_name": "Final compliance check...",
  "estimated_seconds_remaining": 0,
  "started_at": "2026-04-22T01:58:19",
  "completed_at": "2026-04-22T01:59:45",
  "error": null,
  "result": {
    "title": "How I Built a Home AI Assistant",
    "slug": "how-i-built-home-ai-assistant",
    "content_md": "# How I Built a Home AI Assistant\n\nFull markdown content here...",
    "excerpt": "Six months of basement tinkering...",
    "tags": ["ai", "homelab", "openclaw"],
    "category": "homelab",
    "seo": {
      "meta_description": "...",
      "keywords": [...]
    },
    "compliance": {
      "passed": true,
      "issues": []
    }
  }
}
```

**Polling Strategy:** Poll every 2-3 seconds until `status` is `completed` or `failed`.

---

### 4. Cancel Job
**POST** `/jobs/{job_id}/cancel?token=hoffdesk-admin-2025`

**Response:**
```json
{
  "job_id": "gen_20260422_015819_623397",
  "was_cancelled": true,
  "message": "Job cancelled"
}
```

---

## UI Integration Flow

```
User clicks Magic Wand
    ↓
POST /generate → Receive job_id
    ↓
Show progress bar (poll /jobs/{id} every 2s)
    ↓
Status: queued → strategy → structure → draft → seo → compliance
    ↓
On completed:
    - Fill title input
    - Fill content editor with result.content_md
    - Fill excerpt, tags, category
    - Show "SEO Ready" badge
    - Enable "Save Draft" button
```

---

## Stage Progress Mapping

| Stage | progress_percent | Stage Name | Duration |
|-------|------------------|------------|----------|
| queued | 0% | "Waiting to start..." | ~1s |
| strategy | 10% | "Generating content brief..." | ~15s |
| structure | 30% | "Creating outline..." | ~15s |
| draft | 50% | "Writing first draft..." | ~30s |
| seo | 80% | "Optimizing for search..." | ~15s |
| compliance | 90% | "Final compliance check..." | ~5s |
| completed | 100% | "Ready to publish" | — |

---

## HTMX Implementation Notes

**Start Generation:**
```html
<button hx-post="/admin/content/generate?token=hoffdesk-admin-2025"
        hx-target="#generation-result"
        hx-swap="innerHTML"
        hx-headers='{"Content-Type": "application/json"}'
        hx-vals='{"topic": "...", "content_type": "how_i_solved"}'>
  ✨ Generate with AI
</button>
```

**Poll Progress:**
```html
<div hx-get="/admin/content/jobs/{job_id}?token=hoffdesk-admin-2025"
     hx-trigger="every 2s"
     hx-target="this">
  <!-- Progress content -->
</div>
```

---

## Error Handling

| HTTP | Meaning | Action |
|------|---------|--------|
| 401 | Unauthorized | Redirect to login |
| 404 | Job not found | Show "Job expired" message |
| 422 | Validation error | Check content_type enum |
| 500 | Pipeline failed | Show "Try again" with error details |

---

## Testing

**Quick test:**
```bash
curl -X POST "https://notes.hoffdesk.com/admin/content/generate?token=hoffdesk-admin-2025" \
  -H "Content-Type: application/json" \
  -d '{"topic":"Test post","content_type":"how_i_solved"}'
```

Then poll:
```bash
curl "https://notes.hoffdesk.com/admin/content/jobs/{job_id}?token=hoffdesk-admin-2025"
```

---

## Backend Status

- ✅ Gaming PC (phi4:14b, qwen2.5-coder:7b) responding
- ✅ 5-stage pipeline tested and working
- ✅ Token auth implemented
- ✅ ~90 second total generation time
- ✅ Compliance filter (Sovereign Stack voice)
- ⏳ Awaiting Magic Wand UI integration

---

*Document: `shared/project-docs/blog/magic-wand-api-contract.md`*  
*Author: Socrates 🧠*  
*For: Daedalus 🎨 (Frontend), Matt (Director)*