Radio Cult Online Radio API Reference

Looking to integrate a powerful radio API for developers into your online radio station? The Radio Cult API provides comprehensive endpoints and workflows for building custom radio applications, automating broadcasting tasks, and creating seamless listener experiences.

Our radio API for developers follows REST architecture principles, exposing both read and write endpoints that enable you to power websites, automate workflows, and build custom integrations. Whether you're developing a new website, mobile app or automated scheduling workflows our API provides the flexibility developers need.

All endpoints return clean JSON-encoded responses with standard HTTP response codes, making integration straightforward for any development stack. Our API workflows support everything from simple player embeds to complex automation systems.

Authentication uses secure API keys that prove access permissions. Follow standard security protocols with your API key, which can be regenerated anytime to maintain security integrity.

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!

Generating an API key

To generate an API key for your station, simply head over to the API key settings page. On this page you will be able to generate new secret and publishable API keys. You can delete or roll API keys at any point.

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.

Public key

Publishable keys are used to access read-only endpoints that return data safe for public display. This means there is limited access if your key gets leaked.

In short, this means you're safe to use your publishable keys on your website.

If you wish to block access in the future then simply delete or roll your publishable key.

A publishable API key should look something like: pk_34c9a89dd5434676972834781b55ad40

Secret key

Secret keys allow access to all API endpoints, including automation endpoints that modify your station's data. For example, uploading media, creating artists and more.

Due to the expanded access of secret keys, you should take precautions to prevent your secret key from being leaked (hence, the wonderfully apt name of a "secret" key).

You will most likely be using your secret key in your backend or as part of a CLI workflow. You should not use your secret key on your website.

If you wish to access read-only data, then you should use a publishable key, which can be safely stored and used in your frontend code.

A secret API key should look something like: sk_34c9a89dd5434676972834781b55ad40s78ahddha6884

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.

The x-api-key header value can be a publishable or a secret key. Use the correct API key for the endpoint in question.

In general, use a publishable API key for all GET requests. Use a secret key for any PUT, POST or DELETE requests.

The URL to use for all API endpoints is https://api.radiocult.fm. Make sure to direct requests there rather than the normal Radio Cult URL.

The Radio Cult API uses conventional HTTP response codes to indicate the success or failure of each request.

In general: response status codes in the 2xx range indicate success. 4xx response codes indicate an error due to invalid information provided to the endpoint (e.g., missing or incorrect parameters). 5xx response codes indicate an error with our servers, and not your request (these are rare, if this does happen then we will have been alerted and on the case but feel free to reach out as well).

We try to be consistent with return values. In the case of an error, every reponse body should be an object containing at least the property success which will be set to false.

To ensure fair usage, we enforce rate limits on key automation endpoints. Limits are applied per station.

There are two layers of protection:

• Burst limit — prevents a large number of requests being made within a short period (per minute)
• Daily limit — caps the total number of requests per day

Every response includes headers so you can track your current usage and build smarter retry logic.

Handling a 429 response

When a rate limit is exceeded the API returns a 429 Too Many Requests response. The Retry-After header tells you how many seconds to wait before retrying. The response body includes additional detail about which limit was hit.

We recommend implementing exponential backoff in your integration. Monitor the X-RateLimit-Remaining-* headers to slow down proactively before hitting a limit.

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

You'll generally query the live now endpoint to build custom players and display what is currently being played on your stream. You'll want to use the range endpoint for building Schedule pages, displaying upcoming events for the week.

These endpoints will return Events. The Event object represents an instance of an scheduled event.

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.

The content of the stream can be an Event (in the case of a scheduled show), an Off Air enum to indicate the stream is off air or the details associated with your default playlist.

The endpoint also returns:

• the Metadata of the track details currently being played on the stream. See below for more details on the shape of the Metadata object.
• the LiveMusicRecognition of the track currently detected to be playing on the stream. This object will only be defined if your Radio Cult account has the 24/7 Music Recognition add-on. See below for more details on the shape of the LiveMusicRecognition object.

For live updates on your station's metadata, we recommend using WebSockets.

With WebSockets, we send updates immediately when the metadata changes, ensuring the most up-to-date data. Using Websockets puts less load on our servers and results in a better experience for your listeners.

Unlike polling the "live now" endpoint every minute, which may result in a few seconds of delay, WebSockets provide instant updates. This is why all of our player embeds are powered by WebSockets.

Our WebSockets use Socket.IO, so you'll need the client version of Socket.IO to connect.

To authenticate, include your API key in the auth section when establishing the connection.

All metadata updates will be delivered under the player-metadata event.

We've included example code showing you how to connect and start consuming Websocket events.

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 and endDate are required query params. They must be present for the endpoint to return successfully.

You may optionally pass an expand query param to expand the response. Multiple values can be passed as a comma-separated string (i.e. expand=artist,tags). Use expand=artist to hydrate the artistIds field with the full artist object for each event. Use expand=tags to hydrate the tagIds field with the full tag object for each event.

