API reference

Introduction

Are you looking to power your site with the Radio Cult API? If so, you're in the right place.

The Radio Cult API is organised around REST. We expose many of our read-only endpoints so you easily can power your site.

Not a developer?

You can easily integrate Radio Cult functionality into your site using our range of embeds - such as our chat rooms, weekly schedule and player components.

Don't have an account yet?

You need to create a Radio Cult account before you can power your station with our APIs. Go to our sign up page to get started!

Why the Radio Cult API?

If you're already managing your station data through Radio Cult, why take the extra step of using an external Content Management System (CMS) when you can just use Radio Cult as a CMS?

Not only can you manage all your data on the Radio Cult platform - like your artist profiles and schedules - you can also fetch this data to display on your site. Radio Cult is the one-stop shop for your station.

Getting started

To get started using our API you need to create an API key first. The API key allows you to access all our APIs by proving you are who you say you are. Afterall, we only want you to be able to access your station data.

Generating an API key

To generate your station's API key, simply head over to the API key settings page. On this page you will be able to generate a new API key, or delete and roll your key if you already have one.

Your API key should look something like: pk_34c9a89dd5434676972834781b55ad40

Your station ID

You will also be able to find your unique stationId on the API key settings page. You will need to use your stationId to build the correct URLs for our REST API.

Using your API key

Once you have your API key is is simple to use it. Simply include the API key in the x-api-key header on all requests to our API.

fetch('https://api.radiocult.fm/api/station/:stationId/artists', {
  headers: {
    'x-api-key': <your_api_key_here>,
  },
});

API routes

Below you will find an overview of all the API routes you can query to power your site and internal tools, along with an explanation of the objects and entities returned.

Artists

GET  /api/station/:stationId/artists
GET  /api/station/:stationId/artists/:artistId
GET  /api/station/:stationId/artists/:slug
POST /api/station/:stationId/artists

The artist object

The artist object represents an instance of an artist/presenter, just like ones you create via the artist table.

Attributes

{
    id: string;
    name?: string;
    stationId: string; 
    slug?: string;
    socials?: {
      twitterHandle?: string;
      instagramHandle?: string;
      facebook?: string;
      mixcloud?: string;
      soundcloud?: string;
      site?: string;
    };
    shareableLinkId: string;
    description?: JSONContent | undefined;
    logo?:  {
        default: string;
        '1024x1024': string;
        '32x32'?: string;
        '64x64'?: string;
        '128x128'?: string;
        '256x256'?: string;
        '512x512'?: string;
    };
    tags: Array<string>;
    genres: Array<string>;
    modified: string;
    created: string;
}

Get all artists

Call the get all artists endpoint to return all of your artists.

GET /api/station/:stationId/artists

{
    success: true,
    artists: Array<Artist>
} 
  | 
{
    success: false,
    error?: string
}

Get an individual artist by artist ID

Use an artist's ID to fetch their details. Use your station's ID and the ID of the artist you are interested in to build the URL.

GET /api/station/:stationId/artists/:artistId

{
    success: true,
    artist: Artist
} 
  | 
{
    success: false,
    error?: string
}

Get an individual artist by slug

Use an artist's slug to fetch their details. Use your station's ID and the slug of the artist you are interested in to build the URL.

GET /api/station/:stationId/artists/:slug

{
    success: true,
    artist: Artist
} 
  | 
{
    success: false,
    error?: string
}

Create an artist

Create a new artist. Use your station's ID to build the URL.

POST /api/station/:stationId/artists

email is the only required property within the request body and must be a valid email address. If provided, site must be a valid URL. Lastly, if provided, description must either be a string or TipTap JSON format

{
    email: string,
    slug?: string,
    name?: string,
    site?: string,
    twitterHandle?: string,
    instagramHandle?: string,
    facebook?: string,
    mixcloud?: string,
    soundcloud?: string,
    description?: string | JSONContent,
    tags?: string[],
    genres?: string[],
} 

{
    success: true,
    artist: Artist
} 
  | 
{
    success: false,
    error?: string
}

Schedule

The schedule endpoints can be used to work out what is playing on your stream now and what events are scheduled for the future.

GET /api/station/:stationId/schedule?startDate=<iso_timestamp_start_date>&endDate=<iso_timestamp_start_date>&timezone=<your_timezone>
GET /api/station/:stationId/schedule/live

The event object

The event object represents an instance of an scheduled event, just like ones you create on the schedule page to control your stream.

Attributes

{
    id: string;
    stationId: string;
    title: string;
    startDateUtc: string;
    endDateUtc: string;
    description?: JSONContent;
    duration: Minutes;
    timezone: string;
    color?: string;
    artistIds?: string[];
    isRecurring: boolean
    media: 
      | {
        type: 'mix';
        trackId?: string | undefined;
      }
      | {
          type: 'playlist';
          playlistId: string;
        }
      | {
          type: 'live';
        };
}

Get live now

Call the get live now endpoint to return what is currently playing. This endpoint will return the "status" of your stream and the content being played.

The "status" can be one of three things - either:

1. "schedule" - which means a scheduled event is playing
2. "offAir" - which means your stream is off air and nothing is playing, or
3. "defaultPlaylist" - which means there is no scheduled event and your default playlist is playing

GET /api/station/:stationId/schedule/live

{
    success: true;
    result:
      | { status: 'schedule'; content: Event }
      | { status: 'offAir'; content: 'Off Air' }
      | {
          status: 'defaultPlaylist';
          content: {
            name: string;
            numberOfSongs: number;
            duration: Minutes;
          }
    };
}
  | 
{
    success: false,
    error?: string
}

Get events in range

Call the get events in range endpoint to return all events between specified start and end dates. The events will be returned sorted by start time.

startDate, endDate and timezone are required query params. They must be present for the endpoint to return successfully.

GET /api/station/:stationId/schedule?startDate=<iso_timestamp_start_date>&endDate=<iso_timestamp_start_date>&timezone=<your_timezone>

startDate*: ISO_Timestamp (indicating the beginning of the range you want events for)
endDate*: ISO_Timestamp (indicating the end of the range you want events for)
timezone*: Timezone (e.g. europe/london)

{
    schedules: Array<Event>,
    success: true,
}
  | 
{
    success: false,
    error?: string
}