Skip to main content
Labels represent record labels or publishing entities in your music catalog. They serve as organizational units for grouping releases and managing distribution metadata.

​
Overview

The label management system enables you to:

Create labels

Set up record labels with contact information and location

Organize releases

Group releases under specific labels for distribution

Geographic data

Track label location by country code

Contact management

Store email and description for each label

​
Label entity structure

The Label entity contains the following fields: 
@Entity('labels')
@Unique(['id'])
export class Label extends AbstractEntity {
  // NAME
  @Column({ name: 'name', length: 255, type: 'varchar', nullable: false })
  name: string;

  // EMAIL
  @Column({ length: 255, type: 'varchar', nullable: true })
  email: string;

  // DESCRIPTION
  @Column({ name: 'description', length: 255, type: 'varchar', nullable: true })
  description: string;

  // USER ID
  @Column({ name: 'user_id', type: 'uuid', nullable: false })
  userId: string;

  // COUNTRY
  @Column({
    name: 'country',
    type: 'enum',
    enum: countriesList.map((country) => country.code),
    nullable: false,
    default: 'RW',
  })
  country: string;

  // Relations
  @ManyToOne(() => User, (user) => user.labels)
  user: User;

  @OneToMany(() => Release, (release) => release.label)
  releases: Release[];
}

​
Core fields

FieldTypeRequiredDescription
idUUIDYesUnique identifier (inherited from AbstractEntity)
namestring (255)YesLabel’s display name
emailstring (255)NoContact email address
descriptionstring (255)NoLabel description or bio
userIdUUIDYesReference to the owning user
countryenumYesISO country code (default: RW)
createdAttimestampYesRecord creation time (inherited)
updatedAttimestampYesLast update time (inherited)

​
Relationships

Each label is owned by a single user who manages the label’s information and releases.
@ManyToOne(() => User, (user) => user.labels)
@JoinColumn({ name: 'user_id' })
user: User;
A label can have multiple releases. This relationship allows you to organize your catalog by imprint or sub-label.
@OneToMany(() => Release, (release) => release.label)
releases: Release[];

​
Common operations

​
Create a label

Create a new label in your catalog: 
POST /labels

{
  "name": "Deep Sounds Records",
  "email": "[email protected]",
  "description": "Underground electronic music label",
  "country": "us"
}
The country code is automatically converted to uppercase. You can provide it in lowercase (us) or uppercase (US).
Response: 
{
  "message": "Label created successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Deep Sounds Records",
    "email": "[email protected]",
    "description": "Underground electronic music label",
    "country": "US",
    "userId": "...",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

​
Fetch labels

Retrieve labels with pagination: 
GET /labels?page=0&size=10
Query parameters:
  • page - Page number (default: 0)
  • size - Items per page (default: 10)
  • Any additional query parameters are applied as filter conditions
GET /labels?page=0&size=20

​
Get label by ID

Retrieve a specific label’s details with related user data: 
GET /labels/:id
Response: 
{
  "message": "Label found successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Deep Sounds Records",
    "email": "[email protected]",
    "description": "Underground electronic music label",
    "country": "US",
    "user": {
      "id": "...",
      "name": "John Doe",
      "email": "[email protected]"
    }
  }
}

​
Update a label

Modify an existing label’s information: 
PATCH /labels/:id

{
  "name": "Deep Sounds Records Ltd",
  "description": "Premium underground electronic music",
  "country": "gb"
}
All fields are optional. Only provided fields will be updated.
The service validates that the label exists before updating. If not found, a 404 Not Found error is returned.

​
Delete a label

Remove a label from the catalog: 
DELETE /labels/:id
Deleting a label will cascade delete all associated releases due to the relationship configuration. Make sure to backup or reassign releases before deleting a label.

​
Country codes

Labels use ISO 3166-1 alpha-2 country codes. The system includes a comprehensive list of countries from the countriesList constant.

​
Common country codes

United States

US

United Kingdom

GB

Germany

DE

France

FR

Japan

JP

Rwanda

RW (default)
Country codes are automatically converted to uppercase when creating or updating a label.

​
Use cases

​
Independent label setup

Create a label for your own releases: 
const label = await fetch('/labels', {
  method: 'POST',
  body: JSON.stringify({
    name: 'My Records',
    email: '[email protected]',
    country: 'us'
  })
});

​
Sub-label management

Create multiple labels for different genres or imprints: 
// Main label
await createLabel({
  name: 'Main Street Records',
  description: 'Parent label for all releases'
});

// Sub-labels
await createLabel({
  name: 'Main Street Deep',
  description: 'Deep house sub-label'
});

await createLabel({
  name: 'Main Street Tech',
  description: 'Techno sub-label'
});

​
Distribution organization

Organize releases by label for distribution platforms: 
// Fetch all releases for a label
const releases = await fetch(`/releases?labelId=${labelId}`);

// Group by label for distribution submission
const distributionData = {
  label: await fetch(`/labels/${labelId}`),
  releases: releases.data
};

​
Validation rules

  • Required field
  • Maximum 255 characters
  • Must be a non-empty string
  • Optional field
  • Must be a valid email format when provided
  • Maximum 255 characters
  • Must be a valid country code from the countriesList
  • Automatically converted to uppercase
  • Defaults to RW if not provided
  • The userId must reference an existing user
  • Validated during label creation
  • Returns error if user not found

Releases

Associate releases with labels

Artists

Manage artists on your label

Roles & Permissions

Control label management access

Build docs developers (and LLMs) love

Get started for freeTalk to us