API Server

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

Overview

This server is built with FastAPI and provides a comprehensive API for multiple services. API documentation is available in three formats:

• Swagger UI: https://api.codey.lol/docs - Classic interactive API explorer with "Try it out" functionality
• Scalar: https://api.codey.lol/scalar - Modern, fast interactive API documentation (recommended)
• ReDoc: https://api.codey.lol/redoc - Clean, read-only documentation with better visual design

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
• ...