Albums

The central entity for music distribution. Albums contain tracks and are associated with artists, labels, and distribution metadata.

Resource Overview

Albums are the core resource in the music distribution system. They represent a collection of tracks that can be distributed to various Digital Service Providers (DSPs).

Base Endpoint
/albums
Resource Type
albums
User Scope
Owner-restricted

Schema

Atributos Requeridos

Field Type Description Validations Editable
title string Album title Up to 255 characters ✓
artwork string Artwork file path Up to 500 characters ✓
is-explicit boolean Explicit content flag - ✓
original-release-date date Original release date format: YYYY-MM-DD ✓
digital-release-date date Digital release date format: YYYY-MM-DD ✓
rights-owner-year integer Rights owner year Between 1900 and next year ✓
rights-owner-name string Rights owner name Up to 255 characters ✓

Optional Attributes

Field Type Description Validations Editable
id string Unique identifier auto-generated
description string Album description - ✓
version-description string Version as free text (e.g., "Deluxe Edition"). Takes priority over version relationship — if set, version_id is cleared automatically. Optional · up to 200 characters ✓
is-published boolean Publication status read-only
upc-code string UPC Code (Universal Product Code) Up to 20 characters · unique ✓
copyright string Copyright information auto-generated
publishing string Publishing information auto-generated
grid string GRID identifier Up to 50 characters ✓
catalogue-number string Catalogue number Up to 50 characters ✓
created-at datetime Creation date automatic
updated-at datetime Last update date automatic
label-name string Label name (computed from label relationship) read-only
tracks-count integer Number of tracks in album computed
format-name string Format name (computed from format relationship) read-only
last-status string Current album status read-only
origin string Album creation origin (api, wizard, etc.) automatic

Required Relationships

Important: These relationships are mandatory for album creation.

Relationship Resource Description Editable
label labels Record label ✓
primary-genre genres Primary music genre ✓
language languages Album language ✓
format album-formats Album format (Album, LP, Single, etc.) ✓

Optional Relationships

Relationship Resource Description Editable
user users Album owner (automatically assigned)
secondary-genre genres Secondary music genre ✓
version versions Album version (from predefined list). Alternative to version-description attribute. ✓

Version: two ways to set it

  • • Free text: Use the version-description attribute to enter any version text (e.g., "Deluxe Edition", "Remastered 2024").
  • • Predefined: Use the version relationship to select from the predefined versions list.
  • • If both are sent in the same request, free text takes priority and the version relationship is cleared automatically.
  • • If only the relationship is sent, the version text is auto-populated from the selected version name.

Collection Relationships (Read-only)

Relationship Resource Description
album-tracks album-tracks Track-album relationships with order metadata
album-artists album-artists Artist-album relationships with roles and order
status-changes album-status-changes Status change history
distribution-requests distribution-requests Distribution requests
deliveries deliveries Deliveries to DSPs

Related Endpoints

Endpoint Method Description Documentation
/albums/{id}/trends GET Get performance trends for an album (plays by date, DSP, country) View Trends →

Many-to-Many Relationships (Editable)

Note: These relationships can be managed directly in album creation/updates.

Relationship Resource Description
tracks tracks Tracks that compose the album
artists artists Artists associated with the album
countries countries Distribution countries
dsps dsps Digital service platforms

List Albums

GET /albums 
GET /albums
Authorization: Bearer {token}
Accept: application/vnd.api+json

Query Parameters

Filtering

  • • filter[title] - Filter by album title (partial match)
  • • filter[last-status] - Filter by album status (draft, in_review, approved, delivered, online, etc.)
  • • filter[label] - Filter by label ID
  • • filter[is-explicit] - Filter by explicit content flag (true/false)
  • • filter[user] - Filter by user ID (admin only)
  • • filter[user-name] - Filter by user name (partial match)
  • • filter[label-name] - Filter by label name (partial match)
  • • filter[upc-code] - Filter by UPC code (exact match)
  • • filter[has-tracks] - Filter albums that have at least one track (true/false)
  • • filter[has-artists] - Filter albums that have at least one artist assigned (true/false)
  • • filter[has-album-tracks] - Filter albums with track relationships configured (true/false)
  • • filter[has-distribution-requests] - Filter albums that have distribution requests (true/false)
  • • filter[has-deliveries] - Filter albums that have been delivered to DSPs (true/false)
  • • filter[created-at-gte] - Filter albums created on or after date (YYYY-MM-DD)
  • • filter[created-at-lte] - Filter albums created on or before date (YYYY-MM-DD)

