openapi: 3.0.3
info:
  title: Radio Cult API
  description: >-
    Power your online radio station website with the Radio Cult API. Manage
    artists, schedules, media, playlists, recordings, and live streaming
    metadata.
  version: "1.0"
  contact:
    name: Radio Cult
    url: https://www.radiocult.fm/docs/api
servers:
  - url: https://api.radiocult.fm
    description: Radio Cult production API
security:
  - ApiKeyAuth: []
tags:
  - name: Artists
  - name: Schedule
  - name: Media
  - name: Tags
  - name: Playlists
  - name: Recordings
  - name: Streaming
paths:
  /api/station/{stationId}/artists:
    get:
      tags: [Artists]
      summary: Retrieve all artists
      parameters:
        - { name: stationId, in: path, required: true, schema: { type: string } }
      responses:
        "200": { description: List of artists }
    post:
      tags: [Artists]
      summary: Create an artist
      parameters:
        - { name: stationId, in: path, required: true, schema: { type: string } }
      responses:
        "200": { description: Created artist }
  /api/station/{stationId}/artists/{artistId}:
    get:
      tags: [Artists]
      summary: Fetch artist by ID or slug
      parameters:
        - { name: stationId, in: path, required: true, schema: { type: string } }
        - { name: artistId, in: path, required: true, schema: { type: string } }
      responses:
        "200": { description: Artist record }
  /api/station/{stationId}/artists/{artistId}/schedule:
    get:
      tags: [Artists]
      summary: Get an artist's scheduled events
      parameters:
        - { name: stationId, in: path, required: true, schema: { type: string } }
        - { name: artistId, in: path, required: true, schema: { type: string } }
      responses:
        "200": { description: Scheduled events }
  /api/station/{stationId}/schedule:
    get:
      tags: [Schedule]
      summary: Get events in a date range
      parameters:
        - { name: stationId, in: path, required: true, schema: { type: string } }
      responses:
        "200": { description: Scheduled events }
  /api/station/{stationId}/schedule/live:
    get:
      tags: [Schedule]
      summary: Current live broadcast status and metadata
      parameters:
        - { name: stationId, in: path, required: true, schema: { type: string } }
      responses:
        "200": { description: Live broadcast status }
  /api/station/{stationId}/media/track:
    get:
      tags: [Media]
      summary: Retrieve all media tracks
      parameters:
        - { name: stationId, in: path, required: true, schema: { type: string } }
      responses:
        "200": { description: Media tracks }
    post:
      tags: [Media]
      summary: Upload an MP3 track
      parameters:
        - { name: stationId, in: path, required: true, schema: { type: string } }
      responses:
        "200": { description: Uploaded track }
  /api/station/{stationId}/media/track/{trackId}/download-url:
    get:
      tags: [Media]
      summary: Get a signed download URL for a track
      parameters:
        - { name: stationId, in: path, required: true, schema: { type: string } }
        - { name: trackId, in: path, required: true, schema: { type: string } }
      responses:
        "200": { description: Signed download URL }
  /api/station/{stationId}/media/track/{trackId}/tag/{tagId}:
    put:
      tags: [Media]
      summary: Tag a media track
      parameters:
        - { name: stationId, in: path, required: true, schema: { type: string } }
        - { name: trackId, in: path, required: true, schema: { type: string } }
        - { name: tagId, in: path, required: true, schema: { type: string } }
      responses:
        "200": { description: Tagged }
  /api/station/{stationId}/media/track/{trackId}/upload/soundcloud:
    post:
      tags: [Media]
      summary: Upload a track to Soundcloud
      parameters:
        - { name: stationId, in: path, required: true, schema: { type: string } }
        - { name: trackId, in: path, required: true, schema: { type: string } }
      responses:
        "200": { description: Soundcloud upload result }
  /api/station/{stationId}/media/playlist:
    get:
      tags: [Playlists]
      summary: Retrieve all playlists
      parameters:
        - { name: stationId, in: path, required: true, schema: { type: string } }
      responses:
        "200": { description: List of playlists }
  /api/station/{stationId}/media/playlist/{playlistId}/entry:
    post:
      tags: [Playlists]
      summary: Add an entry to a playlist
      parameters:
        - { name: stationId, in: path, required: true, schema: { type: string } }
        - { name: playlistId, in: path, required: true, schema: { type: string } }
      responses:
        "200": { description: Added entry }
  /api/station/{stationId}/media/playlist/{playlistId}/entries:
    delete:
      tags: [Playlists]
      summary: Clear all entries from a playlist
      parameters:
        - { name: stationId, in: path, required: true, schema: { type: string } }
        - { name: playlistId, in: path, required: true, schema: { type: string } }
      responses:
        "200": { description: Cleared }
  /api/station/{stationId}/media/tag:
    get:
      tags: [Tags]
      summary: Retrieve all tags
      parameters:
        - { name: stationId, in: path, required: true, schema: { type: string } }
      responses:
        "200": { description: List of tags }
  /api/station/{stationId}/media/recording:
    get:
      tags: [Recordings]
      summary: Retrieve recordings
      parameters:
        - { name: stationId, in: path, required: true, schema: { type: string } }
      responses:
        "200": { description: List of recordings }
  /api/station/{stationId}/media/recording/{recordingId}/download-url:
    get:
      tags: [Recordings]
      summary: Get a signed download URL for a recording
      parameters:
        - { name: stationId, in: path, required: true, schema: { type: string } }
        - { name: recordingId, in: path, required: true, schema: { type: string } }
      responses:
        "200": { description: Signed download URL }
  /api/station/{stationId}/streaming/history/latest-results:
    get:
      tags: [Streaming]
      summary: Recent track playback history
      parameters:
        - { name: stationId, in: path, required: true, schema: { type: string } }
      responses:
        "200": { description: Recent tracks }
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key