Albums

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/v1/albums?include=user,label,primary-genre&page[number]=1&page[size]=5",
    "last": "https://domain.com/api/v1/albums?include=user,label,primary-genre&page[number]=7&page[size]=5",
    "next": "https://domain.com/api/v1/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/v1/albums/1234/user",
            "self": "https://domain.com/api/v1/albums/1234/relationships/user"
          },
          "data": {
            "type": "users",
            "id": "456"
          }
        },
        "label": {
          "links": {
            "related": "https://domain.com/api/v1/albums/1234/label",
            "self": "https://domain.com/api/v1/albums/1234/relationships/label"
          },
          "data": {
            "type": "labels",
            "id": "789"
          }
        },
        "primary-genre": {
          "links": {
            "related": "https://domain.com/api/v1/albums/1234/primary-genre",
            "self": "https://domain.com/api/v1/albums/1234/relationships/primary-genre"
          },
          "data": {
            "type": "genres",
            "id": "12"
          }
        }
      },
      "links": {
        "self": "https://domain.com/api/v1/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/v1/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/v1/labels/789/albums",
            "self": "https://domain.com/api/v1/labels/789/relationships/albums"
          }
        }
      },
      "links": {
        "self": "https://domain.com/api/v1/labels/789"
      }
    },
    {
      "type": "genres",
      "id": "12",
      "attributes": {
        "name": "Ambient"
      },
      "links": {
        "self": "https://domain.com/api/v1/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/v1/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/v1/albums/1234/user",
          "self": "https://domain.com/api/v1/albums/1234/relationships/user"
        },
        "data": {
          "type": "users",
          "id": "456"
        }
      },
      "label": {
        "links": {
          "related": "https://domain.com/api/v1/albums/1234/label",
          "self": "https://domain.com/api/v1/albums/1234/relationships/label"
        },
        "data": {
          "type": "labels",
          "id": "789"
        }
      },
      "primary-genre": {
        "links": {
          "related": "https://domain.com/api/v1/albums/1234/primary-genre",
          "self": "https://domain.com/api/v1/albums/1234/relationships/primary-genre"
        },
        "data": {
          "type": "genres",
          "id": "12"
        }
      },
      "tracks": {
        "links": {
          "related": "https://domain.com/api/v1/albums/1234/tracks",
          "self": "https://domain.com/api/v1/albums/1234/relationships/tracks"
        },
        "data": [
          {
            "type": "tracks",
            "id": "5678"
          },
          {
            "type": "tracks",
            "id": "5679"
          }
        ]
      }
    },
    "links": {
      "self": "https://domain.com/api/v1/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/v1/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/v1/labels/789/albums",
            "self": "https://domain.com/api/v1/labels/789/relationships/albums"
          }
        }
      },
      "links": {
        "self": "https://domain.com/api/v1/labels/789"
      }
    },
    {
      "type": "genres",
      "id": "12",
      "attributes": {
        "name": "Ambient"
      },
      "links": {
        "self": "https://domain.com/api/v1/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/v1/tracks/5678/albums",
            "self": "https://domain.com/api/v1/tracks/5678/relationships/albums"
          }
        },
        "artists": {
          "links": {
            "related": "https://domain.com/api/v1/tracks/5678/artists",
            "self": "https://domain.com/api/v1/tracks/5678/relationships/artists"
          }
        }
      },
      "links": {
        "self": "https://domain.com/api/v1/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/v1/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"
    }
  }
}

Video Releases

An album whose format is the Video album format is a video release. Working with one requires the video feature on your account. These refusals carry their reason in the error's code:

Status	code	When
403	video_not_allowed	Creating an album, or editing one, with the video format when your account does not have the video feature.
403	video_read_only	Any change to a video release (update, delete, its countries, its tracks or its DSPs) when your account does not have the video feature. You can still read it.
422	video_format_new_albums_only	Editing an existing album to the video format when it was not created as one. The video format can only be chosen when the album is created.
422	dsp_does_not_accept_video	Sending `dsps` with a DSP that does not accept video for an album whose tracks are all videos. The whole request is refused and the `detail` names the rejected DSPs, also listed in the error's `meta.dsps`.

A release whose only track is a music video must use the video format. A one-track release of any other format whose track is a video is not complete, and a distribution request for it is refused with an error asking for the Video format. Takedown requests are not affected.

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

Getting Started

Core Resources

Analytics

Royalties

Supporting Data

Distribution

Notifications

Reference

Resource Overview

Schema

Atributos Requeridos

Optional Attributes

Required Relationships

Optional Relationships

Version: two ways to set it

Collection Relationships (Read-only)

Related Endpoints

Many-to-Many Relationships (Editable)

List Albums

Query Parameters

Filtering

Other Parameters

Example Request

Success Response

Get Single Album

Success Response

Create Album

Required Relationships

Important

Success Response

Update Album

Partial Updates

Video Releases

Delete Album

Success Response

Usage Examples

Complete Album Creation Flow

Search and Filter