Other Parameters

  • • include - Include related resources
    Available: user, label, primary-genre, secondary-genre, language, format, version, tracks, artists, album-tracks, album-artists, dsps, countries
  • • sort - Sort by field (prefix with - for desc)
    Available: title, created-at, updated-at, digital-release-date, original-release-date
  • • page[number] - Page number (default: 1)
  • • page[size] - Results per page (default: 15, max: 100)

Example Request

GET /albums?include=user,label,primary-genre&filter[is-explicit]=false&sort=-created-at&page[size]=5
Authorization: Bearer {token}
Accept: application/vnd.api+json

Success Response

200 OK 
{
  "meta": {
    "page": {
      "currentPage": 1,
      "from": 1,
      "lastPage": 7,
      "perPage": 5,
      "to": 5,
      "total": 33
    }
  },
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "first": "https://domain.com/api/albums?include=user,label,primary-genre&page[number]=1&page[size]=5",
    "last": "https://domain.com/api/albums?include=user,label,primary-genre&page[number]=7&page[size]=5",
    "next": "https://domain.com/api/albums?include=user,label,primary-genre&page[number]=2&page[size]=5"
  },
  "data": [
    {
      "type": "albums",
      "id": "1234",
      "attributes": {
        "title": "Midnight Dreams",
        "version-description": "Deluxe Edition",
        "description": "A collection of atmospheric tracks exploring themes of night and dreams",
        "label-name": "Indie Records",
        "tracks-count": 8,
        "format-name": "Album",
        "last-status": "draft",
        "is-explicit": false,
        "is-published": false,
        "upc-code": "123456789012",
        "original-release-date": "2024-03-15T00:00:00.000000Z",
        "digital-release-date": "2024-03-15T00:00:00.000000Z",
        "rights-owner-year": 2024,
        "rights-owner-name": "Dream Music Publishing",
        "copyright": "2024 Dream Music Publishing",
        "publishing": "2024 Dream Music Publishing",
        "artwork": "https://example.com/artwork/midnight-dreams.jpg",
        "origin": "api",
        "created-at": "2024-03-10T10:00:00.000000Z",
        "updated-at": "2024-03-15T14:30:00.000000Z"
      },
      "relationships": {
        "user": {
          "links": {
            "related": "https://domain.com/api/albums/1234/user",
            "self": "https://domain.com/api/albums/1234/relationships/user"
          },
          "data": {
            "type": "users",
            "id": "456"
          }
        },
        "label": {
          "links": {
            "related": "https://domain.com/api/albums/1234/label",
            "self": "https://domain.com/api/albums/1234/relationships/label"
          },
          "data": {
            "type": "labels",
            "id": "789"
          }
        },
        "primary-genre": {
          "links": {
            "related": "https://domain.com/api/albums/1234/primary-genre",
            "self": "https://domain.com/api/albums/1234/relationships/primary-genre"
          },
          "data": {
            "type": "genres",
            "id": "12"
          }
        }
      },
      "links": {
        "self": "https://domain.com/api/albums/1234"
      }
    }
  ],
  "included": [
    {
      "type": "users",
      "id": "456",
      "attributes": {
        "name": "John Artist",
        "email": "john@example.com",
        "created-at": "2024-01-15T08:30:00.000000Z",
        "updated-at": "2024-03-10T12:00:00.000000Z"
      },
      "links": {
        "self": "https://domain.com/api/users/456"
      }
    },
    {
      "type": "labels",
      "id": "789",
      "attributes": {
        "name": "Indie Records",
        "description": "Independent music label focusing on emerging artists",
        "created-at": "2023-06-01T10:00:00.000000Z",
        "updated-at": "2024-02-20T16:45:00.000000Z"
      },
      "relationships": {
        "albums": {
          "links": {
            "related": "https://domain.com/api/labels/789/albums",
            "self": "https://domain.com/api/labels/789/relationships/albums"
          }
        }
      },
      "links": {
        "self": "https://domain.com/api/labels/789"
      }
    },
    {
      "type": "genres",
      "id": "12",
      "attributes": {
        "name": "Ambient"
      },
      "links": {
        "self": "https://domain.com/api/genres/12"
      }
    }
  ]
}

