Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion content/docs/contracts/operation-inventory.json
Original file line number Diff line number Diff line change
Expand Up @@ -3839,7 +3839,7 @@
"content/docs/source/api-reference/openapi/applications.json": "07cf7c630ca81816d73e9198b863dc0a9c8e987f4e0794375951ead06e498ad6",
"content/docs/source/api-reference/openapi/content.json": "877afed1e0fb5c95afab8c5e294bae38fabdf48f50f226e0089b9ff50438870d",
"content/docs/source/api-reference/openapi/context.json": "10b243ab1098a7428fb935dfb0780ff0f9a1c8885b96feda8e453acff4a1df17",
"content/docs/source/api-reference/openapi/players.json": "4a4c90583fe1de6487444581b293a32b1cc04622fc929965ab90f365feb8bc94",
"content/docs/source/api-reference/openapi/players.json": "eb1ee4cff0c61db4904af8b544b03f290e041577584b52ed32803849109baa17",
"content/docs/source/api-reference/openapi/projects.json": "b059cf8baa83a7f73a3c15db19f54fa56e46a3840e91bd42979b83550f543ace",
"content/docs/source/api-reference/openapi/releases.json": "0e1239e256b2c1f8f189d81e013f942518619a24214b7c2b7f99baad15de7d3c",
"content/docs/source/api-reference/openapi/research.json": "f301a714e994e99b1dbcfc63ee18824537cf42813d8df3906ac7c2436a481ae0",
Expand Down
2 changes: 1 addition & 1 deletion content/docs/manifest.json

Large diffs are not rendered by default.

Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,6 @@
title: "Read public player metadata"
openapi: "/api-reference/openapi/players.json GET /api/players/public/{id}"
---


