API Documentation
Integrate BlackHole video downloads into your applications.
Authentication
All API requests require authentication using an API key. Include your API key in theAuthorization header:
Authorization: Bearer YOUR_API_KEYAPI keys are available for existing Business tier subscribers. Manage your API keys →
Base URL
https://blhole.comEndpoints
POST
/api/v1/downloadDownload a video from a supported platform
Parameters:
url: string (required) - The video URL to downloadquality: string (optional) - '1080' | '720' | '480' | '360' | 'max'format: string (optional) - 'video' | 'audio'audioFormat: string (optional) - 'mp3' | 'best'
Example:
curl -X POST https://blhole.com/api/v1/download \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://youtube.com/watch?v=dQw4w9WgXcQ", "quality": "1080"}'Response:
{
"success": true,
"data": {
"url": "https://cdn.blhole.com/download/abc123.mp4",
"filename": "video.mp4",
"fileSize": 15728640,
"duration": 212
}
}GET
/api/v1/infoGet video information without downloading
Parameters:
url: string (required) - The video URL to analyze
Example:
curl -X GET "https://blhole.com/api/v1/info?url=https://youtube.com/watch?v=dQw4w9WgXcQ" \ -H "Authorization: Bearer YOUR_API_KEY"
Response:
{
"success": true,
"data": {
"title": "Video Title",
"duration": 212,
"thumbnail": "https://...",
"platform": "youtube",
"availableQualities": ["1080", "720", "480", "360"]
}
}GET
/api/v1/usageCheck your current API usage and limits
Example:
curl -X GET https://blhole.com/api/v1/usage \ -H "Authorization: Bearer YOUR_API_KEY"
Response:
{
"success": true,
"data": {
"tier": "business",
"requestsToday": 42,
"requestsLimit": 500,
"requestsRemaining": 458,
"resetsAt": "2026-01-29T00:00:00Z"
}
}Rate Limits
API requests are limited based on your subscription tier:
| Tier | Requests/Day | Max Quality |
|---|---|---|
| Business | 500 | 4K |
Rate limits reset at midnight UTC each day.
Error Codes
| Code | Status | Description |
|---|---|---|
UNAUTHORIZED | 401 | Invalid or missing API key |
FORBIDDEN | 403 | API access not allowed for your tier |
LIMIT_EXCEEDED | 429 | Daily request limit exceeded |
INVALID_URL | 400 | The provided URL is not supported |
DOWNLOAD_ERROR | 400 | Failed to process the video |
SERVER_ERROR | 500 | Internal server error |
Support
Need help with the API? Join our Discord community and ask in #api-discussion.