Streams

List All Streams

GET /stream

Returns a list of all active streams. No auth required.

Example:

curl https://api.radioreg.net/stream

Response:

[
  {
    "id": 1,
    "name": "Radio Example",
    "url": "https://stream.example.com/live",
    "tags": ["pop", "hits"],
    "organization": {
      "id": 1,
      "name": "Example Radio",
      "image": "https://cdn.radioreg.net/logos/example.png"
    },
    "song": {
      "title": "Blinding Lights",
      "artist": "The Weeknd",
      "cover": "https://cdn.example.com/cover.jpg",
      "songDuration": 200,
      "songStartedAt": 1730465520,
      "next": {
        "title": "Next Song",
        "artist": "Next Artist",
        "cover": null
      }
    },
    "isStreamOfTheMonth": false,
    "isNewcomerOfTheMonth": false,
    "isRecentPopularStream": false,
    "isTopVotedStream": false
  }
]

---

Song History

GET /stream/:id/history

Returns the current song, next song, and the last 3 played songs of a stream. No auth required.

Parameters:

Name	Type	Description
id	integer	Stream ID

Example:

curl https://api.radioreg.net/stream/1/history

Response:

{
  "current": {
    "id": "ab399e04-9835-40aa-aad4-fb14e6e0e700",
    "title": "Blinding Lights",
    "artist": "The Weeknd",
    "cover": "https://cdn.example.com/cover.jpg"
  },
  "next": {
    "title": "Next Song",
    "artist": "Next Artist",
    "cover": null
  },
  "history": [
    {
      "id": 42,
      "title": "Song Name",
      "artist": "Artist Name",
      "cover": "https://cdn.example.com/cover.jpg",
      "playedAt": "2024-11-01T14:32:00.000Z"
    }
  ]
}

next is null if no next track is available.

---

Get Votes

GET /stream/:id/votes

Returns the vote counts for a stream. If a JWT is sent, the response also includes the user's own vote.

Parameters:

Name	Type	Description
id	integer	Stream ID

Example without auth:

curl https://api.radioreg.net/stream/1/votes

Example with auth:

curl https://api.radioreg.net/stream/1/votes \
  -H "Authorization: Bearer <token>"

Response:

{
  "upvotes": 42,
  "downvotes": 3,
  "score": 39,
  "userVote": "up"
}

userVote is null if not logged in or not yet voted.

---

Vote

POST /stream/:id/vote

Votes for or against a stream. Requires authentication. Voting the same type again removes the vote.

Parameters:

Name	Type	Description
id	integer	Stream ID

Request Body:

{
  "voteType": "up"
}

Field	Type	Values
voteType	string	"up" or "down"

Example:

curl -X POST https://api.radioreg.net/stream/1/vote \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"voteType": "up"}'

Response:

{
  "message": "Vote saved"
}

Possible messages: "Vote saved", "Vote updated", "Vote removed".

---

Update Stream Data (Webhook)

POST /stream/update/:streamUUID

Updates the currently playing song data of a stream. Requires the Organization API Token.

This endpoint accepts the simple RadioReg format as well as native AzuraCast webhooks.

Parameters:

Name	Type	Description
streamUUID	string	UUID of the stream

Request Body:

{
  "title": "Song Name",
  "artist": "Artist Name",
  "art": "https://cdn.example.com/cover.jpg",
  "nextTitle": "Next Song",
  "nextArtist": "Next Artist",
  "nextArt": "https://cdn.example.com/next-cover.jpg",
  "songDuration": 214,
  "songStartedAt": 1730465520
}

Field	Type	Required	Description
title	string	no	Current song title
artist	string	no	Current artist
art	string	no	Cover art URL
nextTitle	string	no	Next song title
nextArtist	string	no	Next artist
nextArt	string	no	Cover art URL of the next song
songDuration	number	no	Song duration in seconds
songStartedAt	integer	no	Unix timestamp of song start

Example:

curl -X POST https://api.radioreg.net/stream/update/a1b2c3d4-e5f6-... \
  -H "Authorization: Bearer rr_org_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Blinding Lights",
    "artist": "The Weeknd",
    "songDuration": 200,
    "songStartedAt": 1730465520
  }'