The Artist object represents an instance of an artist (or presenter, or host, or whatever language you choose) in Radio Cult. An Artist is someone who presents shows on your station.

An Artist encapsulates the common information for a host or presenter - such as name, description, social media links and more.

As Artists can be assigned to shows, you can fetch all shows an Artist is on via their ID. Additionally, Events will have the ID for any Artist on that show.

Use an artist's ID to fetch their details.

Use your station ID and the ID of the artist you are interested in to build the URL.

Use an artist's slug to fetch their details.

Use your station ID and the slug of the artist you are interested in to build the URL.

Use an Artist's ID to fetch all events between the specified start and end dates the artist has been assigned to. The events will be returned sorted by start time.

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

Create a new artist.

Use your station's ID to build the URL.

You must provide either email or name in the request body to create an artist. If an email is provided, then it 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

Call this endpoint to update an existing artist. Use the artist's ID to form the URL.

All fields are optional. Only the fields you provide are updated; omitted fields are left unchanged. socials is merged onto the artist's existing handles, so you only need to send the ones you want to change. To clear a value, send tags: [] or genres: [], or a social handle as an empty string.

If provided, email must be a valid email address, site must be a valid URL, and description must be TipTap JSON format.

Call this endpoint to delete an artist. Use the artist's ID to form the URL.

If the artist is linked to a user, that user account is not deleted. Only the link between them is removed.

The last played endpoint can be used to retrieve the latest played tracks for your station.

Call this endpoint to retrieve the latest played tracks for your station. The returned array will be sorted by playoutStart in descending order.

You may optionally pass a limit query param (expressed as an integer) to specify the number of latest played tracks to return. The minimum value is 1 and the maximum value is 100.

If not provided, the 5 last played tracks will be returned.

The track endpoints can be used to interact with your track library.

You can upload files, tag them, add them to playlists, and more.

These endpoints need to be authenticated using your Secret Key.

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

Use your Secret Key when accessing this endpoint.

Call the get track download URL endpoint to retrieve a signed URL that can be used to download the track.

The signed URL will expire after 30 minutes.

Use your Secret Key when accessing this endpoint.

Call this endpoint to update the metadata of an existing track. Use the track's ID to form the URL.

All body fields are optional - only the fields you provide will be updated.

If both cueIn and cueOut are provided, cueIn must be less than cueOut. If all of cueIn, cueOut, fadeIn and fadeOut are provided, then fadeIn + fadeOut must not exceed the playable duration (cueOut - cueIn).

Use your Secret Key when accessing this endpoint.

Call this endpoint to delete a track from your track library. Use the track's ID to form the URL.

By default, if the track is still used by at least one playlist the request returns a 409 and the track is not deleted. Pass the optional force query param set to true to delete the track regardless of any playlist references.

Use your Secret Key when accessing this endpoint.

Call the upload endpoint to upload a file to your track library.

This endpoint is useful for building workflows and automating uploads when you have many Artists and shows.

The request takes a form data body, where stationMedia is the file you wish to upload.

The file must be mp3 or m4a. The file must be less than 750MB. The file must have a valid duration.

We use the metadata (or file name if metadata is not set) to set the track information.

OPTIONALLY: you can provide metadata overrides in the form data. This will override the metadata we extract from the file.

The notes field allows you to add custom notes, descriptions or comments to your tracks (max 4000 characters). These notes can be used for internal organization and will automatically populate as the default description when uploading to platforms like Mixcloud or Soundcloud from within Radio Cult.

NOTE: To ensure we can properly validate the metadata overrides, you must attach it to your form data as valid JSON. You need to JSON.stringify the metadata overrides before adding them to the form data.

OPTIONALLY: you can provide playlistIds and/or tagIds in the form data. This will assign the uploaded track to the provided playlist(s) and/or tag(s).

NOTE: If the provided playlist(s) and/or tag(s) cannot be found, the track will still be uploaded without the intended assignment.

import { createReadStream } from 'node:fs';
import FormData from 'form-data';
import { request } from 'undici';

const audioFile = createReadStream(filePath, {
  autoClose: true,
});

const formData = new FormData();
formData.append('stationMedia', audioFile);
formData.append(
  'metadata',
  JSON.stringify({
    title: 'Title',
    album: 'Album',
    notes: 'Notes about this track',
  })
);

playlistIds.forEach((playlistId) => formData.append('playlistIds', playlistId));
tagIds.forEach((tagId) => formData.append('tagIds', tagId));

await request(
  `https://api.radiocult.fm/api/station/${stationId}/media/track`,
  {
    method: 'POST',
    body: formData,
    headers: {
      ...formData.getHeaders(),
      'x-api-key': secretKey,
    },
  }
);

Call this endpoint to upload an existing file from your Radio Cult track library to your connected Soundcloud account.

This endpoint is useful for building workflows and automating uploads.

