API reference
Base URL: https://fm.puzzofme.com/api/v1
Endpoints
| Endpoint | Purpose |
|---|---|
GET /stations | List stations with optional countryCode, city, state, search, limit, and offset filters |
GET /stations/:id | Retrieve a station by permanent ID or legacy alias |
GET /openapi | Read the public machine-readable specification |
Response format
Abbreviated example with illustrative station data. The stream URL below is a placeholder.
{
"data": [
{
"id": "nr_example",
"name": "Example FM",
"city": "Lagos",
"state": "Lagos",
"countryCode": "NG",
"streamUrl": "https://example.com/live"
}
],
"pagination": {
"total": 1,
"limit": 25,
"offset": 0,
"nextOffset": null
},
"meta": {
"updatedAt": "2026-10-09T10:00:00.000Z",
"stale": false
}
}List responses contain data, pagination, and meta. Detail responses contain data and meta. Station fields include id, name, frequency, city, state, countryCode, streamUrl, website, logo, tags, availability, lastCheckedAt, updatedAt, and listenUrl.
The default country is NG. Pagination defaults to 25 stations and allows up to 100 per request. Location filters match exactly, ignoring case; search uses a substring match. Unknown metadata may be null.
Errors and retries
| Status | What to do |
|---|---|
| 400 | Correct invalid filters or parameters |
| 401 | Check whether the key is valid or has been revoked |
| 404 | Check the requested station ID |
| 429 | Wait for the duration in Retry-After before retrying |
| 503 | Show a temporary-unavailability message and retry later |
Read the API specification and integration demo once deployed. Station inclusion does not guarantee playback. Independent stream-health probes are not implemented; availability is currently reported as unknown.