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.

An example of using your API key
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

Endpoints
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

The artist object
{
    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;
}

idstring

The unique ID of the artist

namestring

The name of the artist. As you can create an artist with only an email, it is possible for this value to not be set

stationIdstring

The unique ID of the station that the artist belongs to

slugstring

An alternative and human-readable ID of the artist

socialsmap

Map containing socials related to the artist - e.g. twitter handle, website. This can be undefined, as can the properties within

shareableLinkIdstring

The shareable Link that gives 3rd parties editable access to the artist. This may be useful if you are building an internal tool for your station. You most likely will not want to render this on any public facing site.

descriptionJSONContent | undefined

The artists description represented in TipTap JSON format

logomap

The artwork for the artist. If no artwork has been uploaded then this may be undefined. Once artwork has been uploaded it is automatically resized. The resizing happens asynchronously. As such, there is a possibility that any of the resize values may be undefined for a few seconds after the image has been uploaded. The time window is so small that you will be very unlikely to ever run into this.

tagsArray<string>

A string array containing the tags assigned to the artist

genresArray<string>

A string array containing the genres of the artist

modifiedstring [UTC timestamp]

A UTC timestamp of when the artist was last modified/updated

createdstring [UTC timestamp]

A UTC timestamp of when the artist was created

Get all artists

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

Endpoint
GET /api/station/:stationId/artists
Response
{
    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.

Endpoint
GET /api/station/:stationId/artists/:artistId
Response
{
    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.

Endpoint
GET /api/station/:stationId/artists/:slug
Response
{
    success: true,
    artist: Artist
} 
  | 
{
    success: false,
    error?: string
}

Create an artist

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

Endpoint
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

Body
{
    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[],
} 
Response
{
    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.

Endpoints
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

The event object
{
    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;
      }
      | {
          type: 'playlist';
          playlistId: string;
        }
      | {
          type: 'live';
        };
}

idstring

The unique ID of the event

stationIdstring

The unique ID of the station that the event belongs to

titlestring

The title of the event

startDateUtcstring [UTC timestamp]

The start date of the event formatted as a ISO timestamp

endDateUtcstring [UTC timestamp]

The end date of the event formatted as a ISO timestamp

descriptionJSONContent | undefined

The event description represented in TipTap JSON format

durationMinutes (number)

The duration of the event expressed as minutes

timezonestring

The original timezone the event was created in

colorstring | undefined

The color of the event as a hex code

mediastring

The media attached to an event. Media can either be live, a mix or a playlist.

artistIdsArray<string> | undefined

An optional array of the IDs of artists attached to an event

isRecurringboolean

A boolean value indicating whether the event is standalone (i.e. doesn't repeat) or is repeating (i.e. is part of a series of events)

modifiedstring [UTC timestamp]

A UTC timestamp of when the event was last modified/updated.

createdstring [UTC timestamp]

A UTC timestamp of when the event was created.

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
Endpoint
GET /api/station/:stationId/schedule/live
Response
{
    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.

Endpoint
GET /api/station/:stationId/schedule?startDate=<iso_timestamp_start_date>&endDate=<iso_timestamp_start_date>&timezone=<your_timezone>
Query params (* required)
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)
Response
{
    schedules: Array<Event>,
    success: true,
}
  | 
{
    success: false,
    error?: string
}