Get Single Album

GET /albums/{id} 
GET /albums/1234?include=user,label,primary-genre,tracks
Authorization: Bearer {token}
Accept: application/vnd.api+json

Success Response

200 OK 
{
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "https://domain.com/api/albums/1234"
  },
  "data": {
    "type": "albums",
    "id": "1234",
    "attributes": {
      "title": "Midnight Dreams",
      "version-description": "Deluxe Edition",
      "version-id": 2,
      "description": "A collection of atmospheric tracks exploring themes of night and dreams",
      "label-name": "Indie Records",
      "tracks-count": 8,
      "format-name": "Album",
      "last-status": "draft",
      "is-explicit": false,
      "is-published": false,
      "upc-code": "123456789012",
      "original-release-date": "2024-03-15T00:00:00.000000Z",
      "digital-release-date": "2024-03-15T00:00:00.000000Z",
      "rights-owner-year": 2024,
      "rights-owner-name": "Dream Music Publishing",
      "copyright": "2024 Dream Music Publishing",
      "publishing": "2024 Dream Music Publishing",
      "artwork": "https://example.com/artwork/midnight-dreams.jpg",
      "origin": "api",
      "created-at": "2024-03-10T10:00:00.000000Z",
      "updated-at": "2024-03-15T14:30:00.000000Z"
    },
    "relationships": {
      "user": {
        "links": {
          "related": "https://domain.com/api/albums/1234/user",
          "self": "https://domain.com/api/albums/1234/relationships/user"
        },
        "data": {
          "type": "users",
          "id": "456"
        }
      },
      "label": {
        "links": {
          "related": "https://domain.com/api/albums/1234/label",
          "self": "https://domain.com/api/albums/1234/relationships/label"
        },
        "data": {
          "type": "labels",
          "id": "789"
        }
      },
      "primary-genre": {
        "links": {
          "related": "https://domain.com/api/albums/1234/primary-genre",
          "self": "https://domain.com/api/albums/1234/relationships/primary-genre"
        },
        "data": {
          "type": "genres",
          "id": "12"
        }
      },
      "tracks": {
        "links": {
          "related": "https://domain.com/api/albums/1234/tracks",
          "self": "https://domain.com/api/albums/1234/relationships/tracks"
        },
        "data": [
          {
            "type": "tracks",
            "id": "5678"
          },
          {
            "type": "tracks",
            "id": "5679"
          }
        ]
      }
    },
    "links": {
      "self": "https://domain.com/api/albums/1234"
    }
  },
  "included": [
    {
      "type": "users",
      "id": "456",
      "attributes": {
        "name": "John Artist",
        "email": "john@example.com",
        "created-at": "2024-01-15T08:30:00.000000Z",
        "updated-at": "2024-03-10T12:00:00.000000Z"
      },
      "links": {
        "self": "https://domain.com/api/users/456"
      }
    },
    {
      "type": "labels",
      "id": "789",
      "attributes": {
        "name": "Indie Records",
        "description": "Independent music label focusing on emerging artists",
        "created-at": "2023-06-01T10:00:00.000000Z",
        "updated-at": "2024-02-20T16:45:00.000000Z"
      },
      "relationships": {
        "albums": {
          "links": {
            "related": "https://domain.com/api/labels/789/albums",
            "self": "https://domain.com/api/labels/789/relationships/albums"
          }
        }
      },
      "links": {
        "self": "https://domain.com/api/labels/789"
      }
    },
    {
      "type": "genres",
      "id": "12",
      "attributes": {
        "name": "Ambient"
      },
      "links": {
        "self": "https://domain.com/api/genres/12"
      }
    },
    {
      "type": "tracks",
      "id": "5678",
      "attributes": {
        "title": "Lucid Dreaming",
        "is-explicit": false,
        "rights-owner-year": 2024,
        "rights-owner-name": "Dream Music Publishing",
        "order": 1,
        "isrc-code": "USRC17607839",
        "notes": "Opening track with ethereal vocals",
        "full-audiofile-url": "https://cdn.example.com/tracks/lucid-dreaming.wav",
        "length": "00:04:23",
        "lyrics": "Floating through the midnight sky...",
        "preview-start": 30,
        "publishing": "2024 Dream Music Publishing",
        "md5": "d41d8cd98f00b204e9800998ecf8427e",
        "created-at": "2024-03-08T14:20:00.000000Z",
        "updated-at": "2024-03-12T09:15:00.000000Z"
      },
      "relationships": {
        "albums": {
          "links": {
            "related": "https://domain.com/api/tracks/5678/albums",
            "self": "https://domain.com/api/tracks/5678/relationships/albums"
          }
        },
        "artists": {
          "links": {
            "related": "https://domain.com/api/tracks/5678/artists",
            "self": "https://domain.com/api/tracks/5678/relationships/artists"
          }
        }
      },
      "links": {
        "self": "https://domain.com/api/tracks/5678"
      }
    },
    {
      "type": "tracks",
      "id": "5679",
      "attributes": {
        "title": "Nocturnal Waves",
        "is-explicit": false,
        "rights-owner-year": 2024,
        "rights-owner-name": "Dream Music Publishing",
        "order": 2,
        "isrc-code": "USRC17607840",
        "notes": "Instrumental piece with ocean sounds",
        "full-audiofile-url": "https://cdn.example.com/tracks/nocturnal-waves.wav",
        "length": "00:05:17",
        "lyrics": null,
        "preview-start": 45,
        "publishing": "2024 Dream Music Publishing",
        "md5": "e99a18c428cb38d5f260853678922e03",
        "created-at": "2024-03-09T11:30:00.000000Z",
        "updated-at": "2024-03-12T16:45:00.000000Z"
      },
      "links": {
        "self": "https://domain.com/api/tracks/5679"
      }
    }
  ]
}

