Capabilities
Recommend
This API does not stream third-party radio audio. Deterministic ranking: supplied favourite +10, each matched genre +3, country +4, language +2; ties by name then stable ID. Maximum 12 results. play_now requires signed territory and current direct approval. No history or sponsor affects ranking.
How this capability is exposed
- Stable ID
ursy.fm:recommend- Owning service
- URSY.fm
- Runtime
- See the source declaration
Capability declarations describe what the service exposes. They are not a guarantee of availability or permission to execute an operation.
Accepted contract
{
"id": "ursy.fm:recommend",
"description": "This API does not stream third-party radio audio. Deterministic ranking: supplied favourite +10, each matched genre +3, country +4, language +2; ties by name then stable ID. Maximum 12 results. play_now requires signed territory and current direct approval. No history or sponsor affects ranking.",
"operationId": "recommendStations",
"rest": {
"method": "POST",
"path": "/recommend"
},
"mcp_tool": "recommend_station",
"input_schema": {
"type": "object",
"properties": {
"country": {
"type": "string",
"pattern": "^[A-Z]{2}$"
},
"favourites": {
"type": "array",
"maxItems": 200,
"items": {
"type": "string",
"pattern": "^stn_[a-z0-9]{16,64}$"
}
},
"genres": {
"type": "array",
"maxItems": 30,
"items": {
"type": "string",
"maxLength": 200
}
},
"language": {
"type": "string",
"maxLength": 200
},
"play_now": {
"type": "boolean"
}
},
"additionalProperties": false,
"required": []
},
"output_schema": {
"type": "object",
"required": [
"recommendations"
],
"properties": {
"recommendations": {
"type": "array",
"maxItems": 12,
"items": {
"type": "object",
"required": [
"station",
"playback",
"score",
"explanation"
],
"properties": {
"station": {
"type": "object",
"required": [
"schema",
"id",
"name",
"station_country",
"official",
"playback"
],
"properties": {
"schema": {
"const": "ursy.fm/station/v3"
},
"id": {
"type": "string",
"pattern": "^stn_[a-z0-9]{16,64}$"
},
"name": {
"type": "string"
},
"station_country": {
"type": [
"string",
"null"
]
},
"languages": {
"type": "array",
"items": {
"type": "string"
}
},
"genres": {
"type": "array",
"items": {
"type": "string"
}
},
"official": {
"type": "object",
"properties": {
"homepage": {
"type": [
"string",
"null"
]
},
"player_url": {
"type": [
"string",
"null"
]
}
}
},
"playback": {
"type": "object",
"required": [
"evaluation_required",
"audio_hosted_by_ursy",
"audio_proxied_by_ursy"
],
"properties": {
"evaluation_required": {
"const": true
},
"audio_hosted_by_ursy": {
"const": false
},
"audio_proxied_by_ursy": {
"const": false
}
}
}
}
},
"playback": {
"type": "object",
"required": [
"state",
"audio_via_ursy"
],
"properties": {
"state": {
"enum": [
"approved_client_direct",
"official_player_only",
"directory_only",
"blocked",
"territory_unknown",
"end_user_territory_required"
]
},
"station_id": {
"type": [
"string",
"null"
]
},
"territory": {
"type": [
"string",
"null"
]
},
"method": {
"enum": [
"official_link",
"client_direct_stream",
"ursy_local_audio"
]
},
"policy_state": {
"enum": [
"approved",
"official_player_only",
"directory_only",
"blocked",
"unknown",
"expired"
]
},
"policy_version": {
"type": "integer"
},
"rights_decision_id": {
"type": [
"string",
"null"
]
},
"audio_via_ursy": {
"const": false
},
"official_player_url": {
"type": [
"string",
"null"
]
},
"authorization_url": {
"type": "string"
},
"handoff_id": {
"type": "string"
},
"grant": {
"type": "string"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"code": {
"type": "string"
},
"handoff": {
"type": "object",
"properties": {
"type": {
"const": "radio_browser"
},
"station_uuid": {
"type": "string",
"format": "uuid"
},
"client_must_resolve": {
"const": true
},
"redemption_required": {
"type": "boolean"
}
}
}
}
},
"score": {
"type": "integer"
},
"explanation": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"territory": {
"type": [
"string",
"null"
]
},
"preferences_stored": {
"const": false
}
}
},
"service_id": "ursy-fm",
"parent_id": "",
"name": "Recommend",
"summary": "This API does not stream third-party radio audio. Deterministic ranking: supplied favourite +10, each matched genre +3, country +4, language +2; ties by name then stable ID. Maximum 12 results. play_now requires signed territory and current direct approval. No history or sponsor affects ranking.",
"source_url": "https://ursy.fm/.well-known/ursy-capabilities.json",
"source_type": "capability_manifest",
"verified_at": "2026-10-14 04:03:32",
"revision": "19b8e557afab3152230ec6958d90168fcf9808f9e1eea37ed162016154c882d2",
"type": "capabilities",
"source": {
"url": "https://ursy.fm/.well-known/ursy-capabilities.json",
"type": "capability_manifest"
},
"last_verified_at": "2026-10-14 04:03:32",
"stale": false
}