Hosting edition

Provisioning API

Create, change, suspend and delete customer stations at runtime, and read usage and royalty reports, over a JSON API.

The Hosting edition's API lets your billing system or panel manage stations while the server runs. Changes apply at once, without a restart.

Basics#

  • Base path: /api/hosting/v1, on the same ports as everything else (port, and tls_port if set). Serve it over TLS.
  • Every request needs Authorization: Bearer <api_token>, the hosting.api_token from your configuration. Without it the API answers 401.
  • Request bodies are JSON objects with Content-Type: application/json, at most 64 KiB.
  • Errors are JSON: {"error": "..."}.
  • Months are YYYY-MM in UTC. Where month is optional, it defaults to the current month.
export TOKEN=replace-with-your-api-token
curl -H "Authorization: Bearer $TOKEN" https://radio.example/api/hosting/v1/stations

Endpoints#

Method and path Does
GET /stations List stations with live status.
POST /stations Create a station. Answers 201.
GET /stations/{id} One station.
PATCH /stations/{id} Change fields. null clears a limit.
DELETE /stations/{id} Delete the station and disconnect it. Answers 204.
POST /stations/{id}/suspend Suspend, and disconnect the source and listeners.
POST /stations/{id}/unsuspend Allow connections again.
GET /stations/{id}/usage?month=YYYY-MM Usage for one month.
GET /usage?month=YYYY-MM Usage for every station.
GET /stations/{id}/reports/sessions.csv?month= Listener sessions, as CSV.
GET /stations/{id}/reports/plays.csv?month= Songs played, with listeners at the time, as CSV.
GET /stations/{id}/reports/summary?month= Aggregate tuning hours and total performances.
GET /license Licensee, expiry and station count.

Station fields#

Field Notes
id Required on create. 1 to 64 characters of a-z, 0-9, - and _, starting with a letter or digit. Cannot change.
mount Defaults to /{id}. Letters, digits, ., _, ~, - and /. Cannot change.
source_password Required on create. At least 8 characters, and must not contain :#.
source_username Defaults to source.
name Display name.
max_listeners Concurrent listeners, or null for no limit.
max_bitrate Highest source bitrate in kbps, or null. A source that declares or sends more is refused or disconnected.
monthly_transfer_bytes Listener traffic per calendar month, or null. When it is used up, listeners are disconnected and new ones refused until the next month or a higher quota.
suspended true refuses the source and listeners.
hidden true leaves the station off public status pages and the public JSON API.
dashboard_password Turns on the customer's dashboard login, with the station id as the username. At least 8 characters; null turns the login off. Stored as a bcrypt hash and never returned: responses show dashboard_login: true or false instead.

To change id or mount, delete the station and create it again.

A mount cannot be one of the paths the server answers itself, or start with them: /admin, /api, /metrics, /status, /stats, /statistics, /7.html, /currentsong, /played, /stream and /;. It also cannot be a mount already set under mounts in the configuration file.

Create a station#

curl -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"id":"rockfm","name":"Rock FM","source_password":"s3cret-pass","max_listeners":100,"max_bitrate":128,"monthly_transfer_bytes":107374182400}' \
  https://radio.example/api/hosting/v1/stations
{
  "id": "rockfm",
  "mount": "/rockfm",
  "name": "Rock FM",
  "listen_url": "https://radio.example/rockfm",
  "source_username": "source",
  "source_password": "s3cret-pass",
  "max_listeners": 100,
  "max_bitrate": 128,
  "monthly_transfer_bytes": 107374182400,
  "suspended": false,
  "hidden": false,
  "created_at": "2026-11-13T09:30:00Z",
  "updated_at": "2026-11-13T09:30:00Z",
  "status": {
    "live": false,
    "listeners": 0,
    "bitrate": null,
    "song": null
  }
}

listen_url is built from public_url. The customer points an Icecast-compatible encoder at the server with mount /rockfm, username source and their password. GET /stations returns {"stations": [...]} with one object like this per station.

Change a station#

Send only the fields you want to change:

curl -X PATCH -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"max_listeners":250,"monthly_transfer_bytes":null}' \
  https://radio.example/api/hosting/v1/stations/rockfm

New limits apply straight away. Lowering max_bitrate below what the live source sends disconnects the source.

Suspend and delete#

curl -X POST -H "Authorization: Bearer $TOKEN" https://radio.example/api/hosting/v1/stations/rockfm/suspend
curl -X POST -H "Authorization: Bearer $TOKEN" https://radio.example/api/hosting/v1/stations/rockfm/unsuspend
curl -X DELETE -H "Authorization: Bearer $TOKEN" https://radio.example/api/hosting/v1/stations/rockfm

Suspending disconnects the source and every listener, and refuses new ones until you unsuspend. Deleting disconnects them and removes the station.

Usage#

curl -H "Authorization: Bearer $TOKEN" 'https://radio.example/api/hosting/v1/stations/rockfm/usage?month=2026-11'
{
  "station": "rockfm",
  "month": "2026-11",
  "bytes_sent": 52428800000,
  "listener_hours": 1820.5,
  "sessions": 4210,
  "peak_listeners": 87,
  "monthly_transfer_bytes": 107374182400,
  "over_quota": false
}

GET /usage returns {"month": "2026-11", "stations": [...]} with one object like this per station. Usage is sampled every meter_interval seconds. over_quota is only ever true for the current month.

Reports#

The CSV endpoints return the raw monthly files as a download; the summary returns:

{
  "station": "rockfm",
  "month": "2026-11",
  "summary": {
    "sessions": 4210,
    "aggregate_tuning_hours": 1820.5,
    "plays": 3150,
    "total_performances": 61240
  }
}

See Metrics and royalty reports for the CSV columns.

License#

curl -H "Authorization: Bearer $TOKEN" https://radio.example/api/hosting/v1/license
{
  "licensee": "Example Hosting AB",
  "expires_at": "2026-12-16T00:00:00Z",
  "expired": false,
  "lapsed": false,
  "max_stations": 100,
  "stations": 12
}

Status codes#

Code When
200, 201, 204 Success.
400 The body is not a JSON object, or a field is missing or not valid. The error names the field.
401 The bearer token is missing or wrong.
403 The license allows no more stations, or the license has lapsed and the API is read-only. See Licensing.
404 No such station or path.
405 The method is not allowed on this path.
409 A station with that id or mount already exists, or the mount is set in the configuration file.
413 The body is larger than 64 KiB.
415 The body's Content-Type is not application/json.