Playback Handoff

{
    "id": "ursy.fm:playback-handoff",
    "description": "This API does not stream third-party radio audio. Station ID only. Without a valid signed end-user territory assertion, returns END_USER_TERRITORY_REQUIRED and a five-minute browser authorization URL. Agent server location is never used. Approved grants last 120 seconds, allow two redemptions, and bind station, territory, method, rights decision and policy version. No shared caching.",
    "operationId": "requestPlaybackHandoff",
    "rest": {
        "method": "POST",
        "path": "/playback/handoff"
    },
    "mcp_tool": "request_playback_handoff",
    "input_schema": {
        "type": "object",
        "properties": {
            "station_id": {
                "type": "string",
                "pattern": "^stn_[a-z0-9]{16,64}$"
            }
        },
        "additionalProperties": false,
        "required": [
            "station_id"
        ]
    },
    "output_schema": {
        "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"
                    }
                }
            }
        }
    },
    "service_id": "ursy-fm",
    "parent_id": "",
    "name": "Playback Handoff",
    "summary": "This API does not stream third-party radio audio. Station ID only. Without a valid signed end-user territory assertion, returns END_USER_TERRITORY_REQUIRED and a five-minute browser authorization URL. Agent server location is never used. Approved grants last 120 seconds, allow two redemptions, and bind station, territory, method, rights decision and policy version. No shared caching.",
    "source_url": "https://ursy.fm/.well-known/ursy-capabilities.json",
    "source_type": "capability_manifest",
    "verified_at": "2026-10-14 07:03:16",
    "revision": "f566e4dc3912b2d51b1f45d66d18c02fbfb15651ff62d8cfe78940bea031c514",
    "type": "capabilities",
    "source": {
        "url": "https://ursy.fm/.well-known/ursy-capabilities.json",
        "type": "capability_manifest"
    },
    "last_verified_at": "2026-10-14 07:03:16",
    "stale": false
}