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 · up to 300 characters Track title
is-explicit boolean Required Explicit content flag
rights-owner-year integer Required · 1900 or later Rights ownership year
rights-owner-name string Required · up to 200 characters Rights owner name
order integer Required · 1 or greater · unique per album Track order within album
full-audiofile-url string Required · up to 200 characters Full audio file URL

Optional Attributes

Field Type Validation Description
isrc-code string Optional · up to 100 characters International Standard Recording Code
version-description string Optional · up to 200 characters Version as free text (e.g., "Radio Edit", "Extended"). Takes priority over version relationship — if set, version_id is cleared automatically.
length string Optional · time format Track duration (HH:MM:SS)
lyrics string Optional Track lyrics
preview-start integer Optional · 0 or greater Preview start time in seconds
extended-credits array Optional · up to 200 items Instrument and additional role credits, as a list of {role, name, artist-id, position} objects. Sending it replaces the track's full set; omitting it leaves the credits untouched. See Extended Credits

Read-only Attributes

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

Required Relationships

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

Optional Relationships

Relationship Related Resource Description
secondary-genre genres Secondary genre classification
track-artists track-artists Artist associations with roles
version versions Version type reference (from predefined list). Alternative to version-description attribute.
artists artists Direct artist associations

Version: two ways to set it

  • • Free text: Use the version-description attribute to enter any version text (e.g., "Radio Edit", "Extended Mix").
  • • Predefined: Use the version relationship to select from the predefined versions list.
  • • If both are sent in the same request, free text takes priority and the version relationship is cleared automatically.
  • • If only the relationship is sent, the version text is auto-populated from the selected version name.

Read-only Relationships

Relationship Related Resource Description
user users Track owner (auto-assigned)
album-tracks album-tracks Album tracks

Extended Credits

The extended-credits attribute carries the credits of a track beyond the core artist roles: instruments and additional roles such as engineer or co-producer. It can be sent on POST /tracks and PATCH /tracks/{id}, and it is returned on every track read. Each credit can also be read as a track credit resource.

Item Shape

Member Type Validation Description
role string Required A key from credit roles (e.g., "violin")
name string Required · 1 to 255 characters Name of the credited person or entity
artist-id integer | null Optional · positive integer Optional. ID of one of your artists, for your own reference. Send a JSON number or null
position integer | null Optional · 1 or greater Order of the credit within its role

Write Rules

  • • Omitted: a PATCH without extended-credits leaves the track's credits untouched.
  • • Sent: the list replaces the track's full set of extended credits. Always send every credit you want to keep.
  • • Empty array: [] removes all extended credits. null is rejected.
  • • Positions: renumbered 1..n within each role, ordered by the position you send; items without one go last, in the order they appear in the list.
  • • Accepted roles: any role listed by GET /credit-roles. Core artist roles (e.g., producer, composer) are never accepted here; use track artists.
  • • Credits already on the track: a credit the track already has can be sent again unchanged even if its role is no longer listed in GET /credit-roles.
  • • Artist reference: artist-id must be one of your artists.
  • • No duplicates: the same name cannot appear twice under the same role (names compared case-insensitively), whatever the artist-id.
  • • All errors at once: every invalid item is reported in a single 422 response, and nothing is saved.

Validation Errors

Each error points at the offending item through source.pointer, using its index in the list starting at 0 (e.g., /data/attributes/extended-credits/0/role).

Error Response Example

422 Unprocessable Entity 
{
  "errors": [
    {
      "status": "422",
      "detail": "Unknown credit role \"guitarr\". See GET /credit-roles.",
      "source": { "pointer": "/data/attributes/extended-credits/0/role" }
    },
    {
      "status": "422",
      "detail": "The name is required and must be 1 to 255 characters.",
      "source": { "pointer": "/data/attributes/extended-credits/1/name" }
    }
  ]
}

Related Endpoints

Endpoint Method Description Documentation
/tracks/{id}/trends GET Get performance trends for a track (plays by date, DSP, country, album) View Trends →
/track-credits?filter[track]={id} GET List a track's extended credits as individual resources (read-only) View Track Credits →
/credit-roles GET Catalog of role keys accepted in extended-credits View Credit Roles →

List Tracks

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

Query Parameters

Filtering

  • • filter[title] - Filter by track title (partial match)
  • • filter[is-explicit] - Filter by explicit content flag (true/false)
  • • filter[order] - Filter by track order within album
  • • filter[rights-owner-year] - Filter by rights ownership year
  • • filter[primary-genre] - Filter by primary genre ID
  • • filter[isrc-code] - Filter by ISRC code (exact match)
  • • filter[album] - Filter by album ID to get all tracks from a specific album
  • • filter[created-at-gte] - Filter tracks created on or after date (YYYY-MM-DD)
  • • filter[created-at-lte] - Filter tracks created on or before date (YYYY-MM-DD)

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-description": "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",
      "extended-credits": [
        { "role": "violin", "name": "Ana Pérez", "artist-id": null, "position": 1 },
        { "role": "engineer", "name": "Studio X", "artist-id": 12 }
      ]
    },
    "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-description": "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",
      "extended-credits": [
        { "role": "engineer", "name": "Studio X", "artist-id": 12, "position": 1 },
        { "role": "violin", "name": "Ana Pérez", "artist-id": null, "position": 1 }
      ],
      "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" }
      }
    }
  }
}
Replace Extended Credits
{
  "data": {
    "type": "tracks",
    "id": "1",
    "attributes": {
      "extended-credits": [
        { "role": "violin", "name": "Ana Pérez", "artist-id": null, "position": 1 },
        { "role": "violin", "name": "Marc Duval", "position": 2 },
        { "role": "engineer", "name": "Studio X", "artist-id": 12 }
      ]
    }
  }
}
Remove All Extended Credits
{
  "data": {
    "type": "tracks",
    "id": "1",
    "attributes": {
      "extended-credits": []
    }
  }
}
DELETE /tracks/{id}

Remove a track from the system.

Key Features & Use Cases

Key Features

  • • Multi-album associations support
  • • Comprehensive metadata management
  • • Explicit content classification
  • • Track ordering within albums
  • • Rights ownership tracking
  • • Audio file URL management
  • • ISRC code support
  • • Lyrics and preview handling
  • • Instrument and role credits

Common Use Cases

  • • Adding songs to albums
  • • Managing track metadata and lyrics
  • • Handling compilation albums
  • • Organizing track sequences
  • • Content classification and rights
  • • Multi-format releases (Single + Album)
  • • Track version management
  • • Audio file quality control