Artist

An artist is a musical artist linked to products and tracks. Artists carry per-DSP identification data used to generate DDEX XML. This resource supports full CRUD. The main relationship is dsp-identifications (per-DSP artist IDs).

---

Lists Artists

GET https://domain.com/api/v1/artists

Headers

Name	Type	Description
Authorization*	String	Bearer \
Content-Type*	String	application/vnd.api+json

Response — 200 OK

{
  "data": [
    {
      "type": "artists",
      "id": "<ID>",
      "attributes": {
        "name": "Bad Bunny",
        "external-user-id": "user_12345",
        "apple-id": "1126808565",
        "created-at": "2024-12-15T10:30:00.000000Z",
        "updated-at": "2024-12-15T10:30:00.000000Z"
      },
      "relationships": {
        "dsp-identifications": {
          "links": {
            "related": "https://domain.com/api/v1/artists/<ID>/dsp-identifications",
            "self": "https://domain.com/api/v1/artists/<ID>/relationships/dsp-identifications"
          }
        }
      },
      "links": {
        "self": "https://domain.com/api/v1/artists/<ID>"
      }
    }
  ],
  "meta": {
    "page": {
      "currentPage": 1,
      "from": 1,
      "lastPage": 8,
      "perPage": 20,
      "to": 1,
      "total": 150
    }
  },
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "first": "https://domain.com/api/v1/artists?page[number]=1&page[size]=20",
    "last": "https://domain.com/api/v1/artists?page[number]=8&page[size]=20",
    "next": "https://domain.com/api/v1/artists?page[number]=2&page[size]=20"
  }
}

Filters

Filter	Example
Name	/artists?filter[name]=Bad Bunny
External user ID	/artists?filter[external-user-id]=user_12345
ID	/artists?filter[id]=1,2,3

---

Get Artist

GET https://domain.com/api/v1/artists/:id

Path Parameters

Name	Type	Description
id*	Number	Artist ID

Headers

Name	Type	Description
Authorization*	String	Bearer \
Content-Type*	String	application/vnd.api+json

Response — 200 OK

{
  "data": {
    "type": "artists",
    "id": "<ID>",
    "attributes": {
      "name": "Bad Bunny",
      "external-user-id": "user_12345",
      "apple-id": "1126808565",
      "created-at": "2024-12-15T10:30:00.000000Z",
      "updated-at": "2024-12-15T10:30:00.000000Z"
    },
    "relationships": {
      "dsp-identifications": {
        "links": {
          "related": "https://domain.com/api/v1/artists/<ID>/dsp-identifications",
          "self": "https://domain.com/api/v1/artists/<ID>/relationships/dsp-identifications"
        }
      }
    },
    "links": {
      "self": "https://domain.com/api/v1/artists/<ID>"
    }
  },
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "https://domain.com/api/v1/artists/<ID>"
  }
}

Response — 404 Not Found

{
  "jsonapi": {
    "version": "1.0"
  },
  "errors": [
    {
      "status": "404",
      "title": "Not Found"
    }
  ]
}

---

Create Artist

POST https://domain.com/api/v1/artists

Headers

Name	Type	Description
Authorization*	String	Bearer \
Content-Type*	String	application/vnd.api+json

Request Body

Name	Required	Type	Description
name	Yes	String	Artist display name
external-user-id	No	String	External user identifier

Response — 201 Created

{
  "data": {
    "type": "artists",
    "id": "<ID>",
    "attributes": {
      "name": "Shakira",
      "external-user-id": "user_98765",
      "apple-id": null,
      "created-at": "2025-05-27T12:00:00.000000Z",
      "updated-at": "2025-05-27T12:00:00.000000Z"
    },
    "relationships": {
      "dsp-identifications": {
        "links": {
          "related": "https://domain.com/api/v1/artists/<ID>/dsp-identifications",
          "self": "https://domain.com/api/v1/artists/<ID>/relationships/dsp-identifications"
        }
      }
    },
    "links": {
      "self": "https://domain.com/api/v1/artists/<ID>"
    }
  },
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "https://domain.com/api/v1/artists/<ID>"
  }
}

Response — 422 Unprocessable Entity

{
  "jsonapi": {
    "version": "1.0"
  },
  "errors": [
    {
      "detail": "The name field is required.",
      "source": {
        "pointer": "/data/attributes/name"
      },
      "status": "422",
      "title": "Unprocessable Entity"
    }
  ]
}

---

Update Artist

PATCH https://domain.com/api/v1/artists/:id

Path Parameters

Name	Type	Description
id*	Number	Artist ID

Headers

Name	Type	Description
Authorization*	String	Bearer \
Content-Type*	String	application/vnd.api+json

Request Body

All fields are optional on PATCH; omitted attributes keep their current values.

Name	Required	Type	Description
name	No	String	Artist display name
external-user-id	No	String	External user identifier

Response — 200 OK

{
  "data": {
    "type": "artists",
    "id": "<ID>",
    "attributes": {
      "name": "Bad Bunny",
      "external-user-id": "user_12345",
      "apple-id": "1126808565",
      "created-at": "2024-12-15T10:30:00.000000Z",
      "updated-at": "2025-05-27T12:00:00.000000Z"
    },
    "relationships": {
      "dsp-identifications": {
        "links": {
          "related": "https://domain.com/api/v1/artists/<ID>/dsp-identifications",
          "self": "https://domain.com/api/v1/artists/<ID>/relationships/dsp-identifications"
        }
      }
    },
    "links": {
      "self": "https://domain.com/api/v1/artists/<ID>"
    }
  },
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "https://domain.com/api/v1/artists/<ID>"
  }
}

---

Delete Artist

DELETE https://domain.com/api/v1/artists/:id

Path Parameters

Name	Type	Description
id*	Number	Artist ID

Headers

Name	Type	Description
Authorization*	String	Bearer \
Content-Type*	String	application/vnd.api+json

Response — 204 No Content (delete OK, empty body)

Response — 404 Not Found

{
  "jsonapi": {
    "version": "1.0"
  },
  "errors": [
    {
      "status": "404",
      "title": "Not Found"
    }
  ]
}