Skip to main content
This guide will walk you through creating an account, setting up your label, adding artists, and publishing your first release on Lens Music.

​
Prerequisites

Before you begin, ensure you have:
  • A valid email address
  • Artist and release information ready
  • Cover art and audio files prepared

​
Create your account

1

Sign up for Lens Music

Create your account by sending a POST request to the signup endpoint:
POST /api/auth/signup
Content-Type: application/json

{
  "email": "[email protected]",
  "name": "Your Name",
  "phone": "+1234567890",
  "password": "your_secure_password"
}
Your password should be strong and secure. The API uses bcrypt for password hashing.
Response:
{
  "message": "You have signed up successfully!",
  "data": {
    "user": {
      "id": "uuid-string",
      "email": "[email protected]",
      "name": "Your Name",
      "phone": "+1234567890",
      "status": "ACTIVE"
    },
    "token": "jwt-token-string"
  }
}
Save the JWT token - you’ll need it for all subsequent requests.
2

Login to your account

If you already have an account, authenticate with:
POST /api/auth/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "your_secure_password"
}
Response:
{
  "message": "You have logged in successfully!",
  "data": {
    "user": {
      "id": "uuid-string",
      "email": "[email protected]",
      "name": "Your Name"
    },
    "token": "jwt-token-string"
  }
}

​
Set up your music infrastructure

1

Create a label

Every release needs to be associated with a label. Create one with:
POST /api/labels
Authorization: Bearer your-jwt-token
Content-Type: application/json

{
  "name": "My Record Label",
  "email": "[email protected]",
  "description": "Independent music label",
  "country": "RW"
}
Response:
{
  "message": "Label created successfully",
  "data": {
    "id": "label-uuid",
    "name": "My Record Label",
    "email": "[email protected]",
    "country": "RW",
    "userId": "your-user-id"
  }
}
The country field accepts ISO country codes. Default is “RW” (Rwanda).
2

Add your artists

Create artist profiles for the musicians on your releases:
POST /api/artists
Authorization: Bearer your-jwt-token
Content-Type: application/json

{
  "name": "Artist Name"
}
Response:
{
  "message": "Artist created successfully",
  "data": {
    "id": "artist-uuid",
    "name": "Artist Name",
    "status": "ACTIVE",
    "userId": "your-user-id"
  }
}
Artists are automatically set to ACTIVE status and associated with your account.

​
Publish your first release

1

Create the release

Now you’re ready to create your first music release:
POST /api/releases
Authorization: Bearer your-jwt-token
Content-Type: application/json

{
  "title": "My First Album",
  "upc": "123456789012",
  "releaseDate": "2026-06-01",
  "productionYear": 2026,
  "version": "original",
  "labelId": "your-label-id"
}
Response:
{
  "message": "Release created successfully",
  "data": {
    "id": "release-uuid",
    "title": "My First Album",
    "upc": "123456789012",
    "releaseDate": "2026-06-01T00:00:00.000Z",
    "productionYear": 2026,
    "version": "original",
    "catalogNumber": "LM-2026-XXXX",
    "labelId": "your-label-id",
    "userId": "your-user-id"
  }
}
The catalog number is automatically generated based on the production year.
Releases are unique by the combination of title, release date, production year, label, and version. You cannot create duplicate releases.
2

View your release

Retrieve your release details:
GET /api/releases/{release-id}
Authorization: Bearer your-jwt-token
Or list all your releases:
GET /api/releases?page=0&size=10
Authorization: Bearer your-jwt-token
The API supports pagination with page and size query parameters, and filtering by labelId or userId.

​
Next steps

Architecture Overview

Learn about the Lens Music platform architecture

API Reference

Explore the complete API documentation

Managing Artists

Deep dive into artist management

Release Management

Advanced release features and workflows

​
Authentication headers

All authenticated endpoints require a JWT token in the Authorization header: 
Authorization: Bearer your-jwt-token
The token is valid for 1 week and must be included in every request to protected endpoints.

​
Common error responses

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us