Artist IDs Dsp Availabilities

Manage artist identifications on streaming platforms (Spotify, Apple Music, Facebook, YouTube)

Resource Overview

Artist DSP Availabilities link artists to their profiles on Digital Service Providers (DSPs) like Spotify, Apple Music, Facebook, and YouTube. This enables proper artist identification and content matching across platforms.

Base Endpoint
/artist-dsp-availabilities
Resource Type
artist-dsp-availabilities
User Scope
Owner-restricted

Allowed DSPs

Artist identification is only allowed for the following platforms:

DSP ID external-artist-id Format external-artist-url Format
Spotify 1 spotify:artist:{id} https://open.spotify.com/artist/{id}
Apple Music 4 Numeric ID https://music.apple.com/artist/{id}
Facebook 12 Numeric ID https://www.facebook.com/{id}
YouTube 3 Channel ID, @handle or channel URL (stored as the channel ID) Built by the API: https://www.youtube.com/channel/{id}

Automatic Facebook Library Replication

When you create, update, or delete a Facebook (DSP 12) identification, the system automatically replicates the action to Facebook Library (DSP 16). You only need to manage the Facebook entry.

Schema

Required Attributes

Field Type Validation Description
external-artist-id string Required · up to 500 characters · DSP-specific format Artist identifier on the DSP platform
external-artist-url string Required · valid URL · DSP-specific format · ignored and stored as null with Spotify NEW · not used for YouTube: built from the channel ID, any value sent is ignored Artist profile URL on the DSP platform

Read-only Attributes

Field Type Description
id string Unique identifier
created-at datetime Creation timestamp
updated-at datetime Last update timestamp
external-artist-name string | null Artist name on the DSP. For YouTube, the channel title YouTube returns. A value sent in a request is ignored

Relationships

Relationship Related Resource Description Required
artist artists The artist this identification belongs to Yes
dsp dsps The DSP platform (Spotify, Apple, Facebook, YouTube). An identification cannot be moved to or from YouTube Yes

Validation Rules by DSP

S

Spotify (DSP 1)

external-artist-id
spotify:artist:{alphanumeric, max 30 chars}
external-artist-url
https://open.spotify.com/artist/{id}
Example: spotify:artist:4q3ewBCX7sLwd24euuV69X
Brand-new artist: NEW

For an artist with no Spotify profile yet, send external-artist-id as exactly NEW (uppercase). The URL is not required: it is stored as null, even when one is sent. NEW is replaced with the real Spotify ID once it is available.

An artist can be marked as NEW only when:

  • it has no Spotify profile linked, and
  • it does not appear, in any role, on a release that was already sent.

Updating a row that already holds NEW to NEW again is always accepted. Reads may return "external-artist-id": "NEW" with "external-artist-url": null.

Y

YouTube (DSP 3)

external-artist-id

Any of:

  • the channel ID: UC followed by 22 characters
  • the channel's handle: @handle
  • a channel URL: https://www.youtube.com/channel/{id}, https://www.youtube.com/@handle or https://www.youtube.com/user/{name}, also on youtube.com, m.youtube.com and music.youtube.com

Not accepted: video, Shorts, playlist, embed or live links, youtu.be links, and custom URLs such as https://www.youtube.com/c/{name} (send the channel's @handle instead).

external-artist-url

Do not send it. The API stores https://www.youtube.com/channel/{id}; any value sent is ignored.

Checked on YouTube

Before saving, the API looks the channel up on YouTube. It stores the channel ID YouTube returns (never the handle or the URL you sent) and the channel title as external-artist-name. A PATCH checks the channel only when it sends external-artist-id.

Rate limit

30 YouTube lookups per minute per user. Above that, 429 Too Many Requests.

Examples: UCuAXFkgsw1L7xaCfnd5JJOw, @CafeTacvba, https://www.youtube.com/@CafeTacvba
A

Apple Music (DSP 4)

