SonicPanel Documentation


Clients API
Radios
HOME

Clients API Guide

Available after v3.35 update.

With this API your own website can talk to your radio. For example, you can show the song that is playing now, let visitors request songs, show the listener count, or start and stop your AutoDJ. You only need basic PHP knowledge. Every feature below has a short PHP example that you can copy and paste.

Before you start

1. Get your API URL and API key

Log in to your control panel and open API Information in the left menu. You will see two things there:

  • API Endpoint URL - the address of the API. It looks like https://your-panel-domain.com/cp/api.php
  • API Key - your private password for the API.

Copy both and keep them safe. On the same page you can also download a ready-to-use example website project.

Keep your API key private. Anyone who knows the key can use your API. Put it only in PHP files on your server. Never write it in JavaScript or in HTML that visitors can see. If the key is leaked, press Regenerate Key on the API Information page.

2. Important rules

  • Do not call the API on every page view. If your website gets many visitors, ask the API only once every few seconds and show the saved result to everyone (the helper in step 3 does this for you).
  • More than 120 calls per minute with the same API key blocks the key for 10 minutes.
  • More than 10 wrong API keys per minute from the same IP address blocks that IP address for 10 minutes.
  • Do not use API calls on your website directly unless your website is protected by Cloudflare.

3. Copy this helper file once

Save the code below as sp_api.php on your website. Replace the URL and the key with your own. Every example in this guide uses it, so you do not have to write the technical part again.

 false, 'message' => 'The radio could not be reached.');
    }
    return $result;
}

// Same as sp_api() but remembers the answer for a few seconds.
// Use it for pages that many visitors open.
function sp_api_cached($action, $params = array(), $seconds = 10)
{
    $file = sys_get_temp_dir() . '/sp_api_' . md5($action . serialize($params)) . '.json';

    if (is_file($file) && (time() - filemtime($file)) < $seconds) {
        $saved = json_decode(file_get_contents($file), true);
        if (is_array($saved)) { return $saved; }
    }

    $result = sp_api($action, $params);
    if (!empty($result['success'])) {
        file_put_contents($file, json_encode($result));
    }
    return $result;
}
?>

4. How answers look

Every answer has a success value. When it is true the call worked and the data is included. When it is false there is a message that tells you what went wrong in plain English.

// It worked
{ "success": true, ... }

// It did not work
{ "success": false, "error": "invalid_api_key", "message": "The API key is missing or invalid." }

In the examples we always check success first.

Show what is happening on your radio

Now playing

Shows the song that is playing right now, and whether a live DJ is on air. The AutoDJ must be online.

Answer


{
  "success": true,
  "song": { "artist": "Artist Name", "title": "Song Title", "started_at": "2026/10/14 22:28:05" },
  "live": false,
  "dj": ""
}



live is true when a live DJ is on air and dj shows who it is. song can be empty (null) when the song cannot be detected.



Next song



Shows the one song that will play after the current song. The AutoDJ must be online.



Answer


{
  "success": true,
  "song": { "position": 1, "artist": "Artist Name", "title": "Song Title", "source": "playlist" }
}



Next 5 songs



Shows the next 5 songs in playing order. The AutoDJ must be online.



';
    }
}



Answer



{
  "success": true,
  "queue": [
    { "position": 1, "artist": "Artist Name", "title": "Song Title", "source": "request" },
    { "position": 2, "artist": "Another Artist", "title": "Another Song", "source": "playlist" }
  ]
}



source tells where the song comes from: request (a visitor asked for it), scheduled (a scheduled playlist) or playlist (the normal AutoDJ playlist).



Upcoming queue (choose how many)



The same as "Next 5 songs", but you choose how many songs you want (1 to 10).



 8), 10);

if ($r['success']) {
    foreach ($r['queue'] as $song) {
        echo $song['artist'] . ' - ' . $song['title'] . '
';
    }
}



Song history



Shows the songs that were played recently, newest first. limit is optional (1 to 50, default 10).



 10), 30);

if ($r['success']) {
    foreach ($r['history'] as $song) {
        echo $song['played_at'] . ' - ' . $song['artist'] . ' - ' . $song['title'] . '
';
    }
}



Answer



{
  "success": true,
  "history": [
    { "artist": "Artist Name", "title": "Song Title", "played_at": "2026-10-14 22:28:05" }
  ]
}



Listeners



Shows how many people are listening now, and how many listeners you had in each hour today.



Answer


{
  "success": true,
  "listeners": 12,
  "unique_listeners": 10,
  "today_hourly": { "h00": 3, "h01": 1, "h02": 0, ... "h23": 0 }
}



listeners is the number of connections, unique_listeners counts each person once.



Live DJ status



Tells you if a live DJ is on air right now. This call also works when the AutoDJ is offline.



Answer


{ "success": true, "autodj_online": true, "live": true, "dj": "dj_john" }



Song requests



A song request page has three steps: show the playlists, show the songs, and send the request when the visitor picks a song.



Get the playlists



Lists your playlists that contain songs. Use the id of a playlist in the next calls.



';
    }
}



Answer



{
  "success": true,
  "playlists": [
    { "id": 12, "name": "Pop Hits", "total": 148 },
    { "id": 15, "name": "Rock Classics", "total": 96 }
  ]
}



Get the songs of a playlist



Lists the songs (artist and title) of one playlist. If you leave playlist_id out, you get your whole music library. Long lists are split into pages: use page and per_page (up to 100).



 12, 'page' => 1, 'per_page' => 50), 60);

if ($r['success']) {
    echo 'Playlist: ' . $r['playlist'] . ' (' . $r['total'] . ' songs)
';
    foreach ($r['tracks'] as $song) {
        echo $song['id'] . ' - ' . $song['artist'] . ' - ' . $song['title'] . '
';
    }
}



