Roles

Credits: the role an artist plays on a track or a product (e.g., Vocals, Producer).

This endpoint exists so that generative AI contribution can be declared per credit, through the ai-contribution attribute. It is read and update only — credits cannot be created or deleted through the API, and ai-contribution is the only updatable attribute.

Do not confuse this with Artist Roles, the reference list of available role types, or Access Roles, which govern user permissions.

Credits are a projection. Role records are recomputed from the product's raw roles every time the product moves to active. Moving a product back to draft and re-activating it regenerates its credits and clears any declaration made here. This is intended behaviour, not a bug: a declaration set through this endpoint is not guaranteed to survive a return to draft status and has to be re-submitted after re-activation.

See Declare AI contribution.

List credits

GET

https://api.idol.io/api/v2

/roles

Retrieve the credits attached to products and tracks.

Narrow the list with filter[product-id], filter[track-id] or filter[artist-id].

List credits › query Parameters

page[number]

integer · min: 1

Page number for pagination

Default: 1

page[size]

integer · min: 1 · max: 200

Number of items per page (max 200)

Default: 20

include

string

Comma-separated list of related resources to include

filter[product-id]

string

Filter by product ID

filter[track-id]

string

Filter by track ID

filter[artist-id]

string

Filter by artist ID

List credits › Responses

Successful response

RoleListResponse

RoleResource[]

Array of resource objects (override with specific resource schema)

object[]

Related resources included in the response

PaginationMeta

PaginationLinks

Get credit details

GET

https://api.idol.io/api/v2

/roles/{id}

Retrieve a single credit by ID

Get credit details › path Parameters

id

string · required

Resource ID

Get credit details › query Parameters

include

string

Comma-separated list of related resources to include

Get credit details › Responses

Successful response

RoleResponse

RoleResource

The primary resource object (override with specific resource schema)

object[]

Related resources included in the response

object

GET/roles/{id}

curl https://api.idol.io/api/v2/roles/:id \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": {
    "type": "roles",
    "id": "id",
    "attributes": {
      "name": "Vocals",
      "position": 0,
      "ai-contribution": "undeclared"
    },
    "relationships": {
      "artist": {
        "data": {
          "type": "type",
          "id": "id"
        },
        "links": {
          "self": "https://www.example.com/path/to/resource",
          "related": "https://www.example.com/path/to/resource"
        }
      },
      "track": {
        "data": {
          "type": "type",
          "id": "id"
        },
        "links": {
          "self": "https://www.example.com/path/to/resource",
          "related": "https://www.example.com/path/to/resource"
        }
      },
      "product": {
        "data": {
          "type": "type",
          "id": "id"
        },
        "links": {
          "self": "https://www.example.com/path/to/resource",
          "related": "https://www.example.com/path/to/resource"
        }
      }
    }
  },
  "included": [
    {}
  ],
  "links": {
    "self": "https://www.example.com/path/to/resource"
  }
}

json

application/vnd.api+json

Declare AI contribution on a credit

PATCH

https://api.idol.io/api/v2

/roles/{id}

Update the AI contribution declared for a credit.

ai-contribution is the only updatable attribute. name, position and the artist, track and product relationships are read-only: a payload that tries to change any of them is rejected with a 400 Bad Request (Field not updatable) rather than being silently ignored.

Omitting ai-contribution is a no-op. Sending undeclared resets the declaration. See Declare AI contribution.

Credits are regenerated. Role records are recomputed from the product's raw roles every time the product moves to active. Moving a product back to draft and re-activating it regenerates its credits and clears the declarations made here, which then have to be re-submitted.

Declare AI contribution on a credit › path Parameters

id

string · required

Resource ID

Declare AI contribution on a credit › Request Body

RoleUpdateRequest

RoleResource · required

Declare AI contribution on a credit › Responses

Credit updated successfully

RoleResponse

RoleResource

The primary resource object (override with specific resource schema)

object[]

Related resources included in the response

object

PATCH/roles/{id}

curl https://api.idol.io/api/v2/roles/:id \
  --request PATCH \
  --header 'Content-Type: application/vnd.api+json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "data": {
    "type": "roles",
    "id": "99e73ff1b87f37d1198ed50240796c18f1d2588c",
    "attributes": {
      "ai-contribution": "partly"
    }
  }
}'

Example Request Body

{
  "data": {
    "type": "roles",
    "id": "99e73ff1b87f37d1198ed50240796c18f1d2588c",
    "attributes": {
      "ai-contribution": "partly"
    }
  }
}

json

application/vnd.api+json

Example Responses

{
  "data": {
    "type": "roles",
    "id": "id",
    "attributes": {
      "name": "Vocals",
      "position": 0,
      "ai-contribution": "undeclared"
    },
    "relationships": {
      "artist": {
        "data": {
          "type": "type",
          "id": "id"
        },
        "links": {
          "self": "https://www.example.com/path/to/resource",
          "related": "https://www.example.com/path/to/resource"
        }
      },
      "track": {
        "data": {
          "type": "type",
          "id": "id"
        },
        "links": {
          "self": "https://www.example.com/path/to/resource",
          "related": "https://www.example.com/path/to/resource"
        }
      },
      "product": {
        "data": {
          "type": "type",
          "id": "id"
        },
        "links": {
          "self": "https://www.example.com/path/to/resource",
          "related": "https://www.example.com/path/to/resource"
        }
      }
    }
  },
  "included": [
    {}
  ],
  "links": {
    "self": "https://www.example.com/path/to/resource"
  }
}

