🎭 Album Artists

Relationships between artists and albums with specific roles and credits

Resource Overview

Album Artists represent the many-to-many relationships between albums and artists, including specific roles such as main artist, featured artist, producer, or composer. This pivot resource manages all contributor credits for albums.

Base Endpoint
/album-artists
Resource Type
album-artists
User Scope
Album owner-restricted

Schema

Required Relationships

Relationship Type Related Resource Description
album BelongsTo albums Album to associate artist with
artist BelongsTo artists Artist to associate with album
artist-role BelongsTo artist-roles Role of artist in album (Main Artist, Producer, etc.)

Optional Attributes

Field Type Validation Description
order integer nullable, min:1, unique per album Artist display order within album

Read-only Attributes

Field Type Description
id string Unique identifier
album-id integer ID of the associated album
album-name string Title of the associated album
artist-id integer ID of the associated artist
artist-name string Name of the associated artist
artist-role-id integer ID of the associated artist role
role-key string Key identifier of the artist role (e.g., "main_artist", "featured")

Business Validations

  • • Unique combination: Same artist cannot have same role twice in same album
  • • Album ownership: Can only associate artists with albums you own
  • • Order uniqueness: Order position must be unique within the album
  • • Authentication required: Must be logged in to create/modify associations

List Album Artists

GET /album-artists 
GET /album-artists
Authorization: Bearer {token}
Accept: application/vnd.api+json

Query Parameters

Filtering

  • • filter[album] - Filter by album ID
  • • filter[artist] - Filter by artist ID
  • • filter[artist-role] - Filter by artist role ID

Other Parameters

  • • include - Include relationships
  • • sort - Sort by field
  • • page[number] - Page number
  • • page[size] - Results per page

Example Request

GET /album-artists?include=album,artist,artist-role&filter[album]=1

Success Response

200 OK 
{
  "data": [
    {
      "type": "album-artists",
      "id": "1",
      "attributes": {
        "order": 1,
        "album-id": 1,
        "album-name": "Electric Dreams",
        "artist-id": 5,
        "artist-name": "Alex Digital",
        "artist-role-id": 1,
        "role-key": "main_artist"
      },
      "relationships": {
        "album": {
          "data": { "type": "albums", "id": "1" }
        },
        "artist": {
          "data": { "type": "artists", "id": "5" }
        },
        "artist-role": {
          "data": { "type": "artist-roles", "id": "1" }
        }
      }
    },
    {
      "type": "album-artists",
      "id": "2",
      "attributes": {
        "order": 2,
        "album-id": 1,
        "album-name": "Electric Dreams",
        "artist-id": 8,
        "artist-name": "Sarah Vocals",
        "artist-role-id": 2,
        "role-key": "featured"
      },
      "relationships": {
        "album": {
          "data": { "type": "albums", "id": "1" }
        },
        "artist": {
          "data": { "type": "artists", "id": "8" }
        },
        "artist-role": {
          "data": { "type": "artist-roles", "id": "2" }
        }
      }
    }
  ],
  "included": [
    {
      "type": "albums",
      "id": "1",
      "attributes": {
        "title": "Electric Dreams",
        "artwork": "https://storage.example.com/artwork/electric-dreams.jpg"
      }
    },
    {
      "type": "artists",
      "id": "5",
      "attributes": {
        "name": "Alex Digital",
        "bio": "Electronic music producer and songwriter"
      }
    },
    {
      "type": "artists",
      "id": "8",
      "attributes": {
        "name": "Sarah Vocals",
        "bio": "Professional vocalist and songwriter"
      }
    },
    {
      "type": "artist-roles",
      "id": "1",
      "attributes": {
        "name": "Main Artist",
        "key": "main_artist"
      }
    },
    {
      "type": "artist-roles",
      "id": "2",
      "attributes": {
        "name": "Featured Artist",
        "key": "featured"
      }
    }
  ],
  "meta": {
    "page": {
      "current-page": 1,
      "per-page": 20,
      "total": 2,
      "last-page": 1
    }
  }
}

Create Album Artist

POST /album-artists

Request Body

{
  "data": {
    "type": "album-artists",
    "attributes": {
      "order": 1
    },
    "relationships": {
      "album": {
        "data": {
          "type": "albums",
          "id": "1"
        }
      },
      "artist": {
        "data": {
          "type": "artists",
          "id": "5"
        }
      },
      "artist-role": {
        "data": {
          "type": "artist-roles",
          "id": "1"
        }
      }
    }
  }
}

Required Fields

Relationships
  • • album - Album to associate artist with (must own album)
  • • artist - Artist to associate with album
  • • artist-role - Role of artist in album
Optional Attributes
  • • order - Display order (min:1, unique per album)

Success Response

201 Created 
{
  "data": {
    "type": "album-artists",
    "id": "15",
    "attributes": {
      "order": 1,
      "album-id": 1,
      "album-name": "Electric Dreams",
      "artist-id": 5,
      "artist-name": "Alex Digital",
      "artist-role-id": 1,
      "role-key": "main_artist"
    },
    "relationships": {
      "album": {
        "data": { "type": "albums", "id": "1" }
      },
      "artist": {
        "data": { "type": "artists", "id": "5" }
      },
      "artist-role": {
        "data": { "type": "artist-roles", "id": "1" }
      }
    }
  }
}

Update Album Artist

PATCH /album-artists/{id}

Request Body Example - Update Order

{
  "data": {
    "type": "album-artists",
    "id": "1",
    "attributes": {
      "order": 3
    }
  }
}

Success Response

200 OK 
{
  "data": {
    "type": "album-artists",
    "id": "1",
    "attributes": {
      "order": 3,
      "album-id": 1,
      "album-name": "Electric Dreams",
      "artist-id": 5,
      "artist-name": "Alex Digital",
      "artist-role-id": 1,
      "role-key": "main_artist"
    },
    "relationships": {
      "album": {
        "data": { "type": "albums", "id": "1" }
      },
      "artist": {
        "data": { "type": "artists", "id": "5" }
      },
      "artist-role": {
        "data": { "type": "artist-roles", "id": "1" }
      }
    }
  }
}

Delete Album Artist

DELETE /album-artists/{id} 
DELETE /album-artists/1
Authorization: Bearer {token}

⚠️ Important Notes

  • • Removing album-artist associations is permanent
  • • Can only delete associations from albums you own
  • • Order positions will be adjusted automatically
  • • Artist and album resources remain unchanged

Success Response

204 No Content

Resource Overview

📊 Key Statistics

  • • Manages album-artist associations
  • • Supports role-based relationships
  • • Maintains order positioning
  • • Prevents duplicate combinations

✨ Key Features

  • • Role assignment per artist
  • • Flexible ordering system
  • • Automatic validation
  • • Full CRUD operations

🔗 Relationships

  • • Links albums to artists
  • • Assigns specific roles
  • • Maintains credits order
  • • Supports collaboration
Previous: Tracks Next: Album Tracks