api/README.md

# API Server

A modern FastAPI-based backend providing various endpoints for media, authentication, lighting control, and more.

## Overview

This server is built with [FastAPI](https://fastapi.tiangolo.com/) and provides a comprehensive API for multiple services. The interactive API documentation is available at the [Swagger UI](https://api.codey.lol/docs).

## API Endpoints

### Authentication (`/auth/`) 🔐
- `POST /auth/login` - User authentication with username/password (OAuth2 form data)
- `POST /auth/refresh` - Refresh access tokens using refresh token from cookies
- `GET /auth/id` - Get current user information (requires authentication)

### Lighting Control (`/lighting/`) 💡
- `GET /lighting/state` - Get current lighting state from Redis cache
- `POST /lighting/state` - Set lighting state and control GE Cync smart lights
  - Supports power on/off, brightness (0-100), and RGB color control
  - Directly interfaces with Cync cloud API for real-time device control
  - Requires authentication

### Radio & Streaming (`/radio/`) 📻
**Public Endpoints:**
- `POST /radio/np` - Get currently playing track information (by station: main, rock, rap, electronic, pop)
- `POST /radio/typeahead` - Search typeahead for song/artist suggestions
- `POST /radio/get_queue` - Get current play queue (paged, 20 results per page)
- `GET /radio/album_art` - Get album art for current or specified track

**Authenticated Endpoints:**
- `POST /radio/request` - Submit song requests to radio stations
- `POST /radio/skip` - Skip to next track or specific UUID in queue
- `POST /radio/queue_shift` - Reorder items in the play queue
- `POST /radio/reshuffle` - Reshuffle the entire play queue
- `POST /radio/queue_remove` - Remove specific items from queue
- `POST /radio/ls._next_` - Get next track (for Liquidsoap integration)

**WebSocket Real-time Updates:**
- `WS /radio/ws/{station}` - Real-time radio updates via WebSocket
  - Connects to specific radio station (main, rock, rap, electronic, pop)
  - Immediately sends current track information on connect
  - Sends real-time updates when tracks change
  - Provides LRC (synchronized lyrics) data when available
  - Message types: `track_change`, `lrc`, `ack`
  - No authentication required

### Content & Media
**YouTube (`/yt/`)** 🎥
- `POST /yt/search` - Search for YouTube videos by title

**Transcriptions (`/transcriptions/`)** 📝
- `POST /transcriptions/get_episodes` - Get episode list by show ID
- `POST /transcriptions/get_episode_lines` - Get transcript lines for specific episodes

**Lyric Search (`/lyric/`)** 🎵
- `POST /lyric/search` - Search for song lyrics across multiple sources
  - Supports artist/song search, text search within lyrics
  - Optional LRC format and extra metadata
  - Configurable source exclusions

**Random Messages (`/randmsg`)** 🎲
- `POST /randmsg` - Generate random messages (optional short format)

### System Widgets (`/widget/`) 📊
Homepage dashboard widgets for system monitoring:
- `GET /widget/redis` - Redis server statistics
- `GET /widget/sqlite` - SQLite database statistics  
- `GET /widget/lyrics` - Lyrics database statistics
- `GET /widget/radio` - Current radio playing information
- `GET /widget/rq` - Background job queue statistics

### Utilities (`/misc/`) 🛠️
- `GET /misc/get_activity_image` - Retrieve current activity status image
- `GET /misc/no` - Get a random "no" reason/response
- `POST /misc/upload_activity_image` - Upload new activity image (API key required)

## Features

- **Rate Limiting**: All endpoints protected with configurable rate limits
- **Authentication**: JWT-based authentication with refresh tokens
- **Real-time Device Control**: Direct integration with smart home devices (Cync lights)
- **Redis Caching**: Fast data retrieval with Redis backend
- **Comprehensive Logging**: Detailed logging for debugging and monitoring
- **Interactive Documentation**: Auto-generated Swagger/OpenAPI docs

## Technology Stack

- **FastAPI** - Modern, fast web framework for building APIs
- **Redis** - In-memory data store for caching and session management  
- **JWT** - Secure authentication tokens
- **aiohttp** - Async HTTP client for external API calls
- **Pydantic** - Data validation and serialization
- ...