The request takes a form data body. Use the returned id from uploading a track to form the URL.

NOTE: To ensure we can properly validate the input, you must send valid JSON for all fields except artworkData. This means you must JSON.stringify the fields before sending them in the form data.

  const formData = new FormData();
  formData.append('tags', JSON.stringify(['rock', 'pop']));
  formData.append('title', JSON.stringify('Autumn Mix'));
  formData.append('embeddableBy', JSON.stringify('all'));
  formData.append('sharing', JSON.stringify('public'));
  formData.append('downloadable', String(true));
  formData.append('commentable', String(false));

Call this endpoint to upload an existing file from your Radio Cult track library to your connected Mixcloud account.

This endpoint is useful for building workflows and automating uploads.

The request takes a form data body. Use the returned id from uploading a track to form the URL.

Some fields (disableComments, hideStats and hosts) require a Mixcloud Pro account.

NOTE: To ensure we can properly validate the input, you must send valid JSON for all fields except the artwork file. This means you must JSON.stringify the fields before sending them in the form data.

Call this endpoint to add a tag to an uploaded track.

Use the returned track ID from uploading a file to form the URL.

You can get the ID of a tag from the URL displayed in the tag view. For example, when viewing a tag your browser will display a URL like: https://app.radiocult.fm/tags?tag=2sZyt9DQDz8cLOUvFiZ2xS5MTIi. The tag ID in this case would be 2sZyt9DQDz8cLOUvFiZ2xS5MTIi.

This endpoint is useful for building workflows and automating uploads.

Call this endpoint to add an uploaded track to a playlist.

Use the returned track ID from uploading a file to form the URL.

You can get the ID of a playlist from the URL displayed in the playlist view. For example, when viewing a playlist your browser will display a URL like: https://app.radiocult.fm/playlists?playlist=2sZyt9DQDz8cLOUvFiZ2xS5MTIi. The playlist ID in this case would be 2sZyt9DQDz8cLOUvFiZ2xS5MTIi.

This endpoint is useful for building workflows and automating uploads.

The tag endpoints can be used to manage your tags. These endpoints are helpful when building automations and CLI workflows.

Due to the sensitive nature use your Secret Key when calling these endpoints.

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

Use your Secret Key when accessing this endpoint.

Call this endpoint to create a new tag. Use your station's ID to build the URL.

Use your Secret Key when accessing this endpoint.

Call this endpoint to update an existing tag. Use the tag's ID to form the URL.

Use your Secret Key when accessing this endpoint.

Call this endpoint to delete a tag. Use the tag's ID to form the URL.

Deleting a tag also removes it from any tracks and playlists it was assigned to.

Use your Secret Key when accessing this endpoint.

The playlist endpoints can be used to manage your playlists. These endpoints are helpful when building automations and CLI workflows.

Due to the sensitive nature use your Secret Key when calling these endpoints.

Call the get all playlists endpoint to retrieve a list of all of your playlists.

Use your Secret Key when accessing this endpoint.

Call this endpoint to create a new, empty playlist. Use your station's ID to build the URL.

Use your Secret Key when accessing this endpoint.

Call this endpoint to delete a playlist. Use the playlist's ID to form the URL.

Use your Secret Key when accessing this endpoint.

Call this endpoint to remove a single entry (a song or a tag) from a playlist. Use the playlist's ID to form the URL.

The sortRanking in the body identifies the specific entry to remove within the playlist.

Use your Secret Key when accessing this endpoint.

Call this endpoint to remove all entries (e.g. songs and tags) from a playlist. This will result in an empty playlist.

This endpoint is useful when automating content for repeating shows.

For example, you can create an event, attach a playlist to the event and make note of the playlist ID. You can then build a workflow where you clear the playlist, upload any new tracks and add to the playlist. You have effectively removed the audio for the previous show and prepared the playlist for the next occurrence of the show. All via the API.

Use your Secret Key when accessing this endpoint.

The recordings endpoints can be used to manage your recordings. These endpoints are helpful when building automations and CLI workflows.

Due to the sensitive nature use your Secret Key when calling these endpoints.

Call the get all recordings endpoint to retrieve a list of all of your recordings.

Use your Secret Key when accessing this endpoint.

Call the get recording download URL endpoint to retrieve a signed URL that can be used to download the recording.

The signed URL will expire after 30 minutes.

Use your Secret Key when accessing this endpoint.

Call this endpoint to update the metadata of an existing recording. Use the recording's ID to form the URL.

All body fields are optional - only the fields you provide will be updated.

Use your Secret Key when accessing this endpoint.

Call this endpoint to delete a recording. Use the recording's ID to form the URL.

Use your Secret Key when accessing this endpoint.

Call this endpoint to copy a recording into your track library as a track. Use the recording's ID to form the URL.

This is useful for turning a recorded show into a reusable track that you can add to playlists, tag, or upload to Mixcloud and Soundcloud.

Use your Secret Key when accessing this endpoint.