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:
{
"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:
{
"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:
{
"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):
{
"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):
{
"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:
{
"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:
<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:
<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:
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:
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)