Skip to main content
Releases are the core of your music distribution. This guide walks you through creating releases, managing metadata, and organizing tracks for distribution.

​
Prerequisites

  • An authenticated user account (see Authentication)
  • A valid JWT token
  • A label ID (recommended, see Creating labels)
  • Artist IDs to associate with the release

​
Understanding releases

A release in Lens Music represents:
  • An album, EP, or single
  • Associated metadata (title, UPC, release date, catalog number)
  • Tracks and their information
  • Artist associations
  • Label affiliation
Each release gets a unique catalog number generated from the production year.

​
Creating a release

Set up a new music release with metadata and distribution information.
1

Prepare release metadata

Gather the required information:
  • title (required): Release title (album/EP/single name)
  • releaseDate (required): Official release date (ISO 8601 format)
  • productionYear (required): Year the music was produced
  • upc (optional): Universal Product Code for distribution
  • version (optional): Version identifier (defaults to “original”)
  • labelId (optional): UUID of the associated label
Releases must be unique based on the combination of title, release date, production year, user, label, and version.
2

Send create release request

Make a POST request to the releases endpoint:
curl -X POST https://api.lensmusic.com/releases \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Midnight Dreams",
    "releaseDate": "2026-06-01",
    "productionYear": 2026,
    "upc": "123456789012",
    "version": "original",
    "labelId": "label-uuid"
  }'
3

Handle the response

On success, you’ll receive the created release:
{
  "message": "Release created successfully",
  "data": {
    "id": "release-uuid",
    "title": "Midnight Dreams",
    "releaseDate": "2026-06-01T00:00:00.000Z",
    "productionYear": 2026,
    "upc": "123456789012",
    "version": "original",
    "catalogNumber": "2026-ABC123",
    "labelId": "label-uuid",
    "userId": "user-uuid",
    "coverArt": null,
    "createdAt": "2026-03-04T10:30:00Z",
    "updatedAt": "2026-03-04T10:30:00Z"
  }
}
The catalogNumber is automatically generated based on the productionYear. Save the release id for adding tracks and managing the release.

​
Fetching releases

Retrieve releases with filtering and pagination options.

​
List all releases

curl -X GET "https://api.lensmusic.com/releases?page=0&size=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Filter by label

Retrieve releases for a specific label: 
GET /releases?labelId=label-uuid&page=0&size=10

curl -X GET "https://api.lensmusic.com/releases?labelId=label-uuid" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Filter by user (admin only)

Admins can filter releases by user ID: 
GET /releases?userId=user-uuid&page=0&size=10
Regular users automatically see only their own releases. Admins can query any user’s releases.

​
Get a specific release

Retrieve details for a single release: 
curl -X GET https://api.lensmusic.com/releases/{releaseId} \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response: 
{
  "message": "Release fetched successfully",
  "data": {
    "id": "release-uuid",
    "title": "Midnight Dreams",
    "releaseDate": "2026-06-01T00:00:00.000Z",
    "productionYear": 2026,
    "upc": "123456789012",
    "version": "original",
    "catalogNumber": "2026-ABC123",
    "coverArt": null,
    "labelId": "label-uuid",
    "userId": "user-uuid",
    "label": {
      "id": "label-uuid",
      "name": "Midnight Records"
    },
    "artists": [],
    "tracks": [],
    "createdAt": "2026-03-04T10:30:00Z",
    "updatedAt": "2026-03-04T10:30:00Z"
  }
}

​
Release metadata explained

The catalog number is automatically generated using the production year:
catalogNumber: "2026-ABC123"
This unique identifier helps organize releases within your catalog. It’s generated server-side and cannot be manually set.
Universal Product Code for commercial distribution:
{ "upc": "123456789012" }
  • 12-digit numeric code
  • Required for most digital distribution platforms
  • Must be unique across all releases
  • Optional field but recommended for commercial releases
Use ISO 8601 date format:
{ "releaseDate": "2026-06-01" }
The server automatically formats this to full ISO timestamp:
"2026-06-01T00:00:00.000Z"
Differentiate between versions of the same release:
{
  "version": "original",      // Original release
  "version": "deluxe",        // Deluxe edition
  "version": "remastered",    // Remastered version
  "version": "instrumental"   // Instrumental version
}
Defaults to “original” if not specified.

​
Uniqueness constraints

Releases must be unique based on this combination:
  • Title
  • Release date
  • Production year
  • User ID
  • Label ID
  • Version
If you try to create a duplicate release, you’ll receive a 409 Conflict error: 
{
  "message": "Release already exists",
  "data": {
    "id": "existing-release-uuid"
  }
}
To create variations of the same release, use the version field (e.g., “deluxe”, “instrumental”).

​
Pagination parameters

ParameterTypeDefaultDescription
pageinteger0Zero-based page number
sizeinteger10Number of releases per page
labelIdstring-Filter by label UUID
userIdstring-Filter by user UUID (admin only)
Example: 
GET /releases?page=1&size=25&labelId=label-uuid

​
Error handling

{
  "message": "Release already exists",
  "data": {
    "id": "existing-release-uuid"
  }
}
A release with the same metadata combination already exists. Check the uniqueness constraints or use a different version identifier.
{
  "message": "Release not found"
}
The release ID doesn’t exist or has been deleted.
{
  "message": "Validation failed",
  "errors": [
    "title should not be empty",
    "releaseDate should not be empty",
    "productionYear must be a number"
  ]
}
Ensure all required fields are provided with correct types.

​
Best practices

Unique UPC codes

Use unique UPC codes for each release. Obtain UPC codes from authorized providers for commercial distribution.

Accurate metadata

Provide complete and accurate metadata. This ensures proper cataloging and distribution.

Proper versioning

Use the version field to differentiate between release variants (original, deluxe, remastered).

Label association

Always associate releases with a label for better organization and catalog management.

​
Adding tracks to releases

After creating a release, you’ll typically want to add tracks. While the tracks endpoint details are covered in the API reference, here’s a quick overview: 
// Create a track for the release
const trackResponse = await fetch('https://api.lensmusic.com/tracks', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Midnight Song',
    duration: 240,  // in seconds
    explicit: false,
    isrc: 'USXXX2600001',
    releaseId: releaseId  // Associate with release
  })
});

​
Next steps

Creating synced lyrics

Add time-synced lyrics to your tracks

API Reference

View complete releases API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us