Skip to main content
Artists are the foundation of your music catalog. This guide shows you how to create artist profiles, manage their status, and organize artists within your labels.

​
Prerequisites

  • An authenticated user account (see Authentication)
  • A valid JWT token
  • Optionally, a label ID to associate artists with a label

​
Creating an artist

Add new artists to your catalog with a simple API call.
1

Prepare artist data

Gather the required information:
  • name (required): The artist’s name or stage name
  • status (optional): Artist status - active or inactive (defaults to active)
Artists are automatically associated with the authenticated user who creates them.
2

Send create artist request

Make a POST request to the artists endpoint:
curl -X POST https://api.lensmusic.com/artists \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "The Midnight Collective",
    "status": "active"
  }'
3

Handle the response

On success, you’ll receive the created artist:
{
  "message": "Artist created successfully",
  "data": {
    "id": "uuid-string",
    "name": "The Midnight Collective",
    "status": "active",
    "userId": "user-uuid",
    "createdAt": "2026-03-04T10:30:00Z",
    "updatedAt": "2026-03-04T10:30:00Z"
  }
}
Save the artist id for future operations like updating or assigning to releases.

​
Fetching artists

Retrieve your artist catalog with pagination and filtering options.

​
List all artists

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

​
Filter by label

Retrieve artists associated with a specific label: 
GET /artists?labelId=label-uuid&page=0&size=10

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

​
Get a specific artist

Retrieve details for a single artist by ID: 
curl -X GET https://api.lensmusic.com/artists/{artistId} \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response: 
{
  "message": "Artist fetched successfully",
  "data": {
    "id": "artist-uuid",
    "name": "The Midnight Collective",
    "status": "active",
    "userId": "user-uuid",
    "labelId": "label-uuid",
    "createdAt": "2026-03-04T10:30:00Z",
    "updatedAt": "2026-03-04T10:30:00Z"
  }
}

​
Updating artists

Modify artist information or change their status.
1

Prepare update data

You can update:
  • name: Change the artist’s name
  • status: Set to active or inactive
2

Send update request

curl -X PATCH https://api.lensmusic.com/artists/{artistId} \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "The Midnight Collective (Updated)",
    "status": "active"
  }'
3

Verify the update

{
  "message": "Artist updated successfully",
  "data": {
    "id": "artist-uuid",
    "name": "The Midnight Collective (Updated)",
    "status": "active",
    "userId": "user-uuid",
    "updatedAt": "2026-03-04T11:00:00Z"
  }
}
Regular users can only update their own artists with active status. Admins can update any artist regardless of status.

​
Deleting artists

Remove an artist from your catalog. 
curl -X DELETE https://api.lensmusic.com/artists/{artistId} \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Deleting an artist is permanent and cannot be undone. Ensure you want to proceed before deletion.

​
Artist status management

Use artist status to control visibility and availability.
Artists with active status are:
  • Visible in all user queries
  • Available for assignment to releases
  • Included in public catalog listings
{ "status": "active" }
Artists with inactive status are:
  • Hidden from regular users (except admins)
  • Not available for new releases
  • Archived but not deleted
{ "status": "inactive" }
Use inactive status to temporarily hide artists without deleting their data.

​
Pagination parameters

Control how many artists are returned in list queries:
ParameterTypeDefaultDescription
pageinteger0Zero-based page number
sizeinteger10Number of artists per page
labelIdstring-Filter by label UUID
Example: 
GET /artists?page=2&size=25&labelId=label-uuid
Returns 25 artists from the third page (0-indexed) for the specified label.

​
Error handling

{
  "message": "Artist not found"
}
The artist ID doesn’t exist or has been deleted.
{
  "message": "Forbidden"
}
You don’t have permission to access or modify this artist. Regular users can only manage their own active artists.
{
  "message": "Validation failed",
  "errors": [
    "name should not be empty",
    "status must be one of: active, inactive"
  ]
}
Check that required fields are provided and valid.

​
Next steps

Creating labels

Organize artists under record labels

Distributing releases

Create releases and assign artists

Build docs developers (and LLMs) love

Get started for freeTalk to us