Create Album

POST /albums 
{
  "data": {
    "type": "albums",
    "attributes": {
      "title": "Sunset Boulevard",
      "artwork": "https://example.com/artwork/sunset-boulevard.jpg"
      "is-explicit": false,
      "original-release-date": "2024-06-01T00:00:00Z",
      "digital-release-date": "2024-06-01T00:00:00Z",
      "rights-owner-year": 2024,
      "rights-owner-name": "Sunset Music Group",
    },
    "relationships": {
      "label": {
        "data": { "type": "labels", "id": "123" }
      },
      "primary-genre": {
        "data": { "type": "genres", "id": "5" }
      },
      "language": {
        "data": { "type": "languages", "id": "1" }
      },
      "format": {
        "data": { "type": "album-formats", "id": "2" }
      }
    }
  }
}

Required Relationships

Important

The following relationships are required when creating an album:

  • • label - Must reference an existing label
  • • primary-genre - Must reference an existing genre
  • • language - Must reference an existing language

Success Response

201 Created

Update Album

PATCH /albums/{id} 
{
  "data": {
    "type": "albums",
    "id": "1234",
    "attributes": {
      "title": "Midnight Dreams - Special Edition",
      "description": "Updated description with bonus tracks and remastered audio",
      "is-explicit": true
    }
  }
}

Partial Updates

You can update specific fields without affecting others:

{
  "data": {
    "type": "albums",
    "id": "1234",
    "attributes": {
      "title": "Ocean Waves - Acoustic Version"
    }
  }
}

Delete Album

DELETE /albums/{id} 
DELETE /albums/1234
Authorization: Bearer {token}

Success Response

204 No Content

Usage Examples

Complete Album Creation Flow

1. Create Album
POST /albums
2. Add Artists
POST /album-artists
3. Add Tracks
POST /tracks
4. Request Distribution
POST /distribution-requests

Search and Filter

Find by title
GET /albums?filter[title]=Dreams
Get latest albums
GET /albums?sort=-created-at&page[size]=10
Published albums only
GET /albums?filter[is-published]=true
Albums by status
GET /albums?filter[last-status]=draft
Albums by user name
GET /albums?filter[user-name]=kahnwald
Albums by label name
GET /albums?filter[label-name]=nielsen