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

Create a release player

On this page
POST/api/players

Register one reusable listening page plus provider embeds. Returns player, listenUrl, spotifyEmbedUrl, appleEmbedUrl. MCP: create_release_player. No site generation is required. This feature requires its API/app/database releases.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL
curl --request POST \
  --url 'https://api.recoupable.dev/api/players' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "spotifyUrl": "string"
}'

Try it

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

Kept in this browser tab only and cleared when it closes.

cURL for this request
curl --request POST \
  --url 'https://recoup-api.vercel.app/api/players' \
  --header 'Content-Type: application/json' \
  --data '{
  "spotifyUrl": "string"
}'

Request body required

application/json

organizationIdstring | null

Authorized workspace; omit for the authenticated account. Never send account_id.

format: uuid

artistIdstringrequired

Artist account belonging to this workspace.

format: uuid

namestringrequired

minLength: 1 · maxLength: 120

spotifyUrlstring | null

Spotify track, album, or playlist URL. Share parameters are removed.

format: uri

appleUrlstring | null

Apple Music song or album URL, optionally an album ?i= song selection.

format: uri

artworkstring | null

Optional public HTTPS artwork.

format: uri

allowedOriginsarray<string>

Exact HTTPS origins authorized to embed this player; no path, query, credentials, or fragment.

maxItems: 10

Item properties for allowedOrigins

string

enabledboolean

Publishing requires an active paid workspace. Disabled players are unavailable publicly.

Default: false

freePlaybackstring · enum

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

MP3 or WAV URL returned by POST /api/sites/assets for the same workspace. Requires an existing audio object; arbitrary or other-workspace URLs are rejected. Required when freePlayback is audio. Uploads currently have a 4 MB limit.

format: uri

anyOf · object 1
spotifyUrlstringrequired

format: uri

anyOf · object 2
appleUrlstringrequired

format: uri

Responses

201PlayerResource fields returned by the release player service.

application/json

playerobjectrequired
Properties for player
idstringrequired

format: uuid

owner_idstringrequired

format: uuid

artist_idstringrequired

format: uuid

created_bystring

format: uuid

namestringrequired
spotify_urlstring | nullrequired

format: uri

apple_urlstring | nullrequired

format: uri

artworkstring | null

format: uri

allowed_originsarray<string>required
Item properties for allowed_origins

string

enabledbooleanrequired
revisionintegerrequired

minimum: 1

created_atstring

format: date-time

updated_atstring

format: date-time

free_playbackstring · 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"

audio_urlstring | nullrequired

MP3 or WAV URL returned by POST /api/sites/assets for the same workspace. Requires an existing audio object; arbitrary or other-workspace URLs are rejected. Required when freePlayback is audio. Uploads currently have a 4 MB limit.

format: uri

listenUrlstringrequired

format: uri

spotifyEmbedUrlstringrequired

Stable provider route. This URL is returned even when that provider is unconfigured; inspect the corresponding destination in player before displaying it.

format: uri

appleEmbedUrlstringrequired

Stable provider route. This URL is returned even when that provider is unconfigured; inspect the corresponding destination in player before displaying it.

format: uri

400Invalid input

application/json

errorstringrequired
statusstring
401Missing/invalid authentication or failed provider authorization

application/json

errorstringrequired
statusstring
402Publishing requires an active paid workspace

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": "Create a release player",
  "description": "Register one reusable listening page plus provider embeds. Returns player, listenUrl, spotifyEmbedUrl, appleEmbedUrl. MCP: create_release_player. No site generation is required. This feature requires its API/app/database releases.",
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "parameters": [],
  "responses": {
    "201": {
      "description": "PlayerResource fields returned by the release player service.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PlayerResource"
          }
        }
      }
    },
    "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"
          }
        }
      }
    },
    "402": {
      "description": "Publishing requires an active paid workspace",
      "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"
          }
        }
      }
    }
  },
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "artistId",
            "name"
          ],
          "properties": {
            "organizationId": {
              "type": [
                "string",
                "null"
              ],
              "format": "uuid",
              "description": "Authorized workspace; omit for the authenticated account. Never send account_id."
            },
            "artistId": {
              "type": "string",
              "format": "uuid",
              "description": "Artist account belonging to this workspace."
            },
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            },
            "spotifyUrl": {
              "type": [
                "string",
                "null"
              ],
              "format": "uri",
              "description": "Spotify track, album, or playlist URL. Share parameters are removed."
            },
            "appleUrl": {
              "type": [
                "string",
                "null"
              ],
              "format": "uri",
              "description": "Apple Music song or album URL, optionally an album ?i= song selection."
            },
            "artwork": {
              "type": [
                "string",
                "null"
              ],
              "format": "uri",
              "description": "Optional public HTTPS artwork."
            },
            "allowedOrigins": {
              "type": "array",
              "maxItems": 10,
              "items": {
                "type": "string",
                "format": "uri"
              },
              "description": "Exact HTTPS origins authorized to embed this player; no path, query, credentials, or fragment."
            },
            "enabled": {
              "type": "boolean",
              "default": false,
              "description": "Publishing requires an active paid workspace. Disabled players are unavailable publicly."
            },
            "freePlayback": {
              "type": "string",
              "enum": [
                "spotify",
                "audio"
              ],
              "default": "spotify",
              "description": "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."
            },
            "audioUrl": {
              "type": [
                "string",
                "null"
              ],
              "format": "uri",
              "description": "MP3 or WAV URL returned by POST /api/sites/assets for the same workspace. Requires an existing audio object; arbitrary or other-workspace URLs are rejected. Required when freePlayback is audio. Uploads currently have a 4 MB limit."
            }
          },
          "description": "At least one of spotifyUrl or appleUrl is required. Disabled by default.",
          "anyOf": [
            {
              "required": [
                "spotifyUrl"
              ],
              "properties": {
                "spotifyUrl": {
                  "type": "string",
                  "format": "uri"
                }
              }
            },
            {
              "required": [
                "appleUrl"
              ],
              "properties": {
                "appleUrl": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          ]
        }
      }
    }
  }
}