Credit Roles

Catalog of instruments and additional roles that can be credited on a track

Resource Overview

Credit Roles list every instrument (e.g., "violin", "acoustic-guitar") and every additional role (e.g., "engineer", "co-producer") that a track can credit beyond the core artist roles. This is a read-only reference resource: use the key of a role when you send the extended-credits attribute of a track.

The list returns the roles you can use for a new extended credit. Core artist roles (e.g., "producer", "composer") are not in it: credit them through track artists.

Base Endpoint
/credit-roles
Resource Type
credit-roles
Access Mode
Read-only Reference

Schema

Attributes

Field Type Visibility Description
key string Public Sortable Stable machine-readable identifier (e.g., "violin", "engineer"). This is the value you send as role in a track's extended-credits
name string Public Sortable Display name (e.g., "Violin", "Engineer")
kind string Public Sortable Either role or instrument. Both kinds are credited the same way

Available Filters

By ID

filter[id]=1,2,3

Filter by specific credit role IDs (comma-separated)

By Key

filter[key]=violin

Filter by an exact role key (up to 64 characters)

By Kind

filter[kind]=instrument

Either role or instrument

Relationships

This resource exposes no relationships and supports no include paths. Credits that use a role are listed under track credits (filter[role]={key}).

API Endpoints

List Credit Roles

GET
GET /credit-roles

Query Parameters

filter[id] - Filter by credit role IDs
filter[key] - Filter by role key
filter[kind] - role or instrument
sort - Sort by: kind, name, key (default: roles first, then instruments, each by name)
page[number] - Page number (default: 1)
page[size] - Items per page (default: 500, max: 500)

Example Request

GET /credit-roles?filter[kind]=instrument&sort=name

Example Response

{
  "data": [
    {
      "type": "credit-roles",
      "id": "41",
      "attributes": {
        "key": "acoustic-guitar",
        "name": "Acoustic Guitar",
        "kind": "instrument"
      }
    },
    {
      "type": "credit-roles",
      "id": "118",
      "attributes": {
        "key": "violin",
        "name": "Violin",
        "kind": "instrument"
      }
    }
  ],
  "meta": {
    "page": {
      "currentPage": 1,
      "from": 1,
      "lastPage": 1,
      "perPage": 500,
      "to": 2,
      "total": 2
    }
  }
}

Get Credit Role

GET
GET /credit-roles/{id}

Path Parameters

id (required) - The ID of the credit role to retrieve

Example Request

GET /credit-roles/118

Example Response

{
  "data": {
    "type": "credit-roles",
    "id": "118",
    "attributes": {
      "key": "violin",
      "name": "Violin",
      "kind": "instrument"
    }
  }
}

Any role can be retrieved by ID, including one no longer listed by GET /credit-roles, such as the role of a credit a track already has.

Common Credit Roles

The catalog includes instruments and additional roles. Here are some common examples; list them all with GET /credit-roles:

violin

Violin

acoustic-guitar

Acoustic guitar

piano

Piano

mixing-engineer

Mixing engineer

mastering-engineer

Mastering engineer

co-producer

Co-producer

Usage Examples

Get Roles Available for New Credits

GET /credit-roles

Get Instruments Only

GET /credit-roles?filter[kind]=instrument

Using in Track Credits

Send the role key in the extended-credits attribute when creating or updating a track:

Request Body Example

{
  "data": {
    "type": "tracks",
    "id": "5",
    "attributes": {
      "extended-credits": [
        { "role": "violin", "name": "Ana Pérez", "artist-id": null, "position": 1 },
        { "role": "engineer", "name": "Studio X", "artist-id": 12 }
      ]
    }
  }
}

A credit the track already has can be sent again unchanged even if its role is no longer listed in GET /credit-roles.

Artist Roles

Reference Resources

Album Formats