{"openapi":"3.1.0","info":{"title":"Math Video API","version":"1.3.1","description":"Free mathematics video catalog. Paid analysis and IQS are disabled with a zero operating budget."},"servers":[{"url":"https://math-video.com"}],"paths":{"/api/v1/jobs":{"get":{"operationId":"listJobs","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Job"}}}}}}},"401":{"description":"Invalid or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Generation is disabled in this product."}},"parameters":[],"deprecated":true,"description":"Disabled in the Math Video aggregator profile. Use the catalog endpoints to browse videos and manage collections."},"post":{"operationId":"createJob","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/Job"}}}}}},"202":{"description":"Task queued","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/Job"}}}}}},"401":{"description":"Invalid or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Operation key conflicts with different input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Generation is disabled in this product."}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["text","image","audio"]},"prompt":{"type":"string","minLength":3,"maxLength":8000}},"required":["kind","prompt"]}}}},"deprecated":true,"description":"Disabled in the Math Video aggregator profile. Use the catalog endpoints to browse videos and manage collections."}},"/api/v1/jobs/{id}":{"get":{"operationId":"getJob","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/Job"}}}}}},"401":{"description":"Invalid or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Generation is disabled in this product."}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"deprecated":true,"description":"Disabled in the Math Video aggregator profile. Use the catalog endpoints to browse videos and manage collections."}},"/api/v1/jobs/{id}/result":{"get":{"operationId":"downloadResult","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/octet-stream":{"schema":{"type":"string","contentEncoding":"binary"}}}},"401":{"description":"Invalid or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Generation is disabled in this product."}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"deprecated":true,"description":"Disabled in the Math Video aggregator profile. Use the catalog endpoints to browse videos and manage collections."}},"/api/v1/quota":{"get":{"operationId":"getQuota","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quota"}}}},"401":{"description":"Invalid or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[]}},"/api/template/access":{"get":{"operationId":"getTemplateRelease","summary":"Get available sanitized template release and clone URL.","description":"Template website only; disabled in generated products.","security":[{"websiteSession":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"Sign in required"},"403":{"description":"Verified website session or valid origin required"},"404":{"description":"Template access disabled"},"503":{"description":"Release unavailable"}}},"post":{"operationId":"createTemplateCloneCredential","summary":"Create a one-hour read-only clone credential. Replaces older credentials; shown once. Requires same-origin browser request.","description":"Template website only; disabled in generated products.","security":[{"websiteSession":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"Sign in required"},"403":{"description":"Verified website session or valid origin required"},"404":{"description":"Template access disabled"},"503":{"description":"Release unavailable"}}},"delete":{"operationId":"revokeTemplateCloneCredential","summary":"Revoke current user clone credentials. Requires same-origin browser request.","description":"Template website only; disabled in generated products.","security":[{"websiteSession":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"Sign in required"},"403":{"description":"Verified website session or valid origin required"},"404":{"description":"Template access disabled"},"503":{"description":"Release unavailable"}}}},"/api/catalog/videos":{"get":{"operationId":"catalogVideos","summary":"Search and filter published videos","security":[],"parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"style":"form","explode":true},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1},"style":"form","explode":true},{"name":"platform","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true},{"name":"language","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true},{"name":"discipline","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true},{"name":"topic","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true},{"name":"difficulty","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true},{"name":"style","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true},{"name":"length","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogPage"}}}},"400":{"description":"Invalid input"},"401":{"description":"Authentication required"},"403":{"description":"Wrong scope, owner, origin or administrator permission"},"404":{"description":"Not found"}}}},"/api/catalog/facets":{"get":{"operationId":"catalogFacets","summary":"Available facet values and counts","description":"Topic keys are stable concept identifiers. Each video is counted once per concept, including when its stored tags contain translations. Topic filters also accept legacy English and Chinese aliases.","security":[],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"integer"}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Authentication required"},"403":{"description":"Wrong scope, owner, origin or administrator permission"},"404":{"description":"Not found"}}}},"/api/catalog/videos/{slug}":{"get":{"operationId":"catalogVideo","summary":"Published video and reviewed learning material","security":[],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"query","schema":{"type":"string","enum":["en","zh","original"],"default":"en"},"description":"Language of the reviewed material; source-language fallback when unavailable."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"video":{"$ref":"#/components/schemas/Video"},"material":{"oneOf":[{"type":"object","properties":{"basis":{"type":"string"},"locale":{"type":"string"},"payload":{"$ref":"#/components/schemas/Material"}}},{"type":"null"}]}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Authentication required"},"403":{"description":"Wrong scope, owner, origin or administrator permission"},"404":{"description":"Not found"}}}},"/api/catalog/submissions":{"post":{"operationId":"submitVideo","summary":"Submit a public video link for editorial review","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"video":{"type":"object","properties":{"id":{"type":"string"},"publication_status":{"type":"string"}}}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Authentication required"},"403":{"description":"Wrong scope, owner, origin or administrator permission"},"404":{"description":"Not found"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"title":{"type":"string"},"author":{"type":"string"},"language":{"type":"string"},"discipline":{"type":"string"},"topics":{"type":"array","items":{"type":"string"}},"difficulty":{"type":"string"},"style":{"type":"string"},"description":{"type":"string"}}}}}}}},"/api/catalog/collections":{"get":{"operationId":"listCollections","summary":"List your own private collections","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}}}}},"400":{"description":"Invalid input"},"401":{"description":"Authentication required"},"403":{"description":"Wrong scope, owner, origin or administrator permission"},"404":{"description":"Not found"}}},"post":{"operationId":"createCollection","summary":"Create a private collection","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"400":{"description":"Invalid input"},"401":{"description":"Authentication required"},"403":{"description":"Wrong scope, owner, origin or administrator permission"},"404":{"description":"Not found"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80}},"required":["name"]}}}}}},"/api/catalog/collections/{id}":{"get":{"operationId":"getCollection","summary":"Read, rename or delete your own collection","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Video"}}}}},"400":{"description":"Invalid input"},"401":{"description":"Authentication required"},"403":{"description":"Wrong scope, owner, origin or administrator permission"},"404":{"description":"Not found"}}},"patch":{"operationId":"patchCollection","summary":"Read, rename or delete your own collection","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"boolean"},"deleted":{"type":"boolean"}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Authentication required"},"403":{"description":"Wrong scope, owner, origin or administrator permission"},"404":{"description":"Not found"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}}}}},"delete":{"operationId":"deleteCollection","summary":"Read, rename or delete your own collection","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"boolean"},"deleted":{"type":"boolean"}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Authentication required"},"403":{"description":"Wrong scope, owner, origin or administrator permission"},"404":{"description":"Not found"}}}},"/api/catalog/collections/{id}/videos/{videoId}":{"put":{"operationId":"putBookmark","summary":"Save or remove a published video","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"videoId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"saved":{"type":"boolean"}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Authentication required"},"403":{"description":"Wrong scope, owner, origin or administrator permission"},"404":{"description":"Not found"}}},"delete":{"operationId":"deleteBookmark","summary":"Save or remove a published video","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"videoId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"saved":{"type":"boolean"}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Authentication required"},"403":{"description":"Wrong scope, owner, origin or administrator permission"},"404":{"description":"Not found"}}}},"/api/admin/catalog/queue":{"get":{"operationId":"reviewQueue","summary":"Administrator: pending sources and task history","security":[{"sessionCookie":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"videos":{"type":"array","items":{"$ref":"#/components/schemas/Video"}},"jobs":{"type":"array","items":{"type":"object"}},"analysisEnabled":{"type":"boolean"}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Authentication required"},"403":{"description":"Wrong scope, owner, origin or administrator permission"},"404":{"description":"Not found"}}}},"/api/admin/catalog/videos/{id}":{"patch":{"operationId":"editVideo","summary":"Administrator: edit, publish, reject or remove source","security":[{"sessionCookie":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"boolean"}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Authentication required"},"403":{"description":"Wrong scope, owner, origin or administrator permission"},"404":{"description":"Not found"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"title_zh":{"type":"string"},"description":{"type":"string"},"description_zh":{"type":"string"},"discipline":{"type":"string"},"topics":{"type":"array","items":{"type":"string"}},"difficulty":{"type":"string"},"publication_status":{"type":"string","enum":["pending","published","rejected","removed"]},"author":{"type":"string","maxLength":120},"language":{"type":"string"},"style":{"type":"string","enum":["visual","lecture","whiteboard","problem","proof","popular"]},"duration_seconds":{"type":["integer","null"],"minimum":1,"maximum":7200},"cover_url":{"type":"string"}}}}}}}},"/api/admin/catalog/videos/{id}/analyze":{"post":{"operationId":"analyzeVideo","summary":"Administrator: reserve budget and dispatch analysis once","security":[{"sessionCookie":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"type":"object"},"reused":{"type":"boolean"}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Authentication required"},"403":{"description":"Wrong scope, owner, origin or administrator permission"},"404":{"description":"Not found"},"503":{"description":"Analysis disabled; no paid request sent"}}}},"/api/admin/catalog/materials/{id}":{"patch":{"operationId":"reviewMaterial","summary":"Administrator: review, edit and publish learning material","security":[{"sessionCookie":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"boolean"}}}}}},"400":{"description":"Invalid input"},"401":{"description":"Authentication required"},"403":{"description":"Wrong scope, owner, origin or administrator permission"},"404":{"description":"Not found"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["published","rejected"]},"payload":{"$ref":"#/components/schemas/Material"}}}}}}}},"/api/admin/catalog/jobs/{id}/recover":{"post":{"operationId":"recoverCatalogJob","summary":"Recover only a queued or failed task with no attempted provider request; never repeat an unknown outcome","security":[{"sessionCookie":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Recovery status"},"403":{"description":"Fresh administrator session and two-factor verification required"},"409":{"description":"Provider outcome needs reconciliation or admission capacity exceeded"},"503":{"description":"Analysis disabled"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"},"websiteSession":{"type":"apiKey","in":"cookie","name":"__Secure-cioy.session_token","description":"Verified template-website session; local development uses cioy.session_token. Product Bearer keys cannot claim template access."},"sessionCookie":{"type":"apiKey","in":"cookie","name":"math-video.session_token","description":"Verified allowlisted email, 2FA and session created within 15 minutes. API keys are denied."}},"schemas":{"Job":{"type":"object","required":["id","kind","status"],"properties":{"id":{"type":"string"},"kind":{"type":"string"},"status":{"type":"string","enum":["queued","running","succeeded","failed","unknown","canceled"]},"text":{"type":["string","null"]},"resultUrl":{"type":["string","null"]},"error":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}}},"Quota":{"type":"object","properties":{"available":{"type":"integer","minimum":0},"held":{"type":"integer","minimum":0},"consumed":{"type":"integer","minimum":0}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}}}}},"Video":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"platform":{"type":"string","enum":["youtube","bilibili","tiktok","x","xiaohongshu"]},"source_url":{"type":"string","format":"uri"},"title":{"type":"string"},"title_zh":{"type":"string"},"author":{"type":"string"},"description":{"type":"string"},"description_zh":{"type":"string"},"cover_url":{"type":"string"},"language":{"type":"string"},"discipline":{"type":"string"},"topics":{"type":"array","items":{"type":"string"}},"difficulty":{"type":"string"},"style":{"type":"string"},"duration_seconds":{"type":["integer","null"]},"analysis_status":{"type":"string"},"publication_status":{"type":"string"},"embed_status":{"type":"string"}}},"CatalogPage":{"type":"object","properties":{"videos":{"type":"array","items":{"$ref":"#/components/schemas/Video"}},"total":{"type":"integer"},"page":{"type":"integer"}}},"Collection":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"video_count":{"type":"integer"}}},"Material":{"type":"object","properties":{"summary":{"type":"string"},"chapters":{"type":"array","items":{"type":"object","properties":{"seconds":{"type":"number"},"title":{"type":"string"}}}},"transcript":{"type":"array","items":{"type":"object","properties":{"seconds":{"type":"number"},"text":{"type":"string"}}}},"cards":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"explanation":{"type":"string"},"formula":{"type":"string"},"seconds":{"type":"number"}}}},"prerequisites":{"type":"array","items":{"type":"string"}},"script":{"type":"array","description":"Original educational narration grounded in video analysis; separate from verbatim speech. Present in reviewed inventory materials.","items":{"type":"object","required":["seconds","text"],"properties":{"seconds":{"type":"number","minimum":0,"maximum":7200},"text":{"type":"string"}}}}}}}}}