Recoup

Get started with Recoup.

Try Our Platform

Use Recoup’s AI tools for your artists, releases, and catalog.

Build Your Platform

Our team builds custom AI software for your business.

API REFERENCE

Acquire or resume a registered player session

On this page
POST/api/players/public/{id}/session

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.

Authentication

This endpoint does not require authentication.

Request

cURL
curl --request POST \
  --url 'https://api.recoupable.dev/api/players/public/YOUR_ID/session' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "spotify",
  "parent": "string"
}'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

cURL for this request
curl --request POST \
  --url 'https://recoup-api.vercel.app/api/players/public/{id}/session' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "spotify",
  "parent": "string"
}'

Parameters

Path parameters

idstringrequired

Request body required

application/json

providerstring · enumrequired

Values: "spotify", "apple_music"

parentstringrequired

minLength: 1

flowstring
sourcestring

maxLength: 100

mediumstring

maxLength: 100

campaignstring

maxLength: 100

contentstring

maxLength: 100

Responses

200PublicPlayerConfig fields returned by the release player service.

application/json

playerIdstringrequired

format: uuid

namestringrequired
artworkstring | null

format: uri

spotifyUrlstring | nullrequired

format: uri

appleUrlstring | nullrequired

format: uri

revisionintegerrequired

minimum: 1

providerstring · enum

Values: "spotify", "apple_music"

releasestring

format: uri

sessionIdstring

format: uuid

flowstring

Short-lived signed player capability; only the trusted Recoup player should handle this.

spotifyobject
Properties for spotify
configuredbooleanrequired
clientIdstring | nullrequired
redirectUristringrequired

format: uri

scopesarray<string>required
Item properties for scopes

string

freePlaybackstring · enumrequired

Release-owner choice for verified Spotify Free accounts. spotify opens the configured Spotify release; audio plays a workspace-owned uploaded file. Premium continues using Spotify streaming.

Values: "spotify", "audio"

Default: "spotify"

audioUrlstring | null

Included only in provider-session responses. Configured uploaded audio is provided for Spotify sessions in audio mode; otherwise null. Not included in chooser metadata.

format: uri

400Invalid input

application/json

errorstringrequired
statusstring
401Missing/invalid authentication or failed provider authorization

application/json

errorstringrequired
statusstring
403Workspace, origin, or session access denied

application/json

errorstringrequired
statusstring
404Player not available

application/json

errorstringrequired
statusstring
429Request rate limit exceeded

application/json

errorstringrequired
statusstring
503Feature/configuration temporarily unavailable

application/json

errorstringrequired
statusstring

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download players.json
View operation source
json
{
  "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.",
  "security": [],
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "PublicPlayerConfig fields returned by the release player service.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PublicPlayerConfig"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PlayerError"
          }
        }
      }
    },
    "401": {
      "description": "Missing/invalid authentication or failed provider authorization",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PlayerError"
          }
        }
      }
    },
    "403": {
      "description": "Workspace, origin, or session access denied",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PlayerError"
          }
        }
      }
    },
    "404": {
      "description": "Player not available",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PlayerError"
          }
        }
      }
    },
    "429": {
      "description": "Request rate limit exceeded",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PlayerError"
          }
        }
      }
    },
    "503": {
      "description": "Feature/configuration temporarily unavailable",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PlayerError"
          }
        }
      }
    }
  },
  "operationId": "acquirePlayerSession",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "provider": {
              "type": "string",
              "enum": [
                "spotify",
                "apple_music"
              ]
            },
            "parent": {
              "type": "string",
              "minLength": 1
            },
            "flow": {
              "type": "string"
            },
            "source": {
              "type": "string",
              "maxLength": 100
            },
            "medium": {
              "type": "string",
              "maxLength": 100
            },
            "campaign": {
              "type": "string",
              "maxLength": 100
            },
            "content": {
              "type": "string",
              "maxLength": 100
            }
          },
          "required": [
            "provider",
            "parent"
          ],
          "additionalProperties": false
        }
      }
    }
  }
}