🎵 Tracks

Individual songs with lyrics, metadata, and album associations

Resource Overview

Tracks represent individual songs within your music catalog. Each track contains detailed metadata including lyrics, duration, and explicit content flags, and can be associated with album.

Base Endpoint

/tracks

Resource Type

tracks

User Scope

Owner-restricted

Schema

Required Attributes

Field	Type	Validation	Description
title	string	required, max:300	Track title
is-explicit	boolean	required	Explicit content flag
rights-owner-year	integer	required, min:1900	Rights ownership year
rights-owner-name	string	required, max:200	Rights owner name
order	integer	required, min:1, unique per album	Track order within album
full-audiofile-url	string	required, max:200	Full audio file URL

Optional Attributes

Field	Type	Validation	Description
isrc-code	string	nullable, max:100	International Standard Recording Code
version	string	nullable, max:200	Track version (e.g., "Radio Edit", "Extended")
length	string	nullable, time format	Track duration (HH:MM:SS)
lyrics	string	nullable	Track lyrics
preview-start	integer	nullable, min:0	Preview start time in seconds

Read-only Attributes

Field	Type	Description
id	string	Unique identifier
created-at	datetime	Creation timestamp
updated-at	datetime	Last update timestamp

Required Relationships

Relationship	Type	Related Resource	Description
albums	BelongsToMany	albums	Album associations (at least one required)
primary-genre	BelongsTo	genres	Primary genre classification
language	BelongsTo	languages	Track language

Optional Relationships

Relationship	Type	Related Resource	Description
secondary-genre	BelongsTo	genres	Secondary genre classification
track-artists	HasMany	track-artists	Artist associations with roles
version	BelongsTo	versions	Version type reference
artists	BelongsToMany	artists	Direct artist associations

Read-only Relationships

Relationship	Type	Related Resource	Description
user	BelongsTo	users	Track owner (auto-assigned)
album-tracks	HasMany	album-tracks	Album tracks
trends	HasMany	trends	Track trend analytics

List Tracks

GET /tracks

GET /tracks
Authorization: Bearer {token}
Accept: application/vnd.api+json

Query Parameters

Filtering

• filter[title] - Filter by track title
• filter[is-explicit] - Filter by explicit content
• filter[order] - Filter by track order
• filter[rights-owner-year] - Filter by rights year
• filter[primary-genre] - Filter by primary genre

Other Parameters

• include - Include relationships
• sort - Sort by field
• page[number] - Page number
• page[size] - Results per page

Example Request

GET /tracks?include=albums,primary-genre,language&filter[title]=City&sort=order

Success Response

200 OK

{
  "data": [
    {
      "type": "tracks",
      "id": "1",
      "attributes": {
        "title": "City Lights",
        "is-explicit": false,
        "rights-owner-year": 2024,
        "rights-owner-name": "Indie Music Co.",
        "order": 1,
        "isrc-code": "US-S1Z-99-00001",
        "version": "Original Mix",
        "length": "00:03:42",
        "lyrics": "Walking through the city lights tonight...",
        "preview-start": 30,
        "publishing": "2024 Indie Music Co.",
        "full-audiofile-url": "https://storage.example.com/tracks/city-lights.wav",
        "created-at": "2024-08-01T10:00:00Z",
        "updated-at": "2024-08-15T14:30:00Z"
      },
      "relationships": {
        "albums": {
          "data": [
            { "type": "albums", "id": "1" }
          ]
        },
        "primary-genre": {
          "data": { "type": "genres", "id": "3" }
        },
        "language": {
          "data": { "type": "languages", "id": "1" }
        },
        "secondary-genre": {
          "data": { "type": "genres", "id": "8" }
        },
        "track-artists": {
          "data": [
            { "type": "track-artists", "id": "1" },
            { "type": "track-artists", "id": "2" }
          ]
        }
      }
    },
    {
      "type": "tracks",
      "id": "2",
      "attributes": {
        "title": "Midnight Drive",
        "is-explicit": false,
        "rights-owner-year": 2024,
        "rights-owner-name": "Indie Music Co.",
        "order": 2,
        "length": "00:04:15",
        "full-audiofile-url": "https://storage.example.com/tracks/midnight-drive.wav",
        "created-at": "2024-08-02T11:30:00Z",
        "updated-at": "2024-08-02T11:30:00Z"
      },
      "relationships": {
        "albums": {
          "data": [
            { "type": "albums", "id": "1" }
          ]
        },
        "primary-genre": {
          "data": { "type": "genres", "id": "3" }
        },
        "language": {
          "data": { "type": "languages", "id": "1" }
        }
      }
    }
  ],
  "included": [
    {
      "type": "albums",
      "id": "1",
      "attributes": {
        "title": "Electric Dreams",
        "artwork": "https://storage.example.com/artwork/electric-dreams.jpg"
      }
    },
    {
      "type": "genres",
      "id": "3",
      "attributes": {
        "name": "Electronic"
      }
    },
    {
      "type": "languages",
      "id": "1",
      "attributes": {
        "name": "English",
        "code": "en"
      }
    }
  ],
  "meta": {
    "page": {
      "current-page": 1,
      "per-page": 20,
      "total": 12,
      "last-page": 1
    }
  }
}

