API Documentation - CloudStreaming Stations

Autenticación

API Key Authentication

Todas las solicitudes a la API requieren autenticación mediante API Key. Puedes generar tu API Key desde el Dashboard > Mi Perfil > API.

# Incluir en el header de todas las solicitudes
Authorization: Bearer YOUR_API_KEY
# O como parámetro en la URL
?api_key=YOUR_API_KEY
            

POST /api/v1/auth/login

Autentica un usuario y devuelve un token de acceso.

Parámetros:

Parámetro	Tipo	Requerido	Descripción
`email`	string	Sí	Email del usuario
`password`	string	Sí	Contraseña del usuario

Respuesta Exitosa (200):

{
  "success": true,
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "expires_in": 7200,
    "user": {
      "id": 1,
      "username": "rca",
      "email": "radiocastelar@gmail.com",
      "role": "broadcaster"
    }
  }
}
                    

Emisoras

GET /api/v1/stations

Obtiene una lista de todas las emisoras activas.

Parámetros de Query:

Parámetro	Tipo	Requerido	Descripción
`limit`	int	No	Límite de resultados (default: 20, max: 100)
`offset`	int	No	Offset para paginación (default: 0)
`search`	string	No	Búsqueda por nombre de emisora

Respuesta Exitosa (200):

{
  "success": true,
  "data": [
    {
      "id": 11,
      "name": "Radio Castelar Argentina",
      "slug": "radio-castelar-argentina",
      "description": "",
      "logo_url": "/uploads/rca/logos/logo_1772685970_8782f67d688848c9.jpg",
      "stream_url": "https://radiocastelar.com.ar/hls/stream.m3u8",
      "protocol": "icecast",
      "bitrate": 128,
      "is_active": 1,
      "listeners_count": 11,
      "created_at": "2026-03-05 04:46:10"
    }
  ],
  "pagination": {
    "total": 2,
    "limit": 20,
    "offset": 0
  }
}
                    

GET /api/v1/stations/{id}

Obtiene los detalles de una emisora específica.

Parámetros de Path:

Parámetro	Tipo	Requerido	Descripción
`id`	int	Sí	ID de la emisora

POST /api/v1/stations

Crea una nueva emisora. Requiere autenticación.

Parámetros del Body:

Parámetro	Tipo	Requerido	Descripción
`name`	string	Sí	Nombre de la emisora (min: 3 caracteres)
`description`	string	No	Descripción de la emisora
`stream_url`	string	No	URL completa del stream
`server_host`	string	No	Host del servidor (sin http://)
`server_port`	int	No	Puerto del servidor (1-65535)
`mount_point`	string	No	Mount point (ej: /stream)
`protocol`	string	No	Protocolo: icecast, shoutcast, custom (default: icecast)
`bitrate`	int	No	Bitrate: 64, 128, 192, 256, 320 (default: 128)

PUT /api/v1/stations/{id}

Actualiza una emisora existente. Requiere autenticación y ser propietario.

DELETE /api/v1/stations/{id}

Elimina una emisora. Requiere autenticación y ser propietario.

Archivos de Audio

GET /api/v1/audio

Obtiene una lista de archivos de audio del usuario autenticado.

POST /api/v1/audio/upload

Sube un nuevo archivo de audio. Requiere autenticación.

Parámetros (multipart/form-data):

Parámetro	Tipo	Requerido	Descripción
`file`	file	Sí	Archivo de audio (mp3, aac, ogg, wav, flac, opus)
`station_id`	int	No	ID de la emisora asociada

Respuesta Exitosa (200):

{
  "success": true,
  "data": {
    "id": 65,
    "filename": "audio_1772721997_e0b7486eba90159b.mp3",
    "filepath": "/uploads/rca/audio_1772721997_e0b7486eba90159b.mp3",
    "original_name": "Culture Beat - Mr. Vain.mp3",
    "mime_type": "audio/mpeg",
    "file_size": 9767040,
    "duration": 244,
    "is_processed": 1
  }
}
                    

Playlists

GET /api/v1/playlists

Obtiene playlists del usuario autenticado.

Parámetros de Query:

Parámetro	Tipo	Requerido	Descripción
`station_id`	int	No	Filtrar por emisora
`is_auto_dj`	boolean	No	Filtrar playlists Auto DJ

POST /api/v1/playlists/{id}/tracks

Agrega un track a una playlist. Requiere autenticación.

Parámetros del Body:

Parámetro	Tipo	Requerido	Descripción
`audio_file_id`	int	Sí	ID del archivo de audio
`order_position`	int	No	Posición en la playlist (default: automático)

Mensajes

POST /api/v1/messages

Envía un mensaje de contacto. No requiere autenticación.

Parámetros del Body:

Parámetro	Tipo	Requerido	Descripción
`name`	string	Sí	Nombre del remitente (min: 2 caracteres)
`email`	string	Sí	Email válido del remitente
`subject`	string	Sí	Asunto del mensaje (min: 5 caracteres)
`message`	string	Sí	Contenido del mensaje (min: 10 caracteres)

Estadísticas

GET /api/v1/stats/station/{id}

Obtiene estadísticas de una emisora específica.

Parámetros de Query:

Parámetro	Tipo	Requerido	Descripción
`period`	string	No	Período: day, week, month, year (default: week)

Códigos de Error

Código	Significado	Descripción
`200`	OK	Solicitud exitosa
`201`	Created	Recurso creado exitosamente
`400`	Bad Request	Parámetros inválidos o faltantes
`401`	Unauthorized	Token inválido o faltante
`403`	Forbidden	No tiene permisos para esta acción
`404`	Not Found	Recurso no encontrado
`429`	Too Many Requests	Límite de rate limit excedido
`500`	Internal Server Error	Error interno del servidor

Ejemplo de Respuesta de Error:

{
  "success": false,
  "error": {
    "code": 400,
    "message": "Parámetros inválidos",
    "details": [
      {
        "field": "email",
        "message": "El email no es válido"
      }
    ]
  }
}
                    

Rate Limits

La API tiene límites de solicitudes para prevenir abuso:

Autenticados: 1000 solicitudes/hora
No autenticados: 100 solicitudes/hora
Upload de archivos: 50 archivos/hora
Envío de mensajes: 5 mensajes/hora