Skip to main content
Labels help you organize artists and releases under a unified brand. This guide covers creating labels, managing label information, and organizing your catalog.

​
Prerequisites

  • An authenticated user account (see Authentication)
  • A valid JWT token

​
Understanding labels

Labels in Lens Music serve as organizational containers for:
  • Artists and their profiles
  • Music releases and albums
  • Catalog management and distribution
Each label can have multiple artists and releases associated with it, making it easy to manage your music business.

​
Creating a label

Set up a new record label in your catalog.
1

Prepare label information

Gather the following details:
  • name (required): The label’s official name
  • email (optional): Contact email for the label
  • description (optional): Brief description of the label
  • country (optional): Country where the label is based
Labels are automatically associated with the authenticated user who creates them.
2

Send create label request

Make a POST request to the labels endpoint:
curl -X POST https://api.lensmusic.com/labels \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Midnight Records",
    "email": "[email protected]",
    "description": "Independent electronic music label",
    "country": "US"
  }'
3

Handle the response

On success, you’ll receive the created label:
{
  "message": "Label created successfully",
  "data": {
    "id": "uuid-string",
    "name": "Midnight Records",
    "email": "[email protected]",
    "description": "Independent electronic music label",
    "country": "US",
    "userId": "user-uuid",
    "createdAt": "2026-03-04T10:30:00Z",
    "updatedAt": "2026-03-04T10:30:00Z"
  }
}
Save the label id to associate artists and releases with this label.

​
Fetching labels

Retrieve your label catalog with pagination support.

​
List all labels

curl -X GET "https://api.lensmusic.com/labels?page=0&size=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response: 
{
  "message": "Labels returned successfully",
  "data": {
    "items": [
      {
        "id": "label-uuid",
        "name": "Midnight Records",
        "email": "[email protected]",
        "description": "Independent electronic music label",
        "country": "US",
        "createdAt": "2026-03-04T10:30:00Z"
      }
    ],
    "total": 1,
    "page": 0,
    "size": 10
  }
}

​
Get a specific label

Retrieve details for a single label by ID: 
curl -X GET https://api.lensmusic.com/labels/{labelId} \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response: 
{
  "message": "Label found successfully",
  "data": {
    "id": "label-uuid",
    "name": "Midnight Records",
    "email": "[email protected]",
    "description": "Independent electronic music label",
    "country": "US",
    "userId": "user-uuid",
    "artists": [],
    "releases": [],
    "createdAt": "2026-03-04T10:30:00Z",
    "updatedAt": "2026-03-04T10:30:00Z"
  }
}

​
Updating labels

Modify label information after creation.
1

Prepare update data

You can update any of the following fields:
  • name: Label name
  • email: Contact email
  • description: Label description
  • country: Country code
2

Send update request

curl -X PATCH https://api.lensmusic.com/labels/{labelId} \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Midnight Records International",
    "description": "Global electronic music label"
  }'
3

Verify the update

{
  "message": "Label updated successfully",
  "data": {
    "id": "label-uuid",
    "name": "Midnight Records International",
    "email": "[email protected]",
    "description": "Global electronic music label",
    "country": "US",
    "updatedAt": "2026-03-04T11:00:00Z"
  }
}

​
Deleting labels

Remove a label from your catalog. 
curl -X DELETE https://api.lensmusic.com/labels/{labelId} \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Deleting a label will also delete all associated artists and releases due to cascade deletion. This action cannot be undone.

​
Organizing with labels

Once you’ve created a label, you can associate artists and releases with it.

​
Adding artists to a label

When creating or updating an artist, include the labelId: 
const response = await fetch('https://api.lensmusic.com/artists', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'The Midnight Collective',
    labelId: 'label-uuid'  // Associate with label
  })
});

​
Creating releases under a label

When creating a release, specify the labelId: 
const response = await fetch('https://api.lensmusic.com/releases', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Midnight Dreams',
    releaseDate: '2026-06-01',
    productionYear: 2026,
    labelId: 'label-uuid'  // Associate with label
  })
});

​
Pagination parameters

Control how many labels are returned in list queries:
ParameterTypeDefaultDescription
pageinteger0Zero-based page number
sizeinteger10Number of labels per page
Example: 
GET /labels?page=1&size=20

​
Error handling

{
  "message": "Label not found"
}
The label ID doesn’t exist or has been deleted.
{
  "message": "Validation failed",
  "errors": [
    "email must be a valid email"
  ]
}
Ensure the email follows standard format: [email protected]
{
  "message": "Validation failed",
  "errors": [
    "name should not be empty"
  ]
}
The name field is required when creating a label.

​
Best practices

Descriptive names

Use clear, descriptive names for labels that reflect your brand or music genre.

Consistent metadata

Keep label information up-to-date, especially contact email and country.

Organized catalog

Group related artists and releases under the same label for better organization.

Backup label IDs

Store label IDs in your application to easily reference them when creating artists and releases.

​
Next steps

Managing artists

Add artists to your label

Distributing releases

Create releases under your label

Build docs developers (and LLMs) love

Get started for freeTalk to us