Documentation

Everything you need to build, integrate, and manage your radio station

Getting Started

Base URL

https://app.myradio.click/api/v3

Quick 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. 1. Log in to your dashboard:
    Visit console.myradio.click and log in as a station owner.
  2. 2. Navigate to API Keys:
    Select your station and click on "API Keys" in the sidebar menu.
  3. 3. Create a new key:
    Click "Create New API Key", give it a name, and set a rate limit.
  4. 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

READ-ONLYRead-Only Keys
  • ✓ 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

READ + WRITERead-Write Keys
  • ✓ 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: 95

Rate 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

CodeMeaningAction
200SuccessRequest completed successfully
201CreatedResource created successfully (POST requests)
400Bad RequestCheck request body and parameters
401UnauthorizedCheck your API key is valid and not revoked
403ForbiddenYour key doesn't have permission for this action
404Not FoundResource doesn't exist or was deleted
422Validation ErrorCheck required fields and data formats
429Too Many RequestsWait and retry (see retry_after_seconds)
500Server ErrorRetry later, contact support if persists

Common Error Codes

INVALID_API_KEY

The 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_KEY

The 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_REQUIRED

Attempting 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_ERROR

The 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:

  1. Create an API key with Read + Write permissions in your station dashboard
  2. In StationPlaylist Creator, go to Settings > Now Playing
  3. Set HTTP Mode to POST
  4. Set URL to: https://app.myradio.click/api/v3/episode-logs
  5. Add custom header: X-API-KEY: your_api_key_here
  6. 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.

Your API key will not be stored. Get your key from the dashboard.

Format: key1=value1&key2=value2

Ready to Get Started?

Create your API key and start building with the Myradio.Click API today.

Go to Dashboard
myradio.click
© 2026 Myradio.click