The optional capabilities v1 configuration projection is pending. See [configuration observations](/api-reference/players/get#pending-configuration-observations) for its unknown-state and compatibility limits.
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,6 @@ title: "Acquire or resume a player session"
openapi: "/api-reference/openapi/players.json POST /api/players/public/{id}/session"
sidebarTitle: "Start or resume player session"
---


The optional capabilities v1 configuration projection is pending. See [configuration observations](/api-reference/players/get#pending-configuration-observations) for its unknown-state and compatibility limits.
92 changes: 88 additions & 4 deletions content/docs/source/api-reference/openapi/players.json
Original file line number Diff line number Diff line change
Expand Up @@ -346,7 +346,7 @@
"get": {
"operationId": "getPlayersById",
"summary": "Read a release player",
"description": "Read settings, revision and share/embed links. MCP: get_release_player.",
"description": "Read settings, revision and share/embed links. MCP: get_release_player. An optional capabilities v1 configuration projection is pending; it contains no fan eligibility or playback authorization.",
"security": [
{
"apiKeyAuth": []
Expand Down Expand Up @@ -384,7 +384,7 @@
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PlayerResource"
"$ref": "#/components/schemas/PlayerReadResource"
}
}
}
Expand Down Expand Up @@ -909,7 +909,7 @@
"get": {
"operationId": "getPlayersPublicById",
"summary": "Read public player metadata without creating a session",
"description": "Internal transport for the trusted Recoup browser player. Without provider, returns only public release settings. With provider, validates parent and creates or resumes a signed, provider-bound listening session. No owner, fan profile or email is exposed. The embedding website should use returned embed URLs rather than calling this API or handling credentials.",
"description": "Internal metadata transport for the trusted Recoup browser player; never creates or resumes a session. A provider is rejected; use POST /api/players/public/{id}/session to acquire a provider session. No owner, fan profile, email or provider credentials are exposed. The optional capabilities v1 projection is pending and reports configuration only. Embedding websites should use the returned embed URLs.",
"security": [],
"parameters": [
{
Expand Down Expand Up @@ -1268,7 +1268,7 @@
"/api/players/public/{id}/session": {
"post": {
"summary": "Acquire or resume a registered player session",
"description": "Internal transport for the trusted Recoup browser player. Without provider, returns only public release settings. With provider, validates parent and creates or resumes a signed, provider-bound listening session. No owner, fan profile or email is exposed. The embedding website should use returned embed URLs rather than calling this API or handling credentials.",
"description": "Internal transport for the trusted Recoup browser player; requires provider and parent. Validates registered configuration and creates or resumes a signed, provider-bound listening session. No owner, fan profile or email is exposed. Existing trusted-player OAuth configuration is unchanged; the optional credential-free capabilities v1 projection is pending and keeps fan observations unknown, including on resumed sessions. Embedding websites should use embed URLs rather than handling credentials.",
"security": [],
"parameters": [
{
Expand Down Expand Up @@ -2043,6 +2043,11 @@
],
"format": "uri",
"description": "Included only in provider-session responses. Configured uploaded audio is provided for Spotify sessions in audio mode; otherwise null. Not included in chooser metadata."
},
"capabilities": {
"$ref": "#/components/schemas/PlayerCapabilitiesV1",
"x-recoup-availability": "pending",
"description": "Pending rollout. Optional for compatibility; absence or an unsupported version retains existing behavior. All fan-specific observations are unknown in v1."
}
},
"required": [
Expand Down Expand Up @@ -2211,6 +2216,85 @@
]
}
}
},
"PlayerCapabilitiesV1": {
"type": "object",
"x-recoup-availability": "pending",
"description": "Pending additive v1 configuration projection for authorized reads and trusted player configuration. No credentials or verified fan observations. Not deployed availability or host sign-in proof.",
"properties": {
"version": {
"type": "integer",
"const": 1
},
"spotify": {
"type": "object",
"properties": {
"clientConfiguration": {
"type": "string",
"enum": [
"configured",
"unconfigured"
],
"description": "Presence of the existing Spotify client ID setting only; not validation of the ID, callback, provider approval or service availability."
},
"releaseConfigured": {
"type": "boolean",
"description": "Whether this player has a Spotify destination; not enablement or admission."
},
"premiumEligibility": {
"type": "string",
"const": "unknown",
"description": "No current fan or browser observation is available in this configuration response. Unknown grants no permission."
},
"tokenStatus": {
"type": "string",
"const": "unknown",
"description": "No current fan or browser observation is available in this configuration response. Unknown grants no permission."
},
"scopeStatus": {
"type": "string",
"const": "unknown",
"description": "No current fan or browser observation is available in this configuration response. Unknown grants no permission."
},
"playbackSupport": {
"type": "string",
"const": "unknown",
"description": "No current fan or browser observation is available in this configuration response. Unknown grants no permission."
}
},
"required": [
"clientConfiguration",
"releaseConfigured",
"premiumEligibility",
"tokenStatus",
"scopeStatus",
"playbackSupport"
],
"additionalProperties": false
}
},
"required": [
"version",
"spotify"
],
"additionalProperties": false
},
"PlayerReadResource": {
"allOf": [
{
"$ref": "#/components/schemas/PlayerResource"
},
{
"type": "object",
"properties": {
"capabilities": {
"$ref": "#/components/schemas/PlayerCapabilitiesV1",
"x-recoup-availability": "pending",
"description": "Pending rollout. Optional for compatibility; absence or an unsupported version retains existing behavior. All fan-specific observations are unknown in v1."
}
}
}
]
}
}
}
Expand Down
6 changes: 6 additions & 0 deletions content/docs/source/api-reference/players/get.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,9 @@
title: "Read a release player"
openapi: "/api-reference/openapi/players.json GET /api/players/{id}"
---

## Pending configuration observations

The optional `capabilities` v1 response is a pending additive contract for `get_release_player`, authorized player GET, and trusted player metadata/session responses. It reports whether a Spotify client ID is configured and whether the player has a Spotify destination. Neither means provider approval, fan eligibility, playback permission or host login. Premium eligibility, token status, scope status and playback support are always `unknown` in this version. No credentials are included.

Clients retain existing behavior when the field is absent or its version is unsupported. The planned chooser uses an explicit unconfigured result to offer Open Spotify; uploaded-audio mode retains an Open player link. This does not claim that either consumer is deployed. GET metadata never creates or resumes a session; provider acquisition requires POST with provider and parent. Existing authorization, session and fallback behavior remains separate.
Loading
Loading