Magic Hour Documentation Audit
Magic Hour's API docs are unusually agent-friendly on the surface — llms.txt and llms-full.txt both resolve, every page serves clean .md, there's a published OpenAPI spec, a mock server, and an MCP server — but the reference index contradicts the spec, and the billing pages contradict the live pricing page in both directions.
1. API Reference index lists wrong paths for all three Files endpoints (critical)
Location: https://docs.magichour.ai/api-reference/overview
Problem: The "Files" section of the API Reference overview lists:
POST /v1/files/generate-upload-urls— Generate asset upload URLsGET /v1/files/:id/face-detection— Get face detection detailsPOST /v1/files/face-detection— Detect faces in an asset
The published OpenAPI spec (https://docs.magichour.ai/api-reference/openapi.json) and the endpoint pages themselves use entirely different paths: POST /v1/files/upload-urls, GET /v1/face-detection/{id}, and POST /v1/face-detection. The generate-asset-upload-urls page repeatedly shows https://api.magichour.ai/v1/files/upload-urls in its cURL/PHP/Java samples — none of the three paths printed on the overview page exist in the spec.
Consequence: The overview is the page both humans and AI agents use to enumerate the API surface. Anyone who constructs a request from the index — instead of clicking through to each endpoint page — calls a nonexistent path and gets a 404. An agent that cross-references the index against the spec sees three endpoints that appear in one source and not the other, and fails silently or hallucinates a reconciliation.
The fix: Correct the three Files entries on /api-reference/overview to match the OpenAPI paths (/v1/files/upload-urls, /v1/face-detection, /v1/face-detection/{id}), and generate the index from the spec so it can't drift again.
2. Billing docs contradict the live pricing page on prices, credits, and credit packs (critical)
Location: https://docs.magichour.ai/billing/overview and https://docs.magichour.ai/billing/subscription-pricing
Problem: The docs say Creator is "$15/mo or $10/mo (yearly)" with "10,000 credits per month (120,000/year)" and Pro is "$45/mo or $30/mo (yearly)" with "30,000 credits per month (360,000/year)". The live page charges Creator $19/mo ($144 billed annually) with 144,000 credits/year, and Pro $39/mo ($300 billed annually) with 300,000 credits/year. Every Creator and Pro number disagrees, in both directions: the docs undersell Creator's price and credits, and oversell Pro's price and credits by $60/year and 60,000 credits. Credit packs disagree too: docs say "1,000 credits per pack, $3.00 per pack ($0.003 per credit)"; the pricing page sells packs at "$1 = 400 credits" ($0.0025/credit) in 4,000/12,000/32,000 sizes with no 1,000-credit option.