downlink/docs/api.md

API Documentation

Overview

The Downlink API provides endpoints for fetching YouTube video information and downloading videos/audio in various formats.

Base URL

• Development: http://localhost:3000
• Production: https://your-domain.com

Endpoints

Get Video Information

Retrieve metadata about a YouTube video without downloading it.

Endpoint: POST /api/info

Request Body:

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}

Response (Success):

{
  "success": true,
  "videoInfo": {
    "title": "Video Title",
    "duration": 120,
    "thumbnail": "https://i.ytimg.com/vi/.../maxresdefault.jpg",
    "formats": [
      {
        "formatId": "137",
        "ext": "mp4",
        "resolution": "1920x1080",
        "filesize": 50000000,
        "formatNote": "1080p"
      }
    ]
  }
}

Response (Error):

{
  "success": false,
  "error": "Invalid YouTube URL"
}

Status Codes:

• 200: Success
• 400: Bad Request (invalid URL or missing fields)
• 500: Internal Server Error

---

Download Video/Audio

Download a YouTube video or extract audio in the specified format.

Endpoint: POST /api/download

Request Body:

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "format": "mp4",
  "formatType": "video"
}

Format Types:

• "video": Download as video file
• "audio": Extract audio only

Video Formats:

• "mp4": MP4 video (most compatible)
• "webm": WebM video (web-optimized)
• "mkv": MKV container (high quality)
• "avi": AVI video (legacy)

Audio Formats:

• "mp3": MP3 audio (most compatible)
• "wav": WAV audio (uncompressed)
• "m4a": M4A audio (Apple format)
• "opus": Opus audio (modern, efficient)

Response (Success):

{
  "success": true,
  "downloadUrl": "/downloads/1234567890-abc123.mp4",
  "filename": "Video_Title.mp4",
  "videoInfo": {
    "title": "Video Title",
    "duration": 120,
    "thumbnail": "https://...",
    "formats": [...]
  }
}

Response (Error):

{
  "success": false,
  "error": "Failed to download video"
}

Status Codes:

• 200: Success
• 400: Bad Request (invalid URL, format, or missing fields)
• 500: Internal Server Error

Error Handling

All endpoints return JSON responses with a success boolean field. When success is false, an error field contains the error message.

Common error messages:

• "Missing required fields": Required request body fields are missing
• "Invalid YouTube URL": The provided URL is not a valid YouTube URL
• "Failed to get video info": Error occurred while fetching video metadata
• "Failed to download video": Error occurred during download/transcoding

Rate Limiting

Currently, no rate limiting is implemented. Consider adding rate limiting for production use.

File Storage

Downloaded files are stored in /public/downloads/ and are accessible via the downloadUrl returned in the response. Files are named with a timestamp and random ID to avoid conflicts.

Note: Files are not automatically cleaned up. Consider implementing a cleanup job for production.

Examples

JavaScript/TypeScript

// Get video info
const infoResponse = await fetch('/api/info', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'
  })
});
const infoData = await infoResponse.json();

// Download MP4 video
const downloadResponse = await fetch('/api/download', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
    format: 'mp4',
    formatType: 'video'
  })
});
const downloadData = await downloadResponse.json();

if (downloadData.success) {
  // Download the file
  window.location.href = downloadData.downloadUrl;
}

cURL

# Get video info
curl -X POST http://localhost:3000/api/info \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"}'

# Download MP3 audio
curl -X POST http://localhost:3000/api/download \
  -H "Content-Type: application/json" \
  -d '{
    "url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "format":"mp3",
    "formatType":"audio"
  }'

Security Considerations

• URLs are validated to ensure they are YouTube URLs
• Filenames are sanitized to prevent directory traversal
• No user authentication is currently implemented
• Consider adding file size limits and download quotas
• Implement CORS policies if needed for cross-origin requests