ERICADE Radio API

ERICADE Radio · Developer portal

ERICADE Radio API

The ERICADE API provides structured, machine-readable metadata from the ERICADE radio network, covering demoscene culture, tracked music, radio playlists, shows, artists, and historical context.

Read the API documentation Station Data WebSocket
What is playing right now, in two requests
# 1. Get a token
TOKEN=$(curl -s https://radio.ericade.net/get-token/)

# 2. Ask what station 1 is playing
curl -s https://api.ericade.net/radio/v2/nowplaying/ \
  -d '{"Token":"'$TOKEN'","StationID":1,"Sequence":0}'
Base URL
https://api.ericade.net/
v2 endpoints under /radio/v2/
Authentication
Token from radio.ericade.net/get-token/, sent in the request body
Format
JSON over HTTPS, POST with a JSON body
Rate limit
Per IP address; 429 with Retry-After

About ERICADE Radio

The data behind ericade.radio

ericade.radio plays demoscene, chiptune, Amiga and tracker music, and keeps track of the artists and the scene history around it.

This API is what the station's own website is built on: what is playing now and what is up next, the track library and its artists, playout history, news and podcast episodes, statistics, the request line and star ratings. The same data is open to your player, bot, widget or research project.

Listen at ericade.radio

ERICADE Radio at a glance

  • Station 1: ericade.radio, tracked music around the clock
  • Station 2: Best of ericade.radio, the podcast station
  • Operated by: The ERICADE Radio Network
  • API versions: v2 under /radio/v2/; the original v1 under /radio/
  • Contact: radio@ericade.net

What you get

Everything the station knows, as JSON

Current and historical playout metadata, track, artist and station context fields, and request eligibility and request-line status, in several endpoint families under /radio/.

On air

Now playing and history

What a station is playing, with comprehensive metadata about the track and its artist, what is next up, and what has been played before.

Library

Tracks and artists

Search the track library, page through tracks and artists, and read biographies, external links, ratings and the tracks credited to each artist.

Listeners

Requests and ratings

Show a live request line, see which tracks can be requested right now, submit a request, and record 1–5 star ratings.

Live

Station data WebSocket

Events pushed the moment they happen, for both stations over one connection: now playing, next up, song requests, star ratings and messages from the station.

More than playout

  • News and podcasts: news posts and podcast episodes, with paging, free-text and tag search, and optional transcripts.
  • Statistics: station statistics, and a live snapshot of who is listening right now.
  • New on the station: the tracks most recently added to the library, with their ratings and request eligibility.

Accounts and content

The API also holds the user accounts of radio.ericade.net, and the administration of its news, podcast episodes and comments. Those endpoints carry credentials, so they follow stricter rules of their own and answer only to the website. They are documented alongside the rest.

User accounts · Content administration

How it works

From nothing to now playing in three steps

  1. Get a token

    Make a GET request to https://radio.ericade.net/get-token/. The response is a raw JWT string. There is nothing to sign up for.

  2. Post a JSON body

    Send a POST to an endpoint under /radio/v2/, with the token in the Token field and the station in StationID.

  3. Read the answer

    Data comes back as JSON, for example {"Tracks": [...]}. A failure is a message, a subcode and a submessage.

For developers

The Radio API

A JSON API over HTTPS. Every v2 endpoint lives under /radio/v2/, takes a POST with a JSON body and answers with JSON. Calls are authenticated with a token that anyone can fetch, and the data endpoints answer with Access-Control-Allow-Origin: *.

Get a token

  1. Request https://radio.ericade.net/get-token/ with GET.
  2. Take the response as it is: a raw JWT string, not JSON.
  3. Send it as Token in the JSON body of every call, next to the StationID (1 or 2).
  4. Fetch a fresh token for each session; reusing tokens across sessions is inadvisable.
Token or Password?

The field name is not the same on every endpoint. Most read Token; news, addrequest and settings read the same token from Password. Sending the wrong one leaves the call unauthenticated.

Example request body
{
  "Token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "StationID": 1,
  "Sequence": 0
}
Failures return a status message
{
  "message": "Failure",
  "subcode": "FALSE",
  "submessage": "You need to specify a StationID."
}

Endpoints

The v2 endpoints most integrations use. Paths are relative to https://api.ericade.net; each links to its documentation, which lists every endpoint.
Method Path Returns or does
POST /radio/v2/nowplaying/ What a station is playing, with full track and artist metadata; answers 204 when nothing has changed
POST /radio/v2/getnextup The station's upcoming queue on its own, small enough to poll separately
POST /radio/v2/songs/<trackid>/ Full metadata for one track, in the same shape as now playing
POST /radio/v2/search Free-text search of the track library
POST /radio/v2/songs Paged listing of the track library, with a total count
POST /radio/v2/artists Paged listing of artists with biography, links, rating and credited tracks; artists/<artistid> returns one
POST /radio/v2/songhistory The recently played tracks on a station
POST /radio/v2/new-songs The tracks most recently added to the library, newest first
POST /radio/v2/news News posts and podcast episodes, with paging, search and optional transcripts
POST /radio/v2/stats Statistics for a station; listening next to it returns who is listening right now
POST /radio/v2/requests The request queue and recent request history, for a live request line
POST /radio/v2/addrequest Submits a listener request to the station's request queue
POST /radio/v2/rating Records a listener's 1–5 star rating for a track
WSS wss://api.ericade.net/ws/stationdata The station data WebSocket: live events for both stations over one connection
WSS wss://api.ericade.net/ws/chat The chat WebSocket: radio.ericade.net's listeners and the station's Discord in one conversation, for logged-in visitors

Responses

Endpoints that return data echo their JSON payload directly, for example {"Tracks": [...]}. Failures come as message, subcode and submessage. Some endpoints return that failure with HTTP 200, so always check the message field of the body.

Status codes

  • 200 success
  • 204 nothing has changed since the Sequence you sent
  • 400 validation or authentication failure, or an unknown endpoint
  • 429 rate limited

Rate limiting

Every endpoint shares one throttle per client IP address. Going over starts a temporary ban during which every request answers 429; wait for the time in the Retry-After header before retrying.

Documentation

The full reference

Every endpoint, request field, response field and error is described in the API documentation, the authoritative reference for the API. The v2 documentation is in progress and was last updated 2026-09-19.

API v2 documentation

Full endpoint reference, request and response fields, and examples.

Station Data WebSocket

The WebSocket relay for station data events: connecting, the message envelope, every event, limits and client best practices.

Chat WebSocket

The chat that joins the website and Discord: logging in with a ticket, the messages, the limits, the Discord bridge and how to run it.

API v1 documentation

The original /radio/ endpoints. New integrations should use v2 where an equivalent exists.

OpenAPI description

The v2 API as an OpenAPI 3.1 document, for code generators and API clients.

Documentation as PDF

The API v2 documentation, laid out for print and offline reading.

FAQ

Frequently asked questions

Do I need an API key?

No. Fetch a token with a GET request to https://radio.ericade.net/get-token/ and send it in the body of each call. The token identifies a browser or client, not a person.

Which stations does the API cover?

Two. StationID 1 is ericade.radio, with tracked music around the clock, and 2 is Best of ericade.radio, the podcast station.

Is the API rate limited?

Yes. Every endpoint shares one throttle per client IP address. Going over returns HTTP 429; retrying while banned does not succeed, so back off until the time in the Retry-After header has passed.

How do I follow what is playing without polling hard?

Send the TimeStamp of the previous answer as Sequence to now playing and get 204 until the track changes, or connect to the Station Data WebSocket and have the events pushed to you.

Why did a failed call answer HTTP 200?

Several data endpoints, now playing and search among them, return their failure message with HTTP 200. Do not branch on the status code alone: check the message field of the body.

Is v1 still available?

Yes. The original endpoints live directly under /radio/ and have their own documentation. New integrations should use v2 where an equivalent exists.

Where is the API documentation?

The complete v2 reference is at api.ericade.net/docs/ericade-api-v2.html, and is also available as a PDF and as an OpenAPI description.

Where can I get help?

Write to radio@ericade.net.