Skip to main content
The releases endpoints allow you to create and retrieve music release information. All endpoints require JWT authentication.

​
Create release

POST /api/releases Create a new music release. The system automatically generates a catalog number and validates for duplicate releases. Authentication required: Yes (JWT Bearer token)

​
Request body

​
title
string
required
Release title
​
releaseDate
string
required
Release date (ISO 8601 format or any valid date string)
​
productionYear
number
required
Year the release was produced
​
upc
string
Universal Product Code (optional)
​
version
string
Release version (e.g., ‘original’, ‘remix’, ‘remaster’). Defaults to ‘original’
​
labelId
string
ID of the associated label (optional)

​
Response

​
message
string
Success message: “Release created successfully”
​
data
object
The created release object

​
Example request

curl -X POST https://your-domain.com/api/releases \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Midnight Dreams",
    "upc": "123456789012",
    "releaseDate": "2024-06-15",
    "version": "original",
    "productionYear": 2024,
    "labelId": "b2c3d4e5-f6a7-4b5c-8d7e-9f8a7b6c5d4e"
  }'

const response = await fetch('https://your-domain.com/api/releases', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Midnight Dreams',
    upc: '123456789012',
    releaseDate: '2024-06-15',
    version: 'original',
    productionYear: 2024,
    labelId: 'b2c3d4e5-f6a7-4b5c-8d7e-9f8a7b6c5d4e'
  })
});

const data = await response.json();

​
Example response

{
  "message": "Release created successfully",
  "data": {
    "id": "c3d4e5f6-a7b8-4c5d-8e7f-9a8b7c6d5e4f",
    "title": "Midnight Dreams",
    "upc": "123456789012",
    "releaseDate": "2024-06-15T00:00:00.000Z",
    "version": "original",
    "productionYear": 2024,
    "catalogNumber": "2024-001",
    "labelId": "b2c3d4e5-f6a7-4b5c-8d7e-9f8a7b6c5d4e",
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "createdAt": "2024-03-04T10:00:00.000Z",
    "updatedAt": "2024-03-04T10:00:00.000Z"
  }
}

​
Error responses

409 Conflict - Release already exists 
{
  "message": "Release already exists",
  "data": {
    "id": "c3d4e5f6-a7b8-4c5d-8e7f-9a8b7c6d5e4f"
  }
}
A release is considered duplicate if it has the same title, release date, production year, version, label, and user.

​
List releases

GET /api/releases Retrieve a paginated list of releases. Non-admin users see only their own releases. Authentication required: Yes (JWT Bearer token)

​
Query parameters

​
size
number
default:"10"
Number of releases per page
​
page
number
default:"0"
Page number (zero-indexed)
​
labelId
string
Filter releases by label ID
​
userId
string
Filter releases by user ID (admin only)

​
Response

​
message
string
Success message: “Releases fetched successfully”
​
data
array
Array of release objects

​
Example request

curl -X GET "https://your-domain.com/api/releases?size=20&page=0&labelId=b2c3d4e5-f6a7-4b5c-8d7e-9f8a7b6c5d4e" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

const params = new URLSearchParams({
  size: '20',
  page: '0',
  labelId: 'b2c3d4e5-f6a7-4b5c-8d7e-9f8a7b6c5d4e'
});

const response = await fetch(`https://your-domain.com/api/releases?${params}`, {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const data = await response.json();

​
Example response

{
  "message": "Releases fetched successfully",
  "data": [
    {
      "id": "c3d4e5f6-a7b8-4c5d-8e7f-9a8b7c6d5e4f",
      "title": "Midnight Dreams",
      "coverArt": null,
      "upc": "123456789012",
      "releaseDate": "2024-06-15T00:00:00.000Z",
      "version": "original",
      "productionYear": 2024,
      "catalogNumber": "2024-001",
      "labelId": "b2c3d4e5-f6a7-4b5c-8d7e-9f8a7b6c5d4e",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2024-03-04T10:00:00.000Z",
      "updatedAt": "2024-03-04T10:00:00.000Z"
    }
  ]
}

​
Get release by ID

GET /api/releases/:id Retrieve a specific release by ID. Authentication required: Yes (JWT Bearer token)

​
Path parameters

​
id
string
required
The unique identifier (UUID) of the release

​
Response

​
message
string
Success message: “Release fetched successfully”
​
data
object
The release object

​
Example request

curl -X GET https://your-domain.com/api/releases/c3d4e5f6-a7b8-4c5d-8e7f-9a8b7c6d5e4f \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

const releaseId = 'c3d4e5f6-a7b8-4c5d-8e7f-9a8b7c6d5e4f';

const response = await fetch(`https://your-domain.com/api/releases/${releaseId}`, {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const data = await response.json();

​
Error responses

404 Not Found - Release does not exist 
{
  "statusCode": 404,
  "message": "Release not found"
}

​
Release object structure

​
id
string
Unique release identifier (UUID)
​
title
string
Release title
​
coverArt
string
URL to cover art image (nullable)
​
upc
string
Universal Product Code (nullable)
​
releaseDate
string
Scheduled release date (ISO 8601)
​
version
string
Release version (e.g., ‘original’, ‘remix’, ‘remaster’)
​
productionYear
number
Year the release was produced
​
catalogNumber
string
Auto-generated catalog number
​
labelId
string
ID of the associated label (nullable)
​
userId
string
ID of the user who created the release
​
createdAt
string
Timestamp when the release was created (ISO 8601)
​
updatedAt
string
Timestamp when the release was last updated (ISO 8601)

​
Notes

  • Catalog numbers are automatically generated based on the production year
  • The system prevents duplicate releases with the same combination of title, release date, production year, version, label, and user
  • Release dates are formatted and stored in ISO 8601 format
  • Releases cascade delete when associated labels or users are deleted

Build docs developers (and LLMs) love

Get started for freeTalk to us