external-artist-id
Numeric only
external-artist-url
https://music.apple.com/artist/{id}
Example: 1126808565
F

Facebook (DSP 12)

external-artist-id
Numeric only
external-artist-url
https://www.facebook.com/{id}
Example: 112233445566778899

List Artist DSP Availabilities

GET /artist-dsp-availabilities 
GET /artist-dsp-availabilities
Authorization: Bearer {token}
Accept: application/vnd.api+json

Query Parameters

Filtering

  • filter[id] - Filter by ID(s)
  • filter[artist-id] - Filter by artist
  • filter[dsp-id] - Filter by DSP

Other Parameters

  • include=artist - Include artist data
  • include=dsp - Include DSP data
  • include=artist,dsp - Include both
  • sort - Sort by field

Success Response

200 OK 
{
  "data": [
    {
      "type": "artist-dsp-availabilities",
      "id": "1",
      "attributes": {
        "external-artist-id": "spotify:artist:4q3ewBCX7sLwd24euuV69X",
        "external-artist-url": "https://open.spotify.com/artist/4q3ewBCX7sLwd24euuV69X",
        "created-at": "2024-01-01T10:00:00Z",
        "updated-at": "2024-01-01T10:00:00Z"
      },
      "relationships": {
        "artist": {
          "links": { "related": "/artist-dsp-availabilities/1/artist" }
        },
        "dsp": {
          "links": { "related": "/artist-dsp-availabilities/1/dsp" }
        }
      }
    }
  ]
}

Create Artist DSP Availability

POST /artist-dsp-availabilities

Spotify Example

{
  "data": {
    "type": "artist-dsp-availabilities",
    "attributes": {
      "external-artist-id": "spotify:artist:4q3ewBCX7sLwd24euuV69X",
      "external-artist-url": "https://open.spotify.com/artist/4q3ewBCX7sLwd24euuV69X"
    },
    "relationships": {
      "artist": {
        "data": { "type": "artists", "id": "123" }
      },
      "dsp": {
        "data": { "type": "dsps", "id": "1" }
      }
    }
  }
}

Spotify Example: brand-new artist

POST /artist-dsp-availabilities
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "artist-dsp-availabilities",
    "attributes": {
      "external-artist-id": "NEW"
    },
    "relationships": {
      "artist": {
        "data": { "type": "artists", "id": "123" }
      },
      "dsp": {
        "data": { "type": "dsps", "id": "1" }
      }
    }
  }
}

The created resource answers "external-artist-id": "NEW" and "external-artist-url": null.

Apple Music Example

{
  "data": {
    "type": "artist-dsp-availabilities",
    "attributes": {
      "external-artist-id": "1126808565",
      "external-artist-url": "https://music.apple.com/artist/1126808565"
    },
    "relationships": {
      "artist": {
        "data": { "type": "artists", "id": "123" }
      },
      "dsp": {
        "data": { "type": "dsps", "id": "4" }
      }
    }
  }
}

Facebook Example

{
  "data": {
    "type": "artist-dsp-availabilities",
    "attributes": {
      "external-artist-id": "112233445566778899",
      "external-artist-url": "https://www.facebook.com/112233445566778899"
    },
    "relationships": {
      "artist": {
        "data": { "type": "artists", "id": "123" }
      },
      "dsp": {
        "data": { "type": "dsps", "id": "12" }
      }
    }
  }
}

YouTube Example

{
  "data": {
    "type": "artist-dsp-availabilities",
    "attributes": {
      "external-artist-id": "@CafeTacvba"
    },
    "relationships": {
      "artist": {
        "data": { "type": "artists", "id": "123" }
      },
      "dsp": {
        "data": { "type": "dsps", "id": "3" }
      }
    }
  }
}

The created resource answers the channel as YouTube returns it:

"attributes": {
  "external-artist-id": "UCuAXFkgsw1L7xaCfnd5JJOw",
  "external-artist-url": "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw",
  "external-artist-name": "Café Tacvba",
  ...
}