json

application/vnd.api+json

Artist Roles Import Tasks

Labelcamp API v2

Roles

Credits: the role an artist plays on a track or a product (e.g., Vocals, Producer).

Do not confuse this with Artist Roles, the reference list of available role types, or Access Roles, which govern user permissions.

See Declare AI contribution.

List credits

GET

https://api.idol.io/api/v2

/roles

Retrieve the credits attached to products and tracks.

Narrow the list with filter[product-id], filter[track-id] or filter[artist-id].

List credits › query Parameters

page[number]

integer · min: 1

Page number for pagination

Default: 1

page[size]

integer · min: 1 · max: 200

Number of items per page (max 200)

Default: 20

include

string

Comma-separated list of related resources to include

filter[product-id]

string

Filter by product ID

filter[track-id]

string

Filter by track ID

filter[artist-id]

string

Filter by artist ID

List credits › Responses

Successful response

RoleListResponse

RoleResource[]

Array of resource objects (override with specific resource schema)

object[]

Related resources included in the response

PaginationMeta

PaginationLinks

Get credit details

GET

https://api.idol.io/api/v2

/roles/{id}

Retrieve a single credit by ID

Get credit details › path Parameters

id

string · required

Resource ID

Get credit details › query Parameters

include

string

Comma-separated list of related resources to include

Get credit details › Responses

Successful response

RoleResponse

RoleResource

The primary resource object (override with specific resource schema)

object[]

Related resources included in the response

object

GET/roles/{id}

curl https://api.idol.io/api/v2/roles/:id \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": {
    "type": "roles",
    "id": "id",
    "attributes": {
      "name": "Vocals",
      "position": 0,
      "ai-contribution": "undeclared"
    },
    "relationships": {
      "artist": {
        "data": {
          "type": "type",
          "id": "id"
        },
        "links": {
          "self": "https://www.example.com/path/to/resource",
          "related": "https://www.example.com/path/to/resource"
        }
      },
      "track": {
        "data": {
          "type": "type",
          "id": "id"
        },
        "links": {
          "self": "https://www.example.com/path/to/resource",
          "related": "https://www.example.com/path/to/resource"
        }
      },
      "product": {
        "data": {
          "type": "type",
          "id": "id"
        },
        "links": {
          "self": "https://www.example.com/path/to/resource",
          "related": "https://www.example.com/path/to/resource"
        }
      }
    }
  },
  "included": [
    {}
  ],
  "links": {
    "self": "https://www.example.com/path/to/resource"
  }
}

json

application/vnd.api+json

Declare AI contribution on a credit

PATCH

https://api.idol.io/api/v2

/roles/{id}

Update the AI contribution declared for a credit.

Omitting ai-contribution is a no-op. Sending undeclared resets the declaration. See Declare AI contribution.

Declare AI contribution on a credit › path Parameters

id

string · required

Resource ID

Declare AI contribution on a credit › Request Body

RoleUpdateRequest

RoleResource · required

Declare AI contribution on a credit › Responses

Credit updated successfully

RoleResponse

RoleResource

The primary resource object (override with specific resource schema)

object[]

Related resources included in the response

object

PATCH/roles/{id}

curl https://api.idol.io/api/v2/roles/:id \
  --request PATCH \
  --header 'Content-Type: application/vnd.api+json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "data": {
    "type": "roles",
    "id": "99e73ff1b87f37d1198ed50240796c18f1d2588c",
    "attributes": {
      "ai-contribution": "partly"
    }
  }
}'

Example Request Body

{
  "data": {
    "type": "roles",
    "id": "99e73ff1b87f37d1198ed50240796c18f1d2588c",
    "attributes": {
      "ai-contribution": "partly"
    }
  }
}

json

application/vnd.api+json

Example Responses

{
  "data": {
    "type": "roles",
    "id": "id",
    "attributes": {
      "name": "Vocals",
      "position": 0,
      "ai-contribution": "undeclared"
    },
    "relationships": {
      "artist": {
        "data": {
          "type": "type",
          "id": "id"
        },
        "links": {
          "self": "https://www.example.com/path/to/resource",
          "related": "https://www.example.com/path/to/resource"
        }
      },
      "track": {
        "data": {
          "type": "type",
          "id": "id"
        },
        "links": {
          "self": "https://www.example.com/path/to/resource",
          "related": "https://www.example.com/path/to/resource"
        }
      },
      "product": {
        "data": {
          "type": "type",
          "id": "id"
        },
        "links": {
          "self": "https://www.example.com/path/to/resource",
          "related": "https://www.example.com/path/to/resource"
        }
      }
    }
  },
  "included": [
    {}
  ],
  "links": {
    "self": "https://www.example.com/path/to/resource"
  }
}

json

application/vnd.api+json

Artist Roles Import Tasks