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, except for a music video · up to 500 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
is-video boolean Optional Marks the track as a music video. Changed only when sent. See Music Videos
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
allow-fingerprint-scan boolean Optional · default true Whether the track is sent to fingerprint DSPs (YouTube Content ID, Meta and TikTok). Send false to opt this track out; omitting it on an update leaves it unchanged. Cannot be false on a music video.

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" }
    }
  ]
}

Music Videos

is-video switches a track between a song and a music video. Its masters are managed through /track-assets.

  • • Changing the type: setting is-video to true removes the track's Dolby Atmos master and, when the track is not shared with other albums, its audio file reference (full-audiofile-url, md5); length is kept. Setting it back to false removes the video master.
  • • Clearing is-video is always allowed, except on a video release.
  • • Audio file: a music video needs no full-audiofile-url; every other track does. A release of any other format may mix songs and music videos.
  • • Video releases: every track of a release in the Video format is a music video. A track created on one without is-video is stored as a music video.
Status Code When
403 video_read_only Creating, editing or deleting a track of a video album, by an account without music videos enabled.
403 video_not_allowed Sending is-video: true from an account without music videos enabled.
422 video_track_is_shared Turning into a video a track that belongs, or would belong, to more than one album. A track that is already a video can still be edited.
422 video_release_accepts_only_videos Sending is-video: false for a track of a video release, or adding a track that is not a music video to one through /album-tracks.

Error Response Example

403 Forbidden 
{
  "errors": [
    {
      "status": "403",
      "title": "Forbidden",
      "code": "video_not_allowed",
      "detail": "This account is not enabled for music videos. Contact support to have it enabled."
    }
  ]
}

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,
        "allow-fingerprint-scan": true,
        "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