Albums - limbo/API

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	max: 255	✓
artwork	string	Artwork file path	max: 500	✓
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	min: 1900, max: current year+1	✓
rights-owner-name	string	Rights owner name	max: 255	✓

Optional Attributes

Field	Type	Description	Validations	Editable
id	string	Unique identifier	auto-generated	❌
description	string	Album description	-	✓
version-description	string	Version description	read-only	❌
version-id	number	Version ID	-	✓
is-published	boolean	Publication status	read-only	❌
upc-code	string	UPC Code (Universal Product Code)	max: 20, unique	✓
copyright	string	Copyright information	auto-generated	❌
publishing	string	Publishing information	auto-generated	❌
grid	string	GRID identifier	max: 50	✓
catalogue-number	string	Catalogue number	max: 50	✓
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	Type	Resource	Description	Editable
label	BelongsTo	labels	Record label	✓
primary-genre	BelongsTo	genres	Primary music genre	✓
language	BelongsTo	languages	Album language	✓
format	BelongsTo	album-formats	Album format (Album, LP, Single, etc.)	✓

Optional Relationships

Relationship	Type	Resource	Description	Editable
user	BelongsTo	users	Album owner (automatically assigned)	❌
secondary-genre	BelongsTo	genres	Secondary music genre	✓
version	BelongsTo	versions	Album version	✓

Collection Relationships (Read-only)

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

Many-to-Many Relationships (Editable)

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

Relationship	Type	Resource	Description
tracks	BelongsToMany	tracks	Tracks that compose the album
artists	BelongsToMany	artists	Artists associated with the album
countries	BelongsToMany	countries	Distribution countries
dsps	BelongsToMany	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
• filter[last-status] - Filter by album status
• filter[label] - Filter by label ID
• filter[is-explicit] - Filter by explicit flag
• 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)

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",
        "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"
          }
        }
      },
      "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

Getting Started

Core Resources

Supporting Data

Distribution

Reference

🎵 Albums

Resource Overview

Schema

Atributos Requeridos

Optional Attributes

Required Relationships

Optional Relationships

Collection Relationships (Read-only)

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

Delete Album

Success Response

💡 Usage Examples

Complete Album Creation Flow

Search and Filter