{"openapi":"3.1.0","info":{"title":"Summarize YouTube Videos API","version":"1.0.0","description":"Create structured, timestamped YouTube summaries synchronously or as durable jobs. Cached summaries consume no generation credits."},"servers":[{"url":"https://summarizeyoutubevideos.com"}],"security":[{"bearerAuth":[]}],"paths":{"/api/v1/summaries":{"post":{"operationId":"createSummary","summary":"Create a single-video summary","description":"Returns 200 for a completed synchronous request or 202 when mode=async / Prefer: respond-async is used.","parameters":[{"name":"Idempotency-Key","in":"header","description":"Visible ASCII; retained for 24 hours","schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[\\x21-\\x7E]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSummaryRequest"}}}},"responses":{"200":{"description":"Summary completed","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window"},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix epoch seconds when the current window resets"},"X-Request-Id":{"schema":{"type":"string"},"description":"Stable identifier for support and log correlation"},"Idempotency-Replayed":{"schema":{"type":"boolean"},"description":"True when a POST response was replayed from a key retained for 24 hours"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SummaryResponse"}}}},"202":{"description":"Summary job accepted","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window"},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix epoch seconds when the current window resets"},"X-Request-Id":{"schema":{"type":"string"},"description":"Stable identifier for support and log correlation"},"Idempotency-Replayed":{"schema":{"type":"boolean"},"description":"True when a POST response was replayed from a key retained for 24 hours"},"Location":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/jobs/{id}":{"get":{"operationId":"getSummaryJob","summary":"Get or resume an asynchronous summary job","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^job_"}}],"responses":{"200":{"description":"Current job state","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window"},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix epoch seconds when the current window resets"},"X-Request-Id":{"schema":{"type":"string"},"description":"Stable identifier for support and log correlation"},"Idempotency-Replayed":{"schema":{"type":"boolean"},"description":"True when a POST response was replayed from a key retained for 24 hours"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"401":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/batches":{"post":{"operationId":"createBatch","summary":"Summarize a YouTube playlist or channel","parameters":[{"name":"Idempotency-Key","in":"header","description":"Visible ASCII; retained for 24 hours","schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[\\x21-\\x7E]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBatchRequest"}}}},"responses":{"202":{"description":"Batch accepted","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window"},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix epoch seconds when the current window resets"},"X-Request-Id":{"schema":{"type":"string"},"description":"Stable identifier for support and log correlation"},"Idempotency-Replayed":{"schema":{"type":"boolean"},"description":"True when a POST response was replayed from a key retained for 24 hours"},"Location":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"400":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/batches/{id}":{"get":{"operationId":"getBatch","summary":"Get or resume a playlist/channel batch","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","markdown"],"default":"json"}}],"responses":{"200":{"description":"Current batch state and completed output","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window"},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix epoch seconds when the current window resets"},"X-Request-Id":{"schema":{"type":"string"},"description":"Stable identifier for support and log correlation"},"Idempotency-Replayed":{"schema":{"type":"boolean"},"description":"True when a POST response was replayed from a key retained for 24 hours"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"401":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/logs":{"get":{"operationId":"listApiLogs","summary":"List paginated request activity","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"status","in":"query","schema":{"oneOf":[{"type":"integer"},{"type":"string","enum":["2xx","4xx","5xx"]}]}},{"name":"keyId","in":"query","schema":{"type":"string"}},{"name":"endpoint","in":"query","schema":{"type":"string"}},{"name":"source","in":"query","schema":{"type":"string"}},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Request activity","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window"},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix epoch seconds when the current window resets"},"X-Request-Id":{"schema":{"type":"string"},"description":"Stable identifier for support and log correlation"},"Idempotency-Replayed":{"schema":{"type":"boolean"},"description":"True when a POST response was replayed from a key retained for 24 hours"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogList"}}}},"401":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/usage":{"get":{"operationId":"getApiUsage","summary":"Get 30-day usage, allowance and latency percentiles","responses":{"200":{"description":"Usage overview","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window"},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix epoch seconds when the current window resets"},"X-Request-Id":{"schema":{"type":"string"},"description":"Stable identifier for support and log correlation"},"Idempotency-Replayed":{"schema":{"type":"boolean"},"description":"True when a POST response was replayed from a key retained for 24 hours"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"401":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"syv_live_…"}},"schemas":{"CreateSummaryRequest":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"YouTube URL or 11-character video ID"},"mode":{"type":"string","enum":["sync","async"],"default":"sync"},"format":{"type":"string","enum":["json","markdown","text"],"default":"json"},"language":{"type":"string","maxLength":35,"pattern":"^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$","description":"Optional BCP-47 output language tag"},"includeTranscript":{"type":"boolean","default":false},"webhookUrl":{"type":"string","format":"uri","description":"Public HTTPS URL; async mode only"}}},"CreateBatchRequest":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"YouTube playlist or channel URL/id"},"limit":{"type":"integer","minimum":1,"maximum":50,"default":50}}},"ErrorResponse":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object","additionalProperties":true}}},"requestId":{"type":"string"}}},"Summary":{"type":"object","required":["title","tldr","key_points","summary","chapters"],"properties":{"title":{"type":"string"},"tldr":{"type":"string"},"key_points":{"type":"array","items":{"type":"object","required":["point","timestamp"],"properties":{"point":{"type":"string"},"timestamp":{"type":"string"}}}},"summary":{"type":"string"},"chapters":{"type":"array","items":{"type":"object","required":["timestamp","title","covers"],"properties":{"timestamp":{"type":"string"},"title":{"type":"string"},"covers":{"type":"string"}}}}}},"SummaryResult":{"type":"object","required":["object","id","status","summary","cached","usage"],"properties":{"object":{"const":"summary"},"id":{"type":"string"},"videoId":{"type":"string"},"status":{"const":"succeeded"},"title":{"type":["string","null"]},"channelName":{"type":["string","null"]},"summary":{"$ref":"#/components/schemas/Summary"},"cached":{"type":"boolean"},"output":{"type":"object","properties":{"format":{"type":"string"},"contentType":{"type":"string"},"content":{}}},"transcript":{"type":"object","properties":{"language":{"type":["string","null"]},"segments":{"type":"array","items":{"type":"object"}}}},"usage":{"type":"object"}}},"SummaryResponse":{"allOf":[{"$ref":"#/components/schemas/SummaryResult"},{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string"}}}]},"Job":{"type":"object","required":["object","id","status","requestId"],"properties":{"object":{"const":"job"},"id":{"type":"string"},"status":{"type":"string","enum":["queued","running","succeeded","failed"]},"result":{"anyOf":[{"$ref":"#/components/schemas/SummaryResult"},{"type":"null"}]},"error":{"anyOf":[{"type":"object"},{"type":"null"}]},"requestId":{"type":"string"}}},"Batch":{"type":"object","required":["object","id","status"],"properties":{"object":{"const":"batch"},"id":{"type":"string"},"status":{"type":"string","enum":["running","synthesising","done","failed"]},"kind":{"type":"string","enum":["playlist","channel"]},"title":{"type":["string","null"]},"total":{"type":"integer"},"done":{"type":"integer"},"failed":{"type":"integer"},"videos":{"type":"array","items":{"type":"object"}},"output":{"type":"object"},"requestId":{"type":"string"}}},"ApiActivity":{"type":"object","required":["id","method","endpoint","credits","startedAt"],"properties":{"id":{"type":"string"},"method":{"type":"string"},"endpoint":{"type":"string"},"resource":{"type":["string","null"]},"statusCode":{"type":["integer","null"]},"elapsedMs":{"type":["integer","null"]},"cached":{"type":["boolean","null"]},"provider":{"type":["string","null"]},"credits":{"type":"integer"},"operationStatus":{"type":["string","null"]},"operationErrorCode":{"type":["string","null"]},"startedAt":{"type":"string","format":"date-time"}}},"LogList":{"type":"object","required":["object","data","pagination","requestId"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiActivity"}},"pagination":{"type":"object"},"requestId":{"type":"string"}}},"Usage":{"type":"object","required":["object","period","requests","succeeded","failed","allowance","requestId"],"properties":{"object":{"const":"usage"},"period":{"const":"rolling_30_days"},"requests":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"},"cacheHits":{"type":"integer"},"daily":{"type":"array","items":{"type":"object"}},"latency":{"type":"object"},"allowance":{"type":"object"},"requestId":{"type":"string"}}}}}}