RadioCult Online Radio API Reference

The RadioCult radio API for developers follows REST principles and covers both sides of your station: read your schedule, artists, tracks and now playing data to power a website or app, and write back to create shows, build playlists and manage your library.

Everything below applies whether you are building a player, a schedule page, a mobile app, or an automation that runs every week.

Not a developer?

You do not need to write code to automate your station. Connect an AI assistant like Claude or ChatGPT to our MCP server and manage your station by asking: build next week of shows, tag a night of new tracks, or tidy a playlist that has grown too long. It calls the same endpoints documented here on your behalf.

If you work with an AI coding agent, our agent skills teach it to build against this API correctly, so you can ask for a player or a schedule page and get working code rather than a plausible guess.

To put RadioCult on your site without any of that, use 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 RadioCult account before you can power your station with our APIs. Go to our sign up page to get started!

Custom player skill

Helps your agent build a custom web player for your station: live now-playing metadata over WebSockets, an audio element that always joins at the live edge and disconnects cleanly on pause (keeping your listener analytics accurate), and publishable-key-only authentication.

Station website skill

Helps your agent build your station website from the API: weekly programme grids and schedule pages, artist directory and profile pages, and a recently-played tracks feed. It uses the expand param to hydrate artists and tags in one request only when they are shown, handles UTC to local timezone conversion, renders TipTap descriptions and builds artist pages from slugs.

Media upload skill Connect

Lets your agent upload tracks straight to your media library for you. Tell it "upload this folder to my station" and it validates the files (mp3 or m4a, under 750MB), confirms the list, uploads sequentially with rate-limit awareness and reports the results. Also covers metadata overrides, playlist and tag assignment, and building your own upload automations. Uses your secret key, so it belongs in server-side or CLI workflows.

Schedule automation skill Connect

Lets your agent build and maintain your schedule for you, and helps it write a sync that keeps RadioCult in step with a roster spreadsheet, a CMS or a booking form. Covers creating, updating and deleting events, repeating series with valid recurrence rules, booking artists onto shows, and the scope rules that decide whether a change hits one show or the whole series. It reads the range before it writes so a re-run does not double-book, converts show times through your station's timezone, and confirms destructive changes with you first.

Connection URL

Point your MCP client at the URL below. It speaks the Streamable HTTP transport.

Authentication

There is no API key to paste into your client. The first time your agent connects, RadioCult opens a consent screen in your browser. Approve it and your agent receives a scoped, revocable grant for your station. Your API key never touches the client.

When you connect you choose a scope:

• Read. The agent can only query your station: now playing, schedule, artists, tracks, tags, playlists, recordings and playout history.
• Write. The agent can also make changes, including creating and updating data and destructive actions such as deleting artists or clearing a playlist.

Choose read unless the agent genuinely needs to make changes. To switch scope later, reconnect and pick the other option.

Adding it to your agent

Claude Code. Add the server from your terminal:

claude mcp add --transport http radiocult https://mcp.radiocult.fm/mcp

Claude desktop, ChatGPT, Cursor and others. Add a custom connector (or MCP server) in your client's settings and give it the connection URL above. Each client's screen is a little different, but they all need the same URL. Your browser will open the consent screen the first time the agent connects.

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 Connect 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 it 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 RadioCult URL.

The RadioCult 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.

Three codes are worth calling out. 401 means the x-api-key header is missing or the key is not recognised. 403 means the key is recognised but is not allowed on that endpoint, most often a publishable key used on a write. 402 means the key and the request are both fine, but the station cannot use that endpoint on its current plan, either because the plan is not active or because it is a Connect endpoint and the station does not have Connect.

To ensure fair usage, we enforce rate limits on key Connect 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 RadioCult 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.

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

duration is expressed in minutes and must be between 1 - 1440 (24 hours).

Provide an rrule to create a repeating event, or omit it to create a standalone event. It takes an RFC 5545 recurrence rule, the pattern only (e.g. FREQ=WEEKLY;BYDAY=MO;WKST=SU). You don't include a DTSTART; the series is anchored to startDateUtc.

Supported patterns match what the platform offers: daily, weekly (one or more days), and monthly on a day-of-month or a weekday-of-month, with an optional interval and WKST=SU. For monthly patterns the day-of-month or weekday-of-month must match startDateUtc. A weekday-of-month pattern takes a BYSETPOS of 1 to 5 for a fixed occurrence, or -1 for the last of that weekday in the month (FREQ=MONTHLY;BYSETPOS=-1;BYDAY=FR;WKST=SU), in which case startDateUtc must fall on the last such weekday. Anything else (e.g. FREQ=YEARLY or a COUNT) is rejected. Add an UNTIL to bound the series, or omit it to repeat indefinitely.

If provided, description must either be a string or TipTap JSON format. A string is stored as a single paragraph.

artistIds books artists onto the event. A maximum of 10 can be provided, and each one must already exist on the station.

Every ID referenced by media is checked before the event is created, so a track, playlist or relay that does not exist fails the whole request.

color is optional. If provided, it must be one of the palette colours below, any other value is rejected. Click a swatch to copy its hex code.

Update an existing event. Use the event's originalId to form the URL.

Use scope to control which events are updated:

• all updates the whole series. Always use all when updating a standalone event,
• this only updates a single instance of a repeating event, identified by instanceStart (required), or
• thisAndFollowing updates the target instance - identified by instanceStart (required) - and all following instances of a repeating event.

If provided, description must either be a string or TipTap JSON format. A string is stored as a single paragraph.

color is optional. If provided, it must be one of the palette colours below, any other value is rejected. Click a swatch to copy its hex code.

Delete an event. Use the event's originalId to form the URL.

Use scope to control which events are deleted:

• all deletes the whole series. Always use all when deleting a standalone event,
• this only deletes a single instance of a repeating event, identified by instanceStart (required), or
• thisAndFollowing deletes the target instance - identified by instanceStart (required) - and all following instances of a repeating event.

Add an artist to an event. Use the event's originalId and the artist's ID to form the URL. The artist is added to the whole series.

Remove an artist from an event. Use the event's originalId and the artist's ID to form the URL. The artist is removed from the whole series.

The Artist object represents an instance of an artist (or presenter, or host, or whatever language you choose) in RadioCult. 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 set an artist's profile image. Use the artist's ID to form the URL.

The request takes a form data body, where artistImage is the image file you wish to upload. The file must be less than 10MB.

Uploaded images are re-encoded to JPEG. The updated artist is returned with its new logo map, so you do not need a follow-up request to read the URLs back.

An artist has a single image. Uploading a new one replaces the existing image, and the previous image is removed.

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

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

const formData = new FormData();
formData.append('artistImage', imageFile);

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

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 RadioCult.

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 RadioCult 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 RadioCult 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.