Getting Started
Base URL
https://app.myradio.click/api/v3Quick Example
Here's a quick example of how to make your first API request:
curl -H "X-API-KEY: your_api_key_here" \
https://app.myradio.click/api/v3/station💡 Tip: All API requests require authentication via an API key. Read the Authentication section below to learn how to get your API key.
Authentication
The Myradio.Click API uses API keys for authentication. All requests must include your API key in the X-API-KEY header.
Request Header
GET /api/v3/station HTTP/1.1
Host: app.myradio.click
X-API-KEY: mr_abc123def456789...⚠️ Security: Never share your API key or commit it to version control. Store it securely as an environment variable.
Managing API Keys
Creating Your First API Key
- 1. Log in to your dashboard:
Visit console.myradio.click and log in as a station owner. - 2. Navigate to API Keys:
Select your station and click on "API Keys" in the sidebar menu. - 3. Create a new key:
Click "Create New API Key", give it a name, and set a rate limit. - 4. Save your key:
Copy the generated key immediately - you won't be able to see it again!
Key Format
API keys follow this format:
mr_abc123def456789...Keys start with mr_ followed by 64 random hexadecimal characters.
Key Types & Permissions
- ✓ Access all GET endpoints
- ✓ View station, programs, episodes
- ✓ Fetch schedules and grids
- ✗ Cannot create or modify data
Best for: Website integrations, mobile apps, public displays
- ✓ All read-only permissions
- ✓ Create and update track logs
- ✓ Create and update programs
- ✓ Delete resources
Best for: Playout software, automation systems, integrations
Key Management
- Multiple Keys: Create separate keys for development, staging, and production
- Revoke: Instantly revoke compromised keys
- Rate Limits: Fixed at 120 requests per minute for all API keys
- Usage Tracking: Monitor when each key was last used
⚠️ Best Practice: Use read-only keys for public-facing applications (websites, apps). Only use read-write keys on secure backend systems like playout software.
API Endpoints
The V3 API provides both read and write access to your station data. Read-only API keys can access GET endpoints, while read/write API keys can also use POST, PUT, and DELETE endpoints. Click on each endpoint to view details, parameters, and examples.
Webhooks
Webhooks allow your station to automatically notify external systems when content changes. When programs, episodes, or station details are updated, your configured webhook endpoints will receive HTTP POST requests with the updated data.
Note: Webhook management is only available to station owners and admins through the console dashboard.
Event Types
- Programs: Triggered when a program is created, updated, or deleted
- Episodes: Triggered when an episode is created, updated, or deleted
- Station Details: Triggered when station information is updated
- Segments: Triggered when episode segments are modified
Webhook Payload
When an event occurs, your webhook endpoint receives a POST request with a JSON payload:
{
"type": "program",
"action": "update",
"station": {
"id": 1,
"name": "Radio Station Name",
"slug": "radio-station-name"
},
"program": {
"id": 123,
"name": "Morning Show",
"slug": "morning-show",
"bio": "Your favorite morning program",
"presenters": [...],
"slots": [...]
}
}Authentication
Webhook requests include your configured API key in the mr-header HTTP header. Use this to verify requests are coming from Myradio.Click:
// Express.js example
app.post('/webhook', (req, res) => {
const apiKey = req.headers['mr-header'];
if (apiKey !== process.env.EXPECTED_WEBHOOK_KEY) {
return res.status(401).json({ error: 'Unauthorized' });
}
const { type, action, station, program, episode } = req.body;
// Process the webhook...
console.log(`Received ${action} for ${type}`);
res.status(200).json({ received: true });
});Best Practice: Your webhook endpoint should respond within 10 seconds. For long-running operations, acknowledge the webhook immediately and process asynchronously. Webhook management and logs can be accessed through the console dashboard.
Rate Limiting
All API keys have a fixed rate limit of 120 requests per minute.
Response Headers
All responses include rate limit information:
HTTP/1.1 200 OK
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 95Rate Limit Exceeded
When you exceed your rate limit, you'll receive a 429 error:
{
"error": "Rate limit exceeded",
"message": "Too many requests. Maximum 120 requests per minute allowed.",
"meta": {
"code": "RATE_LIMIT_EXCEEDED",
"rate_limit": 120,
"retry_after_seconds": 45
}
}Error Response Format
All API errors follow a consistent format to help you handle them gracefully:
{
"error": "Short error description",
"message": "Detailed explanation of what went wrong",
"meta": {
"code": "ERROR_CODE",
// Additional error-specific metadata
}
}HTTP Status Codes
| Code | Meaning | Action |
|---|---|---|
| 200 | Success | Request completed successfully |
| 201 | Created | Resource created successfully (POST requests) |
| 400 | Bad Request | Check request body and parameters |
| 401 | Unauthorized | Check your API key is valid and not revoked |
| 403 | Forbidden | Your key doesn't have permission for this action |
| 404 | Not Found | Resource doesn't exist or was deleted |
| 422 | Validation Error | Check required fields and data formats |
| 429 | Too Many Requests | Wait and retry (see retry_after_seconds) |
| 500 | Server Error | Retry later, contact support if persists |
Common Error Codes
INVALID_API_KEYThe API key is missing, malformed, or doesn't exist.
{
"error": "Invalid API key",
"message": "The API key provided is invalid or does not exist.",
"meta": { "code": "INVALID_API_KEY" }
}REVOKED_API_KEYThe API key has been revoked by the station owner.
{
"error": "API key revoked",
"message": "This API key has been revoked. Please generate a new key.",
"meta": { "code": "REVOKED_API_KEY" }
}WRITE_PERMISSION_REQUIREDAttempting a write operation with a read-only API key.
{
"error": "Write permission required",
"message": "This operation requires a read/write API key. Your key is read-only.",
"meta": { "code": "WRITE_PERMISSION_REQUIRED" }
}VALIDATION_ERRORThe request body has validation errors.
{
"error": "Validation failed",
"message": "The given data was invalid.",
"meta": {
"code": "VALIDATION_ERROR",
"errors": {
"artist": ["The artist field is required."],
"title": ["The title field is required when track is not present."]
}
}
}Code Examples
JavaScript / Node.js
const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://app.myradio.click/api/v3';
async function getStation() {
const response = await fetch(`${BASE_URL}/station`, {
headers: {
'X-API-KEY': API_KEY
}
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
return await response.json();
}
async function searchPrograms(query) {
const response = await fetch(
`${BASE_URL}/programs?search=${encodeURIComponent(query)}&limit=10`,
{ headers: { 'X-API-KEY': API_KEY } }
);
return await response.json();
}
// Usage
getStation().then(data => {
console.log('Station:', data.data.name);
});Python
import requests
API_KEY = 'your_api_key_here'
BASE_URL = 'https://app.myradio.click/api/v3'
headers = {'X-API-KEY': API_KEY}
def get_station():
response = requests.get(f'{BASE_URL}/station', headers=headers)
response.raise_for_status()
return response.json()
def search_programs(query, limit=10):
params = {'search': query, 'limit': limit}
response = requests.get(
f'{BASE_URL}/programs',
headers=headers,
params=params
)
response.raise_for_status()
return response.json()
# Usage
station = get_station()
print(f"Station: {station['data']['name']}")
programs = search_programs('jazz')
print(f"Found {programs['meta']['total']} programs")PHP
<?php
$apiKey = 'your_api_key_here';
$baseUrl = 'https://app.myradio.click/api/v3';
function makeRequest($url, $apiKey) {
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'X-API-KEY: ' . $apiKey
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode !== 200) {
throw new Exception("API request failed: HTTP $httpCode");
}
return json_decode($response, true);
}
function getStation($baseUrl, $apiKey) {
return makeRequest("$baseUrl/station", $apiKey);
}
// Usage
$station = getStation($baseUrl, $apiKey);
echo "Station: {$station['data']['name']}\n";StationPlaylist Creator Integration
Send now-playing track data from StationPlaylist Creator automatically to your myradio.click station.
Setup Instructions:
- Create an API key with Read + Write permissions in your station dashboard
- In StationPlaylist Creator, go to Settings > Now Playing
- Set HTTP Mode to POST
- Set URL to:
https://app.myradio.click/api/v3/episode-logs - Add custom header:
X-API-KEY: your_api_key_here - Use JSON format with the fields below
StationPlaylist JSON Body Template:
{
"artist": "%artist%",
"title": "%title%",
"album": "%album%",
"source": "stationplaylist"
}The %artist%, %title%, and %album% placeholders will be replaced by StationPlaylist with the current track data.
RadioDJ Integration (PHP Script)
Use this PHP script to send now-playing data from RadioDJ or other playout software:
<?php
// RadioDJ Now Playing Script for myradio.click
$apiKey = 'mr_your_api_key_here';
$apiUrl = 'https://app.myradio.click/api/v3/episode-logs';
// Get track info from RadioDJ (customize based on your setup)
$artist = isset($argv[1]) ? $argv[1] : '';
$title = isset($argv[2]) ? $argv[2] : '';
$album = isset($argv[3]) ? $argv[3] : '';
if (empty($artist) || empty($title)) {
exit("Error: Artist and title are required\n");
}
$data = [
'artist' => $artist,
'title' => $title,
'album' => $album,
'source' => 'radiodj'
];
$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'X-API-KEY: ' . $apiKey,
'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode === 200 || $httpCode === 201) {
echo "Track logged successfully\n";
} else {
echo "Error: HTTP $httpCode - $response\n";
}
?>Try It Live
Test the API directly from your browser. Enter your API key and try making requests to different endpoints.
Ready to Get Started?
Create your API key and start building with the Myradio.Click API today.
Go to Dashboard