{"openapi":"3.1.0","info":{"title":"Daily AI Brief Backend API","version":"1.0.0","description":"Cloudflare Workers + Hono + D1 + R2 backend for daily AI news collection, Chinese editorial curation, ElevenLabs TTS audio generation, and publishing."},"servers":[{"url":"https://elevenlabs.bytenote.net","description":"Production (Cloudflare Workers)"},{"url":"http://localhost:8787","description":"Local development (wrangler dev)"}],"tags":[{"name":"Public","description":"Public reading, audio streaming, health, and OpenAPI docs"},{"name":"Admin","description":"Protected news collection, AI editing, TTS audio, review, and publishing endpoints"}],"components":{"securitySchemes":{"AdminBearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token matching ADMIN_API_TOKEN (also accepted via X-Admin-Token header)."}},"schemas":{"ApiErrorResponse":{"type":"object","required":["ok","data","error","meta"],"properties":{"ok":{"type":"boolean","const":false},"data":{"type":"null"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}},"meta":{"type":"object","required":["request_id","timestamp"],"properties":{"request_id":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}},"Edition":{"type":"object","properties":{"id":{"type":"string"},"edition_date":{"type":"string","example":"2026-11-19"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","pending_review","approved","published","failed"]},"broadcast_script":{"type":"string"},"audio_asset_id":{"type":["string","null"]},"audio_url":{"type":["string","null"]},"published_at":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}}},"NewsItem":{"type":"object","properties":{"id":{"type":"string"},"edition_id":{"type":"string"},"raw_item_id":{"type":["string","null"]},"position":{"type":"integer"},"title_zh":{"type":"string"},"summary_zh":{"type":"string"},"content_zh":{"type":"string"},"broadcast_script":{"type":"string"},"source_name":{"type":"string"},"source_url":{"type":"string"},"published_at":{"type":["string","null"]},"collected_at":{"type":"string"},"verification_status":{"type":"string","enum":["verified","needs_verification"]},"verification_note":{"type":["string","null"]},"review_status":{"type":"string","enum":["pending","approved","rejected"]},"audio_asset_id":{"type":["string","null"]},"audio_url":{"type":["string","null"]}}},"AudioAsset":{"type":"object","properties":{"id":{"type":"string"},"target_type":{"type":"string","enum":["edition","news"]},"target_id":{"type":"string"},"edition_id":{"type":["string","null"]},"r2_key":{"type":"string"},"audio_url":{"type":"string"},"content_type":{"type":"string"},"byte_size":{"type":"integer"},"provider":{"type":"string","enum":["elevenlabs","mock"]},"model_id":{"type":"string"},"voice_id":{"type":"string"},"speed":{"type":"number"},"output_format":{"type":"string"},"status":{"type":"string","enum":["pending","completed","failed"]},"character_count":{"type":"integer"},"estimated_cost_usd":{"type":"number"},"chunk_count":{"type":"integer"},"timestamps":{"type":["object","null"]}}}}},"paths":{"/health":{"get":{"tags":["Public"],"summary":"Health check","responses":{"200":{"description":"Service health status","content":{"application/json":{"schema":{"type":"object","required":["ok","data","error","meta"],"properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"anyOf":[{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}},{"type":"null"}]},"meta":{"type":"object","required":["request_id","timestamp"],"properties":{"request_id":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}}}}}}}},"/openapi.json":{"get":{"tags":["Public"],"summary":"OpenAPI 3.1 JSON specification","responses":{"200":{"description":"OpenAPI specification document"}}}},"/docs":{"get":{"tags":["Public"],"summary":"Human-readable HTML API directory","responses":{"200":{"description":"HTML API documentation page"}}}},"/api/editions":{"get":{"tags":["Public"],"summary":"List published daily editions","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":50}},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0}}],"responses":{"200":{"description":"Paginated published editions","content":{"application/json":{"schema":{"type":"object","required":["ok","data","error","meta"],"properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Edition"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}},"error":{"anyOf":[{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}},{"type":"null"}]},"meta":{"type":"object","required":["request_id","timestamp"],"properties":{"request_id":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}}}}}}}},"/api/editions/{id}":{"get":{"tags":["Public"],"summary":"Get daily edition details, news items, and audio metadata","description":"Accepts either an edition ID (ed_...) or YYYY-MM-DD date. Unpublished editions return 404 unless valid admin auth is supplied.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Edition with news items and audio asset metadata","content":{"application/json":{"schema":{"type":"object","required":["ok","data","error","meta"],"properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"edition":{"$ref":"#/components/schemas/Edition"},"items":{"type":"array","items":{"$ref":"#/components/schemas/NewsItem"}},"audio":{"anyOf":[{"$ref":"#/components/schemas/AudioAsset"},{"type":"null"}]}}},"error":{"anyOf":[{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}},{"type":"null"}]},"meta":{"type":"object","required":["request_id","timestamp"],"properties":{"request_id":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}}}}},"404":{"description":"Edition not found"}}}},"/api/news/{id}":{"get":{"tags":["Public"],"summary":"Get single news article details and audio metadata","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Single news article and audio asset metadata","content":{"application/json":{"schema":{"type":"object","required":["ok","data","error","meta"],"properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"article":{"$ref":"#/components/schemas/NewsItem"},"audio":{"anyOf":[{"$ref":"#/components/schemas/AudioAsset"},{"type":"null"}]}}},"error":{"anyOf":[{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}},{"type":"null"}]},"meta":{"type":"object","required":["request_id","timestamp"],"properties":{"request_id":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}}}}},"404":{"description":"News article not found"}}}},"/api/audio/{key}":{"get":{"tags":["Public"],"summary":"Stream generated MP3 audio stored in R2","parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Binary MP3/audio stream","content":{"audio/mpeg":{}}},"404":{"description":"Audio file not found"}}}},"/api/admin/ingest":{"post":{"tags":["Admin"],"security":[{"AdminBearerAuth":[]}],"summary":"Ingest a single Chinese news article and optionally generate MP3 audio immediately (MVP path)","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional idempotency key to replay identical write requests safely.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","content"],"properties":{"title":{"type":"string"},"content":{"type":"string"},"summary":{"type":"string"},"broadcast_script":{"type":"string"},"source_name":{"type":"string"},"source_url":{"type":"string"},"published_at":{"type":"string"},"edition_date":{"type":"string"},"auto_approve":{"type":"boolean","default":false},"generate_audio":{"type":"boolean","default":true},"with_timestamps":{"type":"boolean","default":false},"voice_id":{"type":"string"},"model_id":{"type":"string"},"speed":{"type":"number","minimum":0.7,"maximum":1.2},"output_format":{"type":"string"}}}}}},"responses":{"201":{"description":"Article stored and audio generated"},"401":{"description":"Unauthorized"}}}},"/api/admin/collect":{"post":{"tags":["Admin"],"security":[{"AdminBearerAuth":[]}],"summary":"Collect and deduplicate AI news from configured RSS sources or inline feeds","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional idempotency key to replay identical write requests safely.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"source_ids":{"type":"array","items":{"type":"string"}},"inline_feeds":{"type":"array","items":{"type":"object","required":["source_name","xml"],"properties":{"source_name":{"type":"string"},"source_url":{"type":"string"},"xml":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"Collection report"},"401":{"description":"Unauthorized"}}}},"/api/admin/generate":{"post":{"tags":["Admin"],"security":[{"AdminBearerAuth":[]}],"summary":"Generate daily AI brief draft (5-10 Chinese items, pending review)","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional idempotency key to replay identical write requests safely.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"edition_date":{"type":"string","example":"2026-11-19"},"raw_item_ids":{"type":"array","items":{"type":"string"}},"force":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Generated or replayed daily draft"},"401":{"description":"Unauthorized"}}}},"/api/admin/audio":{"post":{"tags":["Admin"],"security":[{"AdminBearerAuth":[]}],"summary":"Generate TTS MP3 (and optional character timestamps) for an edition or single news item","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional idempotency key to replay identical write requests safely.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["target_type","target_id"],"properties":{"target_type":{"type":"string","enum":["edition","news"]},"target_id":{"type":"string"},"text":{"type":"string"},"voice_id":{"type":"string"},"model_id":{"type":"string"},"speed":{"type":"number","minimum":0.7,"maximum":1.2},"output_format":{"type":"string","default":"mp3_44100_128"},"with_timestamps":{"type":"boolean","default":false},"force":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Audio asset generated or replayed"},"401":{"description":"Unauthorized"}}}},"/api/admin/publish":{"post":{"tags":["Admin"],"security":[{"AdminBearerAuth":[]}],"summary":"Publish a reviewed edition to public endpoints","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional idempotency key to replay identical write requests safely.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"edition_id":{"type":"string"},"edition_date":{"type":"string"},"approved_news_ids":{"type":"array","items":{"type":"string"}},"rejected_news_ids":{"type":"array","items":{"type":"string"}},"approve_unverified":{"type":"boolean","default":false},"require_audio":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Published edition"},"409":{"description":"Unverified items require verification or explicit override"}}}},"/api/admin/news/{id}/review":{"patch":{"tags":["Admin"],"security":[{"AdminBearerAuth":[]}],"summary":"Review or edit a single news item before publishing","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"review_status":{"type":"string","enum":["pending","approved","rejected"]},"verification_status":{"type":"string","enum":["verified","needs_verification"]},"verification_note":{"type":["string","null"]},"title_zh":{"type":"string"},"summary_zh":{"type":"string"},"content_zh":{"type":"string"},"broadcast_script":{"type":"string"}}}}}},"responses":{"200":{"description":"Updated news item"},"404":{"description":"News item not found"}}}},"/api/admin/editions":{"get":{"tags":["Admin"],"security":[{"AdminBearerAuth":[]}],"summary":"List all editions across all statuses (including pending_review)","parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Editions list"}}}},"/api/admin/sources":{"get":{"tags":["Admin"],"security":[{"AdminBearerAuth":[]}],"summary":"List RSS sources","responses":{"200":{"description":"RSS sources list"}}},"post":{"tags":["Admin"],"security":[{"AdminBearerAuth":[]}],"summary":"Add or update an RSS source","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","url"],"properties":{"name":{"type":"string"},"url":{"type":"string"},"category":{"type":"string","default":"ai"},"language":{"type":"string","default":"en"},"enabled":{"type":"boolean","default":true}}}}}},"responses":{"201":{"description":"RSS source saved"}}}},"/api/admin/voices":{"get":{"tags":["Admin"],"security":[{"AdminBearerAuth":[]}],"summary":"List available TTS voices and recommended default Chinese news anchor","responses":{"200":{"description":"Voices and default Chinese selection"}}}},"/api/admin/models":{"get":{"tags":["Admin"],"security":[{"AdminBearerAuth":[]}],"summary":"List available TTS models","responses":{"200":{"description":"Models list"}}}},"/api/admin/jobs":{"get":{"tags":["Admin"],"security":[{"AdminBearerAuth":[]}],"summary":"List pipeline jobs","parameters":[{"name":"edition_date","in":"query","schema":{"type":"string"}},{"name":"stage","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Pipeline jobs list"}}}},"/api/admin/jobs/{id}/retry":{"post":{"tags":["Admin"],"security":[{"AdminBearerAuth":[]}],"summary":"Manually retry a failed pipeline job","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Job retried"},"404":{"description":"Job not found"}}}}}}