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, andtls_portif set). Serve it over TLS. - Every request needs
Authorization: Bearer <api_token>, thehosting.api_tokenfrom your configuration. Without it the API answers401. - Request bodies are JSON objects with
Content-Type: application/json, at most 64 KiB. - Errors are JSON:
{"error": "..."}. - Months are
YYYY-MMin UTC. Wheremonthis 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. |