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**:
```json
{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}
```

**Response** (Success):
```json
{
  "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):
```json
{
  "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**:
```json
{
  "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):
```json
{
  "success": true,
  "downloadUrl": "/downloads/1234567890-abc123.mp4",
  "filename": "Video_Title.mp4",
  "videoInfo": {
    "title": "Video Title",
    "duration": 120,
    "thumbnail": "https://...",
    "formats": [...]
  }
}
```

**Response** (Error):
```json
{
  "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

```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

```bash
# 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