Success Response

201 Created

Update Artist DSP Availability

PATCH /artist-dsp-availabilities/{id} 
{
  "data": {
    "type": "artist-dsp-availabilities",
    "id": "1",
    "attributes": {
      "external-artist-id": "spotify:artist:6vWDO969PvNqNYHIOW5v0m",
      "external-artist-url": "https://open.spotify.com/artist/6vWDO969PvNqNYHIOW5v0m"
    }
  }
}

Success Response

200 OK

Delete Artist DSP Availability

DELETE /artist-dsp-availabilities/{id} 
DELETE /artist-dsp-availabilities/1
Authorization: Bearer {token}

Success Response

204 No Content

Error Responses

DSP Not Allowed

422 Unprocessable Entity 
{
  "errors": [{
    "detail": "Artist identification is only allowed for Spotify, Apple, Facebook, and YouTube.",
    "status": "422"
  }]
}

Invalid Spotify ID Format

422 Unprocessable Entity 
{
  "errors": [{
    "detail": "Spotify artist ID must be in format: spotify:artist:{id} where id is alphanumeric (max 30 characters).",
    "status": "422"
  }]
}

Spotify NEW: Profile Already Linked

422 Unprocessable Entity 
{
  "errors": [{
    "detail": "This artist already has a Spotify profile linked, so they are not new on Spotify. Keep their Spotify profile link instead of marking them as new.",
    "source": { "pointer": "/data/attributes/external-artist-id" },
    "status": "422"
  }]
}

Spotify NEW: Already on a Sent Release

422 Unprocessable Entity 
{
  "errors": [{
    "detail": "This artist already appears on a release sent to distribution, so they are not new on Spotify. Paste their Spotify profile link instead of marking them as new.",
    "source": { "pointer": "/data/attributes/external-artist-id" },
    "status": "422"
  }]
}

YouTube: Not a Channel

422 Unprocessable Entity 
{
  "errors": [{
    "detail": "That is a video link, not a channel.",
    "source": { "pointer": "/data/attributes/external-artist-id" },
    "status": "422"
  }]
}

Other detail values: That is not a YouTube link., That is not a YouTube channel., That is a video or playlist link, not a channel., Links with /c/ cannot be validated. Use the channel's @handle.

YouTube: Channel Not Found

422 Unprocessable Entity 
{
  "errors": [{
    "detail": "No YouTube channel was found for that link or handle.",
    "source": { "pointer": "/data/attributes/external-artist-id" },
    "status": "422"
  }]
}

YouTube: DSP Cannot Change

422 Unprocessable Entity 
{
  "errors": [{
    "detail": "An identification cannot be moved to or from YouTube. Delete it and create a new one.",
    "source": { "pointer": "/data/relationships/dsp" },
    "status": "422"
  }]
}

YouTube: Too Many Lookups

429 Too Many Requests

More than 30 YouTube lookups in a minute. The Retry-After header gives the seconds to wait.

YouTube: Unreachable

503 Service Unavailable 
{
  "errors": [{
    "detail": "YouTube could not be reached. Try again later.",
    "status": "503"
  }]
}

Nothing is saved. Retry the same request later.

Invalid Apple/Facebook ID Format

422 Unprocessable Entity 
{
  "errors": [{
    "detail": "Apple artist ID must be numeric.",
    "status": "422"
  }]
}

URL Does Not Match ID

422 Unprocessable Entity 
{
  "errors": [{
    "detail": "Spotify artist URL must be: https://open.spotify.com/artist/4q3ewBCX7sLwd24euuV69X",
    "status": "422"
  }]
}

Duplicate Entry

422 Unprocessable Entity 
{
  "errors": [{
    "detail": "This artist already has an identification for this DSP. Use PATCH to update it.",
    "status": "422"
  }]
}

Unauthorized Access

403 Forbidden 
{
  "errors": [{
    "detail": "You are not authorized to perform this action.",
    "status": "403"
  }]
}