POST /tracks

Create a new track with complete metadata and album associations.

Request Body

{
  "data": {
    "type": "tracks",
    "attributes": {
      "title": "City Lights",
      "is-explicit": false,
      "rights-owner-year": 2024,
      "rights-owner-name": "Indie Music Co.",
      "order": 1,
      "full-audiofile-url": "https://storage.example.com/tracks/city-lights.wav"
    },
    "relationships": {
      "albums": {
        "data": [
          {
            "type": "albums",
            "id": "1"
          }
        ]
      },
      "primary-genre": {
        "data": {
          "type": "genres",
          "id": "3"
        }
      },
      "language": {
        "data": {
          "type": "languages",
          "id": "1"
        }
      }
    }
  }
}

Required Fields

Attributes

• title - Track title (max 300 characters)
• is-explicit - Explicit content flag (boolean)
• rights-owner-year - Rights year
• rights-owner-name - Rights owner (max 200 characters)
• order - Track order in album (min 1, unique per album)
• full-audiofile-url - Audio file URL (max 200 characters)

Relationships

• albums - At least one album association required
• primary-genre - Primary genre classification
• language - Track language

GET /tracks/{id}

Retrieve a specific track with its complete information and relationships.

Example Response

200 OK

{
  "data": {
    "type": "tracks",
    "id": "1",
    "attributes": {
      "title": "City Lights",
      "is-explicit": false,
      "rights-owner-year": 2024,
      "rights-owner-name": "Indie Music Co.",
      "order": 1,
      "isrc-code": "US-S1Z-99-00001",
      "version": "Original Mix",
      "length": "00:03:42",
      "lyrics": "Walking through the city lights tonight...",
      "preview-start": 30,
      "publishing": "2024 Indie Music Co.",
      "full-audiofile-url": "https://storage.example.com/tracks/city-lights.wav",
      "created-at": "2024-08-01T10:00:00Z",
      "updated-at": "2024-08-15T14:30:00Z"
    },
    "relationships": {
      "albums": {
        "data": [
          { "type": "albums", "id": "1" }
        ]
      },
      "primary-genre": {
        "data": { "type": "genres", "id": "3" }
      },
      "language": {
        "data": { "type": "languages", "id": "1" }
      },
      "secondary-genre": {
        "data": { "type": "genres", "id": "8" }
      }
    }
  }

}

Include Parameters

Use the include parameter to load related resources:

?include=albums,primary-genre,language

?include=track-artists.artist,track-artists.artist-role

?include=albums.label,albums.artists

PATCH /tracks/{id}

Update specific attributes of an existing track.

Request Body Example - Update Title

{
  "data": {
    "type": "tracks",
    "id": "1",
    "attributes": {
      "title": "City Lights"
    }
  }
}

Success Response

200 OK

Other Update Examples

Update Relationships

{
  "data": {
    "type": "tracks",
    "id": "1",
    "attributes": {
      "title": "City Lights 2"
    },
    "relationships": {
      "secondary-genre": {
        "data": { "type": "genres", "id": "12" }
      }
    }
  }
}

DELETE /tracks/{id}

Remove a track from the system.

Getting Started

Core Resources

Supporting Data

Distribution

Reference

🎵 Tracks

Resource Overview

Schema

Required Attributes

Optional Attributes

Read-only Attributes

Required Relationships

Optional Relationships

Read-only Relationships

List Tracks

Query Parameters

Filtering

Other Parameters

Example Request

Success Response

Request Body

Required Fields

Attributes

Relationships

Example Response

Include Parameters

Request Body Example - Update Title

Success Response

Other Update Examples

Update Relationships

💡 Key Features & Use Cases

🎯 Key Features

📝 Common Use Cases