Answer



{
  "success": true,
  "total": 148,
  "page": 1,
  "per_page": 50,
  "playlist_id": 12,
  "playlist": "Pop Hits",
  "tracks": [
    { "id": 3041, "artist": "Artist Name", "title": "Song Title", "playlist_id": 12, "playlist": "Pop Hits" }
  ]
}



The id of a song is what you send in the request call below.



Search songs



Finds songs by artist or title. The search text must be at least 2 characters. You can add playlist_id to search inside one playlist only.



 $text), 30);

if ($r['success']) {
    foreach ($r['tracks'] as $song) {
        echo $song['artist'] . ' - ' . $song['title'] . '
';
    }
} else {
    echo $r['message'];
}



The answer has the same shape as "Get the songs of a playlist".



Send a song request



Adds the chosen song to the request queue. Send the id of the song. Also send the visitor's IP address as visitor_ip, so the limits work per visitor and not for your whole website.



Do not use sp_api_cached() here. A request must always be sent for real.



 (int)$_POST['track_id'],
    'visitor_ip' => $_SERVER['REMOTE_ADDR'],
));

if ($r['success']) {
    echo 'Thank you! Your request is number ' . $r['position'] . ' in the queue.';
} else {
    echo $r['message'];
}



Answer



{
  "success": true,
  "message": "Your song request has been added to the queue.",
  "track": { "id": 3041, "artist": "Artist Name", "title": "Song Title" },
  "position": 2,
  "interrupted": false
}



When a request is refused



Just show the message to your visitor. The most common reasons are:




	
		

			Message you will get
			What it means
		

		

			Too many song requests. Please try again later.
			This visitor has sent too many requests in one hour.
		

		

			This song was requested recently...
			The same song cannot be requested again for a while.
		

		

			The request queue is full...
			Too many requests are waiting in the queue.
		

		

			Scheduled playlist is playing and interruption is disabled...
			A scheduled show is on air and you do not allow requests during it.
		

		

			A live DJ is on air...
			Requests are not accepted while a live DJ is on air.
		

	




You can change the request limits and the "Can Interrupt" option on the API Information page, under Song Request.



Control your AutoDJ



Start AutoDJ



Starts your AutoDJ. If it is already running, it is restarted.



Answer


{ "success": true, "message": "AutoDJ started.", "restarted": false }



Stop AutoDJ



Stops your AutoDJ.



Answer


{ "success": true, "message": "AutoDJ stopped." }



Use these two calls only from a private page that you protect with a password. Do not put them on a public page.



Manage DJ accounts



DJ accounts are the logins your DJs use to connect to your radio live. The DJ username and password must not be used by anyone else on the server.



List DJ accounts



Shows all your DJ accounts and what each DJ is allowed to do. Passwords are never shown.



';
    }
}



Answer



{
  "success": true,
  "total": 1,
  "djs": [
    { "username": "dj_john", "canlogin": "yes", "canstream": "yes", "canplayjingles": "yes", "canuploadpic": "yes",
      "canusevoice": "no", "canchangepass": "no", "canstartrad": "no", "canstartdj": "no", "canskip": "no" }
  ]
}



Add a DJ account



Creates a new DJ. The username must be 3 to 32 characters (letters, numbers, underscore or dot). The password must be 4 to 64 characters. Permissions are optional, use yes or no.



 'dj_john',
    'dj_pass'     => 'S3cretPass',
    'canstream'   => 'yes',
    'canskip'     => 'no',
));

echo $r['message'];



Answer



{ "success": true, "message": "DJ account created.", "dj": { "username": "dj_john", "canstream": "yes", ... } }



Change a DJ account



Changes the password and/or the permissions of a DJ. Send only what you want to change.



 'dj_john',
    'dj_pass'     => 'NewS3cretPass',
    'canskip'     => 'yes',
));

echo $r['message'];



Delete a DJ account



Deletes a DJ account for good.



 'dj_john'));

echo $r['message'];



DJ permissions



You can send any of these when you add or change a DJ. The default is used when you do not send it.




	
		

			Name
			Default
			What the DJ can do
		

		

			canlogin
			yes
			Log in to the DJ panel.
		

		

			canstream
			yes
			Stream live to the radio.
		

		

			canplayjingles
			yes
			Play jingles.
		

		

			canuploadpic
			yes
			Upload a profile picture.
		

		

			canusevoice
			no
			Use the voice (microphone mix) feature.
		

		

			canchangepass
			no
			Change their own password.
		

		

			canstartrad
			no
			Start and stop the radio.
		

		

			canstartdj
			no
			Start and stop the AutoDJ.
		

		

			canskip
			no
			Skip the current song.
		

	




If something goes wrong



When success is false, read the message. These are the most common ones:




	
		

			Message
			What to do
		

		

			The API key is missing or invalid.
			Check that you copied the full key from the API Information page. If you regenerated the key, use the new one.
		

		

			Only POST requests are accepted.
			Use the helper file from this guide, it sends the call in the right way.
		

		

			AutoDJ is currently offline.
			Start your AutoDJ from the panel or with the start_autodj call.
		

		

			AutoDJ is not available for this account.
			Your hosting package does not include AutoDJ.
		

		

			Too many requests... is blocked for 10 minute(s).
			Your website calls the API too often. Wait 10 minutes and use sp_api_cached() so visitors share one answer.
		

		

			The radio could not be reached.
			Check the API URL in sp_api.php.
		

	




Example website



If you want to see everything working together, download the example project from the SonicPanel API Information page (Song Request, Download Example PHP Project). Upload it to your web server, write your API URL and API key into config.php and open index.php. It has a playlist list, search, request buttons and the upcoming songs.
Copyright © 2026 SonicPanel