{"openapi":"3.0.0","info":{"title":"YouTube Comments Downloader API","description":"API for YouTube Comments Downloader services","version":"1.0.0"},"servers":[{"url":"https://api.youtubecommentsdownloader.com","description":"Production server"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Public API key for authenticating requests. Provide your API key in the `x-api-key` header. API keys can be obtained from the developer dashboard."}}},"security":[{"ApiKeyAuth":[]}],"paths":{"/v1/downloads":{"post":{"operationId":"postV1Downloads","summary":"Create a new download","description":"Creates a new download job for extracting comments from YouTube content. Returns a download object with status \"created\". The download will be processed asynchronously.","tags":["Downloads"],"responses":{"200":{"description":"Download job created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","const":"created"},"contentType":{"type":"string","enum":["video","short","live","playlist","channel","channel-details","community","community-images","custom-list"]},"contentDetails":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"contentId":{"type":"string"}},"required":["url","contentId"]},"itemsType":{"type":"string"},"userId":{"type":"string"},"created":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updated":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","status","contentType","contentDetails","userId","created","updated"]},"examples":{"single-video":{"summary":"Single video download","value":{"id":"abc123","status":"created","contentType":"video","contentDetails":{"url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","contentId":"dQw4w9WgXcQ"},"userId":"user123","created":"2024-01-01T00:00:00Z","updated":"2024-01-01T00:00:00Z"}}}}}},"400":{"description":"Bad request - validation failed","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","const":"VALIDATION_ERROR"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"},"value":{}},"required":["field","message"]}}},"required":["code","message","details"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","const":"UNAUTHORIZED"},"message":{"type":"string"}},"required":["code","message"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","const":"INTERNAL_ERROR"},"message":{"type":"string"}},"required":["code","message"]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contentType":{"type":"string","enum":["video","short","live","playlist","channel","channel-details","community","community-images","custom-list"]},"url":{"type":"string","format":"uri"},"itemsType":{"type":"string"},"parentId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["contentType","url"]}}}}},"get":{"operationId":"getV1Downloads","summary":"List downloads","description":"Get a paginated list of download jobs. Can be filtered by status and content type.","tags":["Downloads"],"responses":{"200":{"description":"Downloads retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["created","downloading","finished","error","canceled"]},"contentType":{"type":"string","enum":["video","short","live","playlist","channel","channel-details","community","community-images","custom-list"]},"contentDetails":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"contentId":{"type":"string"},"title":{"type":"string"}},"required":["url","contentId"]},"itemsType":{"type":"string"},"metadata":{"type":"object","properties":{"commentCount":{"type":"number"},"processedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}}},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"userId":{"type":"string"},"created":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updated":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"finished":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","status","contentType","contentDetails","userId","created","updated"]}},"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["data","page","limit","total"]}}},"headers":{"x-count":{"schema":{"def":{"type":"string"},"type":"string","format":null,"minLength":null,"maxLength":null},"description":"Number of items in current page"},"x-total":{"schema":{"def":{"type":"string"},"type":"string","format":null,"minLength":null,"maxLength":null},"description":"Total number of items"}}}}}},"/v1/downloads/{id}":{"get":{"operationId":"getV1DownloadsById","summary":"Get download status","description":"Get the current status and details of a download job by ID.","tags":["Downloads"],"responses":{"200":{"description":"Download details retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["created","downloading","finished","error","canceled"]},"contentType":{"type":"string","enum":["video","short","live","playlist","channel","channel-details","community","community-images","custom-list"]},"contentDetails":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"contentId":{"type":"string"},"title":{"type":"string"}},"required":["url","contentId"]},"itemsType":{"type":"string"},"metadata":{"type":"object","properties":{"commentCount":{"type":"number"},"processedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}}},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"userId":{"type":"string"},"created":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updated":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"finished":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","status","contentType","contentDetails","userId","created","updated"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","const":"VALIDATION_ERROR"},"message":{"type":"string"}},"required":["code","message"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","const":"UNAUTHORIZED"},"message":{"type":"string"}},"required":["code","message"]}}}},"404":{"description":"Download not found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","const":"NOT_FOUND"},"message":{"type":"string"}},"required":["code","message"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","const":"INTERNAL_ERROR"},"message":{"type":"string"}},"required":["code","message"]}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}]}},"/v1/downloads/{id}/save":{"get":{"operationId":"getV1DownloadsByIdSave","summary":"Save download","description":"Save download in various formats.","tags":["Downloads"],"responses":{"200":{"description":"File downloaded successfully","content":{"application/json":{"schema":{}},"text/csv":{"schema":{"type":"string"}},"text/html":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"}},"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string"}},"application/zip":{"schema":{"type":"string"}}}},"400":{"description":"Bad request - missing parameters or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR"]},"message":{"type":"string"}},"required":["code","message"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"]},"message":{"type":"string"}},"required":["code","message"]}}}},"404":{"description":"Download not found or not ready","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["NOT_FOUND","NOT_READY"]},"message":{"type":"string"}},"required":["code","message"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["INTERNAL_ERROR"]},"message":{"type":"string"}},"required":["code","message"]}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}]}},"/v1/downloads/{id}/restart":{"post":{"operationId":"postV1DownloadsByIdRestart","summary":"Restart download","description":"Manually restart a download job. This will remove any existing job from the queue and start from scratch.","tags":["Downloads"],"responses":{"200":{"description":"Download restarted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Download not found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","const":"NOT_FOUND"},"message":{"type":"string"}},"required":["code","message"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","const":"INTERNAL_ERROR"},"message":{"type":"string"}},"required":["code","message"]}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}]}},"/v1/downloads/{id}/cancel":{"post":{"operationId":"postV1DownloadsByIdCancel","summary":"Cancel download","description":"Cancel a running download. Stops further processing and finalizes the download with current data.","tags":["Downloads"],"responses":{"200":{"description":"Download canceled successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Download not found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","const":"NOT_FOUND"},"message":{"type":"string"}},"required":["code","message"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","const":"INTERNAL_ERROR"},"message":{"type":"string"}},"required":["code","message"]}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}]}},"/v1/user":{"get":{"operationId":"getV1User","tags":["User"],"summary":"Get current user","description":"Returns the currently authenticated user information.","responses":{"200":{"description":"User information","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"verified":{"type":"boolean"},"tier":{"type":"string"},"status":{"type":"string"},"prepaidLimit":{"type":"number"},"prepaidUsage":{"type":"number"},"monthlyUsage":{"type":"number"},"monthlyUsageResetDate":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"customClaims":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"updated":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"created":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","email","verified","tier","status","prepaidLimit","prepaidUsage","monthlyUsage","customClaims","updated","created"]}}}},"401":{"description":"Unauthorized"}}}},"/v1/api-keys":{"post":{"operationId":"postV1ApiKeys","tags":["API Keys"],"summary":"Create API Key","description":"Generates a new API key for the authenticated user.","responses":{"201":{"description":"API Key created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","description":"The generated API key. Shown only once."}},"required":["key"]}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"}},"requestBody":{"content":{"application/json":{"schema":{"vendor":"zod"}}}}},"get":{"operationId":"getV1ApiKeys","tags":["API Keys"],"summary":"List API Keys","description":"Returns all API keys belonging to the authenticated user.","responses":{"200":{"description":"List of API keys","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"expires":{"type":"string"},"created":{"type":"string"},"updated":{"type":"string"}},"required":["id","created","updated"]}}}}},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"}}}},"/v1/api-keys/{id}":{"patch":{"operationId":"patchV1ApiKeysById","tags":["API Keys"],"summary":"Update API Key","description":"Updates the name or expiration of an API key.","requestBody":{"content":{"application/json":{"schema":{"vendor":"zod"}}}},"responses":{"200":{"description":"API Key updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}]},"delete":{"operationId":"deleteV1ApiKeysById","tags":["API Keys"],"summary":"Delete API Key","description":"Revokes an API key by ID.","responses":{"200":{"description":"API Key deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}]}}}}