{"openapi":"3.1.0","info":{"title":"Scority API","version":"1.0.0","description":"YouTube Transcript API for AI apps and automation."},"servers":[{"url":"https://api.scority.ai","description":"Production API"}],"tags":[{"name":"Health","description":"Public liveness checks."},{"name":"Transcripts","description":"Protected YouTube transcript endpoints."}],"paths":{"/health":{"get":{"tags":["Health"],"operationId":"getHealth","summary":"Get API liveness status","description":"Returns safe service health fields. This endpoint does not require an API key.","responses":{"200":{"description":"API service is running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/v1/youtube/transcript":{"get":{"tags":["Transcripts"],"operationId":"getYoutubeTranscript","summary":"Fetch a YouTube transcript","description":"Returns transcript text and timed segments for many public YouTube videos that have accessible captions.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"video_id","in":"query","required":false,"description":"YouTube video ID. Provide either video_id or video_url, not both.","schema":{"type":"string","pattern":"^[a-zA-Z0-9_-]{11}$","examples":["dQw4w9WgXcQ"]}},{"name":"video_url","in":"query","required":false,"description":"Full YouTube video URL. Provide either video_id or video_url, not both.","schema":{"type":"string","format":"uri","examples":["https://www.youtube.com/watch?v=dQw4w9WgXcQ"]}},{"name":"language","in":"query","required":false,"description":"Preferred caption language code, such as en, en-US, ru, or ru-RU.","schema":{"type":"string","pattern":"^[a-z]{2,3}(?:-[a-zA-Z]{2,8})?$","examples":["en"]}},{"name":"lang","in":"query","required":false,"description":"Alias for language. Do not send both language and lang.","schema":{"type":"string","pattern":"^[a-z]{2,3}(?:-[a-zA-Z]{2,8})?$","examples":["en"]}}],"responses":{"200":{"description":"Transcript response.","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current short-window rate limit.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current short-window rate limit.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix timestamp when the current short-window rate limit resets.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptResponse"}}}},"400":{"description":"Invalid or ambiguous request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Transcript captions are not available for this video.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit or monthly quota exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying after rate_limited responses.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current short-window rate limit.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current short-window rate limit.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix timestamp when the current short-window rate limit resets.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected transcript processing failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"YouTube upstream transcript fetch failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Rate limit provider is unavailable when fail-closed mode is enabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Scority API key. Keep it server-side."}},"schemas":{"HealthResponse":{"type":"object","required":["environment","nodeVersion","rateLimitProvider","service","status","timestamp","uptime","version","whisperFallbackEnabled"],"properties":{"environment":{"type":"string"},"nodeVersion":{"type":"string"},"rateLimitProvider":{"type":"string","enum":["memory","redis"]},"service":{"type":"string","const":"api"},"status":{"type":"string","const":"ok"},"timestamp":{"type":"string","format":"date-time"},"uptime":{"type":"number"},"version":{"type":["string","null"]},"whisperFallbackEnabled":{"type":"boolean"}},"additionalProperties":false},"TranscriptSegment":{"type":"object","required":["text","start","duration"],"properties":{"text":{"type":"string"},"start":{"type":"number","description":"Segment start time in seconds."},"duration":{"type":"number","description":"Segment duration in seconds."}},"additionalProperties":false},"TranscriptResponse":{"type":"object","required":["language","source","text","segments"],"properties":{"language":{"type":"string","description":"Selected caption language."},"source":{"type":"string","enum":["captions","whisper"]},"text":{"type":"string"},"segments":{"type":"array","items":{"$ref":"#/components/schemas/TranscriptSegment"}}},"additionalProperties":false},"ErrorCode":{"type":"string","enum":["UNAUTHORIZED","ambiguous_language","ambiguous_request","invalid_language","invalid_video_id","invalid_video_url","quota_exceeded","rate_limit_unavailable","rate_limited","transcript_fetch_failed","transcript_not_available","upstream_transcript_failed"]},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}}}