{"openapi":"3.1.0","info":{"title":"Boardcast API","version":"1.0.0","description":"Turn a topic or document into a narrated, hand-drawn whiteboard explainer video. Jobs run with the LLM key stored in the token owner's settings. Webhooks are signed: header `Boardcast-Signature: t=<unix>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" with your webhook secret>`."},"servers":[{"url":"https://video.textocad.com"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Personal API token (bc_...) from Settings → API tokens"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"]},"Options":{"type":"object","properties":{"seconds":{"type":"integer","minimum":15,"maximum":600,"default":75,"description":"Target length (capped by the server limit)"},"audience":{"type":"string","example":"high school students"},"language":{"type":"string","example":"en"},"voice":{"type":"string","example":"af_heart"},"theme":{"type":"string","enum":["whiteboard","blackboard","blueprint","paper"]},"instructions":{"type":"string"}}},"CreateVideo":{"type":"object","properties":{"topic":{"type":"string","example":"Explain how a heat pump works for high school students"},"document_url":{"type":"string","format":"uri","description":"Public URL of a PDF, DOCX, PPTX, MD or TXT (max 20 MB)"},"options":{"$ref":"#/components/schemas/Options"},"mode":{"type":"string","enum":["full","draft"],"default":"full","description":"draft stops after script + narration so it can be edited"},"webhook_url":{"type":"string","format":"uri"}}},"Video":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["queued","planning","voicing","rendering","uploading","done","failed","ready","draft"]},"progress":{"type":"number","minimum":0,"maximum":1},"video_url":{"type":["string","null"],"description":"Signed URL, valid for 1 hour"},"download_url":{"type":["string","null"]},"srt_url":{"type":["string","null"]},"duration_sec":{"type":["number","null"]},"error":{"type":["string","null"]},"usage":{"type":"object","properties":{"input_tokens":{"type":"integer"},"output_tokens":{"type":"integer"},"tts_characters":{"type":"integer"}}},"job":{"type":["object","null"]},"created_at":{"type":"string","format":"date-time"}}}}},"paths":{"/api/v1/videos":{"get":{"summary":"List videos","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Video"}}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a video","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVideo"}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"topic":{"type":"string"},"options":{"type":"string","description":"JSON"},"mode":{"type":"string"},"webhook_url":{"type":"string"}}}}}},"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Video"},{"type":"object","properties":{"job_id":{"type":"string"}}}]}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/videos/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get status, progress and URLs","parameters":[{"name":"include","in":"query","schema":{"type":"string","enum":["script"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Video"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a video and its files","responses":{"200":{"description":"Deleted"},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"put":{"summary":"Save an edited script","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"script":{"type":"object"},"title":{"type":"string"},"theme":{"type":"string"}}}}}},"responses":{"200":{"description":"Saved"},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/{id}/render":{"post":{"summary":"Render the current script to MP4","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"Queued"}}}},"/api/v1/projects/{id}/voice":{"post":{"summary":"Re-record the narration","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"Queued"}}}},"/api/v1/projects/{id}/regenerate-beat":{"post":{"summary":"Regenerate one beat with the LLM","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"beat_index":{"type":"integer"},"instruction":{"type":"string"}},"required":["beat_index"]}}}},"responses":{"202":{"description":"Queued"}}}},"/api/v1/projects/{id}/events":{"get":{"summary":"Progress as Server-Sent Events","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"text/event-stream"}}}},"/api/v1/usage":{"get":{"summary":"Token, voice and render usage","parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":30}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/icons":{"get":{"summary":"Search the icon library","security":[],"parameters":[{"name":"q","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}}}}