🏷️ Labels

Record labels and music distributors managing album releases

Resource Overview

Labels represent record labels, music distributors, and publishing companies that manage and distribute music releases. They support smart creation to avoid duplicates for the same user and provide organizational structure for album catalogs.

Base Endpoint
/labels
Resource Type
labels
User Scope
User-owned with smart creation

Schema

Required Attributes

Field Type Validation Description
name string required, max:255 Official name of the record label

Optional Attributes

Field Type Validation Description
description string nullable, max:300 Business description and specialties

Read-only Attributes

Field Type Description
id string Unique identifier
created-at datetime Creation timestamp
updated-at datetime Last modification timestamp

Relationships

Relationship Type Related Resource Description
albums HasMany albums All albums released under this label

Smart Creation Logic

🧠 Intelligent Deduplication

  • • Find or Create: If a label with the same name exists for the current user, returns existing record
  • • Description Update: Updates description if new one is provided and different
  • • User Scope: Deduplication only applies within the same user's labels
  • • Automatic User Assignment: User ID is automatically assigned to new labels

List Labels

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

Query Parameters

Filtering

  • • filter[name] - Filter by label name
  • • filter[description] - Filter by description content
  • • filter[has-albums] - Labels with/without albums

Other Parameters

  • • include - Include albums relationship
  • • sort - Sort by name, created-at, updated-at
  • • page[number] - Page number
  • • page[size] - Results per page

Example Request

GET /labels?include=albums&sort=name

Success Response

200 OK 
{
  "data": [
    {
      "type": "labels",
      "id": "1",
      "attributes": {
        "name": "Horizon Records",
        "description": "Independent record label specializing in alternative rock and electronic music",
        "created-at": "2024-08-19T10:00:00Z",
        "updated-at": "2024-08-19T10:00:00Z"
      },
      "relationships": {
        "albums": {
          "data": [
            { "type": "albums", "id": "1" },
            { "type": "albums", "id": "3" }
          ]
        }
      }
    },
    {
      "type": "labels",
      "id": "2",
      "attributes": {
        "name": "Digital Wave Music",
        "description": "Electronic music focused label and distribution",
        "created-at": "2024-08-20T14:30:00Z",
        "updated-at": "2024-08-20T14:30:00Z"
      },
      "relationships": {
        "albums": {
          "data": [
            { "type": "albums", "id": "5" }
          ]
        }
      }
    }
  ],
  "included": [
    {
      "type": "albums",
      "id": "1",
      "attributes": {
        "title": "Electric Dreams"
      }
    },
    {
      "type": "albums",
      "id": "3",
      "attributes": {
        "title": "Acoustic Sessions"
      }
    },
    {
      "type": "albums",
      "id": "5",
      "attributes": {
        "title": "Bass Revolution"
      }
    }
  ],
  "meta": {
    "page": {
      "current-page": 1,
      "per-page": 20,
      "total": 2,
      "last-page": 1
    }
  }
}

Create Label

POST /labels

Request Body

{
  "data": {
    "type": "labels",
    "attributes": {
      "name": "Horizon Records",
      "description": "Independent record label specializing in alternative rock and electronic music"
    }
  }
}

Required Fields

  • • name - Label name (max 255 characters)

Optional Fields

  • • description - Business description (max 300 characters)

Success Response

201 Created 
{
  "data": {
    "type": "labels",
    "id": "15",
    "attributes": {
      "name": "Horizon Records",
      "description": "Independent record label specializing in alternative rock and electronic music",
      "created-at": "2024-08-21T16:45:00Z",
      "updated-at": "2024-08-21T16:45:00Z"
    },
    "relationships": {
      "albums": {
        "data": []
      }
    }
  }
}

🧠 Smart Creation

If a label with the same name already exists for your account, the existing label will be returned instead of creating a duplicate. If you provide a different description, it will be updated on the existing label.

Update Label

PATCH /labels/{id}

Request Body Example

{
  "data": {
    "type": "labels",
    "id": "1",
    "attributes": {
      "description": "Premium independent record label focusing on innovative alternative rock and cutting-edge electronic music"
    }
  }
}

Success Response

200 OK 
{
  "data": {
    "type": "labels",
    "id": "1",
    "attributes": {
      "name": "Horizon Records",
      "description": "Premium independent record label focusing on innovative alternative rock and cutting-edge electronic music",
      "created-at": "2024-08-19T10:00:00Z",
      "updated-at": "2024-08-21T16:50:00Z"
    },
    "relationships": {
      "albums": {
        "data": [
          { "type": "albums", "id": "1" },
          { "type": "albums", "id": "3" }
        ]
      }
    }
  }
}

Delete Label

DELETE /labels/{id} 
DELETE /labels/1
Authorization: Bearer {token}

⚠️ Important Notes

  • • Labels with existing albums cannot be deleted
  • • Can only delete labels you own
  • • This action is permanent and cannot be undone
  • • Consider removing all albums first if deletion is necessary

Success Response

204 No Content

Resource Overview

� Key Statistics

  • • Manages album distribution
  • • Supports smart creation
  • • User-scoped ownership

✨ Key Features

  • • Find-or-create logic
  • • Album relationship management

🔗 Common Use Cases

  • • Independent label setup
  • • Album catalog organization
  • • Distribution management
  • • Publishing rights tracking